github.com/badrootd/nibiru-cometbft@v0.37.5-0.20240307173500-2a75559eee9b/docs/architecture/adr-026-general-merkle-proof.md (about)

     1  # ADR 026: General Merkle Proof
     2  
     3  ## Context
     4  
     5  We are using raw `[]byte` for merkle proofs in `abci.ResponseQuery`. It makes hard to handle multilayer merkle proofs and general cases. Here, new interface `ProofOperator` is defined. The users can defines their own Merkle proof format and layer them easily. 
     6  
     7  Goals:
     8  - Layer Merkle proofs without decoding/reencoding
     9  - Provide general way to chain proofs
    10  - Make the proof format extensible, allowing thirdparty proof types
    11  
    12  ## Decision
    13  
    14  ### ProofOperator
    15  
    16  `type ProofOperator` is an interface for Merkle proofs. The definition is:
    17  
    18  ```go
    19  type ProofOperator interface {
    20      Run([][]byte) ([][]byte, error)
    21      GetKey() []byte
    22      ProofOp() ProofOp
    23  }
    24  ```
    25  
    26  Since a proof can treat various data type, `Run()` takes `[][]byte` as the argument, not `[]byte`. For example, a range proof's `Run()` can take multiple key-values as its argument. It will then return the root of the tree for the further process, calculated with the input value.
    27  
    28  `ProofOperator` does not have to be a Merkle proof - it can be a function that transforms the argument for intermediate process e.g. prepending the length to the `[]byte`.
    29  
    30  ### ProofOp
    31  
    32  `type ProofOp` is a protobuf message which is a triple of `Type string`, `Key []byte`, and `Data []byte`. `ProofOperator` and `ProofOp`are interconvertible, using `ProofOperator.ProofOp()` and `OpDecoder()`, where `OpDecoder` is a function that each proof type can register for their own encoding scheme. For example, we can add an byte for encoding scheme before the serialized proof, supporting JSON decoding.
    33  
    34  ## Status
    35  
    36  Implemented
    37  
    38  ## Consequences
    39  
    40  ### Positive
    41  
    42  - Layering becomes easier (no encoding/decoding at each step)
    43  - Thirdparty proof format is available
    44  
    45  ### Negative 
    46  
    47  - Larger size for abci.ResponseQuery
    48  - Unintuitive proof chaining(it is not clear what `Run()` is doing)
    49  - Additional codes for registering `OpDecoder`s