From 11a94d7611bd3d063403dd6f424c07f4b3cc2128 Mon Sep 17 00:00:00 2001
From: Jurriaan Pruijs <jurriaan@pruijs.nl>
Date: Fri, 19 Jan 2024 15:14:22 +0100
Subject: [PATCH] docs(ics21): add spec to lib mapping

---
 lib/ics23/README.md     | 124 ++++++++++++++++++++++++++++++++++++++++
 lib/ics23/src/verify.rs |   2 +
 2 files changed, 126 insertions(+)
 create mode 100644 lib/ics23/README.md

diff --git a/lib/ics23/README.md b/lib/ics23/README.md
new file mode 100644
index 0000000000..ba17d1cdcf
--- /dev/null
+++ b/lib/ics23/README.md
@@ -0,0 +1,124 @@
+# ICS-23 specification mapping
+
+Below an overview of all data types from the [ICS-23 specification](https://github.com/cosmos/ibc/tree/main/spec/core/ics-023-vector-commitments#datatypes) and how they're implemented.
+
+## CommitmentState
+
+spec: `object`  
+impl: _not implemented_
+
+## CommitmentRoot
+
+spec: `object`  
+impl: `[u8]`
+
+## CommitmentPath
+
+spec: `object`  
+impl: `[u8]`
+
+## CommitmentPrefix
+
+spec: `object`  
+impl: _not implemented_
+
+### applyPrefix
+
+spec: `applyPrefix = (prefix: CommitmentPrefix, path: CommitmentPath) => CommitmentPath`  
+impl: _not implemented_
+
+### removePrefix
+
+spec: `removePrefix = (prefix: CommitmentPrefix, path: commitmentPath) => Path`  
+impl: _not implemented_
+
+## Path
+
+spec: `string`  
+impl: `[u8]`
+
+## Value
+
+spec: `[]byte`  
+impl: `[u8]`
+
+## CommitmentProof
+
+spec: `object`  
+impl:
+
+- `existence_proof.rs (from lib/unionlabs) # ExistenceProof`
+- `non_existence_proof.rs (from lib/unionlabs) # NonExistenceProof`
+
+### generate
+
+spec: `(initial: Map<Path, Value>) => CommitmentState`  
+impl: _not implemented_
+
+### calculateRoot
+
+spec: `(state: CommitmentState) => CommitmentRoot`  
+impl: _not implemented_.  
+(NOTE: `existence_proof.rs # calculate_root` seems to do this, but it has an `ExistenceProof` as argument, not a `CommitmentState`)
+
+### set
+
+spec: `(state: CommitmentState, path: Path, value: Value) => CommitmentState`  
+impl: _not implemented_
+
+### remove
+
+spec `(state: CommitmentState, path: Path) => CommitmentState`  
+impl: _not implemented_
+
+### createMembershipProof
+
+spec: `(state: CommitmentState, path: CommitmentPath, value: Value) => CommitmentProof`  
+impl: _not implemented_
+
+### createNonMembershipProof
+
+spec: `(state: CommitmentState, path: CommitmentPath) => CommitmentProof`  
+impl: _not implemented_
+
+### verifyMembership
+
+spec: `(root: CommitmentRoot, proof: CommitmentProof, path: CommitmentPath, value: Value) => boolean`  
+impl:
+
+```rust
+// verify.rs:
+verify_membership(
+    spec: &ProofSpec,
+    root: &[u8],
+    proof: &ExistenceProof,
+    key: &[u8],
+    value: &[u8]
+) -> Result<(), VerifyMembershipError>
+```
+
+### verifyNonMembership
+
+spec: `(root: CommitmentRoot, proof: CommitmentProof, path: CommitmentPath) => boolean`  
+impl:
+
+```rust
+// verify.rs:
+verify_membership(
+    spec: &ProofSpec,
+    root: &[u8],
+    proof: &ExistenceProof,
+    key: &[u8],
+    value: &[u8],
+) -> Result<(), VerifyMembershipError>
+```
+
+### batchVerifyMembership (optional)
+
+spec: `(root: CommitmentRoot, proof: CommitmentProof, items: Map<CommitmentPath, Value>) => boolean`  
+impl: _not implemented_
+
+### batchVerifyNonMembership (optional)
+
+spec: `(root: CommitmentRoot, proof: CommitmentProof, paths: Set<CommitmentPath>) => boolean`  
+impl: _not implemented_
diff --git a/lib/ics23/src/verify.rs b/lib/ics23/src/verify.rs
index 3546f2c6c3..a03f260c8e 100644
--- a/lib/ics23/src/verify.rs
+++ b/lib/ics23/src/verify.rs
@@ -76,6 +76,7 @@ pub enum NeighborSearchError {
     InvalidPath,
 }
 
+/// Implements ICS-23 verifyNonMembership: verifies a proof that a path has not been set to any value in a commitment.
 pub fn verify_non_membership(
     spec: &ProofSpec,
     root: &[u8],
@@ -86,6 +87,7 @@ pub fn verify_non_membership(
         .map_err(VerifyMembershipError::ExistenceProofVerify)
 }
 
+/// Implements ICS-23 verifyMembership: verifies a proof that a path has been set to a particular value in a commitment.
 pub fn verify_membership(
     spec: &ProofSpec,
     root: &[u8],