injectivejs 1.11.13 → 1.11.15

package/cosmos/ics23/v1/proofs.js

@@ -187,6 +187,30 @@ function createBaseExistenceProof() {
         path: []
     };
 }
+/**
+ * ExistenceProof takes a key and a value and a set of steps to perform on it.
+ * The result of peforming all these steps will provide a "root hash", which can
+ * be compared to the value in a header.
+ *
+ * Since it is computationally infeasible to produce a hash collission for any of the used
+ * cryptographic hash functions, if someone can provide a series of operations to transform
+ * a given key and value into a root hash that matches some trusted root, these key and values
+ * must be in the referenced merkle tree.
+ *
+ * The only possible issue is maliablity in LeafOp, such as providing extra prefix data,
+ * which should be controlled by a spec. Eg. with lengthOp as NONE,
+ * prefix = FOO, key = BAR, value = CHOICE
+ * and
+ * prefix = F, key = OOBAR, value = CHOICE
+ * would produce the same value.
+ *
+ * With LengthOp this is tricker but not impossible. Which is why the "leafPrefixEqual" field
+ * in the ProofSpec is valuable to prevent this mutability. And why all trees should
+ * length-prefix the data before hashing it.
+ * @name ExistenceProof
+ * @package cosmos.ics23.v1
+ * @see proto type: cosmos.ics23.v1.ExistenceProof
+ */
 exports.ExistenceProof = {
     typeUrl: "/cosmos.ics23.v1.ExistenceProof",
     aminoType: "cosmos-sdk/ExistenceProof",
@@ -308,6 +332,14 @@ function createBaseNonExistenceProof() {
         right: undefined
     };
 }
+/**
+ * NonExistenceProof takes a proof of two neighbors, one left of the desired key,
+ * one right of the desired key. If both proofs are valid AND they are neighbors,
+ * then there is no valid proof for the given key.
+ * @name NonExistenceProof
+ * @package cosmos.ics23.v1
+ * @see proto type: cosmos.ics23.v1.NonExistenceProof
+ */
 exports.NonExistenceProof = {
     typeUrl: "/cosmos.ics23.v1.NonExistenceProof",
     aminoType: "cosmos-sdk/NonExistenceProof",
@@ -415,6 +447,12 @@ function createBaseCommitmentProof() {
         compressed: undefined
     };
 }
+/**
+ * CommitmentProof is either an ExistenceProof or a NonExistenceProof, or a Batch of such messages
+ * @name CommitmentProof
+ * @package cosmos.ics23.v1
+ * @see proto type: cosmos.ics23.v1.CommitmentProof
+ */
 exports.CommitmentProof = {
     typeUrl: "/cosmos.ics23.v1.CommitmentProof",
     aminoType: "cosmos-sdk/CommitmentProof",
@@ -537,6 +575,25 @@ function createBaseLeafOp() {
         prefix: new Uint8Array()
     };
 }
+/**
+ * LeafOp represents the raw key-value data we wish to prove, and
+ * must be flexible to represent the internal transformation from
+ * the original key-value pairs into the basis hash, for many existing
+ * merkle trees.
+ *
+ * key and value are passed in. So that the signature of this operation is:
+ * leafOp(key, value) -> output
+ *
+ * To process this, first prehash the keys and values if needed (ANY means no hash in this case):
+ * hkey = prehashKey(key)
+ * hvalue = prehashValue(value)
+ *
+ * Then combine the bytes, and hash it
+ * output = hash(prefix || length(hkey) || hkey || length(hvalue) || hvalue)
+ * @name LeafOp
+ * @package cosmos.ics23.v1
+ * @see proto type: cosmos.ics23.v1.LeafOp
+ */
 exports.LeafOp = {
     typeUrl: "/cosmos.ics23.v1.LeafOp",
     aminoType: "cosmos-sdk/LeafOp",
@@ -660,6 +717,26 @@ function createBaseInnerOp() {
         suffix: new Uint8Array()
     };
 }
+/**
+ * InnerOp represents a merkle-proof step that is not a leaf.
+ * It represents concatenating two children and hashing them to provide the next result.
+ *
+ * The result of the previous step is passed in, so the signature of this op is:
+ * innerOp(child) -> output
+ *
+ * The result of applying InnerOp should be:
+ * output = op.hash(op.prefix || child || op.suffix)
+ *
+ * where the || operator is concatenation of binary data,
+ * and child is the result of hashing all the tree below this step.
+ *
+ * Any special data, like prepending child with the length, or prepending the entire operation with
+ * some value to differentiate from leaf nodes, should be included in prefix and suffix.
+ * If either of prefix or suffix is empty, we just treat it as an empty string
+ * @name InnerOp
+ * @package cosmos.ics23.v1
+ * @see proto type: cosmos.ics23.v1.InnerOp
+ */
 exports.InnerOp = {
     typeUrl: "/cosmos.ics23.v1.InnerOp",
     aminoType: "cosmos-sdk/InnerOp",
@@ -763,6 +840,21 @@ function createBaseProofSpec() {
         prehashKeyBeforeComparison: false
     };
 }
+/**
+ * ProofSpec defines what the expected parameters are for a given proof type.
+ * This can be stored in the client and used to validate any incoming proofs.
+ *
+ * verify(ProofSpec, Proof) -> Proof | Error
+ *
+ * As demonstrated in tests, if we don't fix the algorithm used to calculate the
+ * LeafHash for a given tree, there are many possible key-value pairs that can
+ * generate a given hash (by interpretting the preimage differently).
+ * We need this for proper security, requires client knows a priori what
+ * tree format server uses. But not in code, rather a configuration object.
+ * @name ProofSpec
+ * @package cosmos.ics23.v1
+ * @see proto type: cosmos.ics23.v1.ProofSpec
+ */
 exports.ProofSpec = {
     typeUrl: "/cosmos.ics23.v1.ProofSpec",
     aminoType: "cosmos-sdk/ProofSpec",
@@ -895,6 +987,19 @@ function createBaseInnerSpec() {
         hash: 0
     };
 }
+/**
+ * InnerSpec contains all store-specific structure info to determine if two proofs from a
+ * given store are neighbors.
+ *
+ * This enables:
+ *
+ * isLeftMost(spec: InnerSpec, op: InnerOp)
+ * isRightMost(spec: InnerSpec, op: InnerOp)
+ * isLeftNeighbor(spec: InnerSpec, left: InnerOp, right: InnerOp)
+ * @name InnerSpec
+ * @package cosmos.ics23.v1
+ * @see proto type: cosmos.ics23.v1.InnerSpec
+ */
 exports.InnerSpec = {
     typeUrl: "/cosmos.ics23.v1.InnerSpec",
     aminoType: "cosmos-sdk/InnerSpec",
@@ -1040,6 +1145,12 @@ function createBaseBatchProof() {
         entries: []
     };
 }
+/**
+ * BatchProof is a group of multiple proof types than can be compressed
+ * @name BatchProof
+ * @package cosmos.ics23.v1
+ * @see proto type: cosmos.ics23.v1.BatchProof
+ */
 exports.BatchProof = {
     typeUrl: "/cosmos.ics23.v1.BatchProof",
     aminoType: "cosmos-sdk/BatchProof",
@@ -1126,6 +1237,12 @@ function createBaseBatchEntry() {
         nonexist: undefined
     };
 }
+/**
+ * Use BatchEntry not CommitmentProof, to avoid recursion
+ * @name BatchEntry
+ * @package cosmos.ics23.v1
+ * @see proto type: cosmos.ics23.v1.BatchEntry
+ */
 exports.BatchEntry = {
     typeUrl: "/cosmos.ics23.v1.BatchEntry",
     aminoType: "cosmos-sdk/BatchEntry",
@@ -1221,6 +1338,11 @@ function createBaseCompressedBatchProof() {
         lookupInners: []
     };
 }
+/**
+ * @name CompressedBatchProof
+ * @package cosmos.ics23.v1
+ * @see proto type: cosmos.ics23.v1.CompressedBatchProof
+ */
 exports.CompressedBatchProof = {
     typeUrl: "/cosmos.ics23.v1.CompressedBatchProof",
     aminoType: "cosmos-sdk/CompressedBatchProof",
@@ -1322,6 +1444,12 @@ function createBaseCompressedBatchEntry() {
         nonexist: undefined
     };
 }
+/**
+ * Use BatchEntry not CommitmentProof, to avoid recursion
+ * @name CompressedBatchEntry
+ * @package cosmos.ics23.v1
+ * @see proto type: cosmos.ics23.v1.CompressedBatchEntry
+ */
 exports.CompressedBatchEntry = {
     typeUrl: "/cosmos.ics23.v1.CompressedBatchEntry",
     aminoType: "cosmos-sdk/CompressedBatchEntry",
@@ -1419,6 +1547,11 @@ function createBaseCompressedExistenceProof() {
         path: []
     };
 }
+/**
+ * @name CompressedExistenceProof
+ * @package cosmos.ics23.v1
+ * @see proto type: cosmos.ics23.v1.CompressedExistenceProof
+ */
 exports.CompressedExistenceProof = {
     typeUrl: "/cosmos.ics23.v1.CompressedExistenceProof",
     aminoType: "cosmos-sdk/CompressedExistenceProof",
@@ -1549,6 +1682,11 @@ function createBaseCompressedNonExistenceProof() {
         right: undefined
     };
 }
+/**
+ * @name CompressedNonExistenceProof
+ * @package cosmos.ics23.v1
+ * @see proto type: cosmos.ics23.v1.CompressedNonExistenceProof
+ */
 exports.CompressedNonExistenceProof = {
     typeUrl: "/cosmos.ics23.v1.CompressedNonExistenceProof",
     aminoType: "cosmos-sdk/CompressedNonExistenceProof",