github.com/ethereum-optimism/optimism@v1.7.2/packages/contracts-bedrock/scripts/go-ffi/README.md (about)

     1  # `ctb-go-ffi`
     2  
     3  A lightweight binary for utilities accessed via `forge`'s `ffi` cheatcode in the `contracts-bedrock` test suite.
     4  
     5  <pre>
     6  ├── go-ffi
     7  │   ├── <a href="./bin.go">bin</a>: `go-ffi`'s binary
     8  │   ├── <a href="./trie.go">trie</a>: Utility for generating random merkle trie roots / inclusion proofs
     9  │   └── <a href="./differential-testing.go">diff-testing</a>: Utility for differential testing Solidity implementations against their respective Go implementations.
    10  </pre>
    11  
    12  ## Usage
    13  
    14  To build, run `pnpm build:go-ffi` from this directory or the `contract-bedrock` package.
    15  
    16  ### In a Forge Test
    17  
    18  To use `go-ffi` in a forge test, simply invoke the binary via the `vm.ffi` cheatcode.
    19  
    20  ```solidity
    21  function myFFITest() public {
    22      string[] memory commands = new string[](3);
    23      commands[0] = "./scripts/go-ffi/go-ffi";
    24      commands[1] = "trie";
    25      commands[2] = "valid";
    26      bytes memory result = vm.ffi(commands);
    27  
    28      // Do something with the result of the command
    29  }
    30  ```
    31  
    32  ### Available Modes
    33  
    34  There are two modes available in `go-ffi`: `diff` and `trie`. Each are present as a subcommand to the `go-ffi` binary, with their own set of variants.
    35  
    36  #### `diff`
    37  
    38  > **Note**
    39  > Variant required for diff mode.
    40  
    41  | Variant                               | Description                                                                                                        |
    42  | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------
    43  | `decodeVersionedNonce`                | Decodes a versioned nonce and prints the decoded arguments                                                         |
    44  | `encodeCrossDomainMessage`            | Encodes a cross domain message and prints the encoded message                                                      |
    45  | `hashCrossDomainMessage`              | Encodes and hashes a cross domain message and prints the digest                                                    |
    46  | `hashDepositTransaction`              | Encodes and hashes a deposit transaction and prints the digest                                                     |
    47  | `encodeDepositTransaction`            | RLP encodes a deposit transaction                                                                                  |
    48  | `hashWithdrawal`                      | Hashes a withdrawal message and prints the digest                                                                  |
    49  | `hashOutputRootProof`                 | Hashes an output root proof and prints the digest                                                                  |
    50  | `getProveWithdrawalTransactionInputs` | Generates the inputs for a `getProveWithdrawalTransaction` call to the `OptimismPortal` given a withdrawal message |
    51  | `cannonMemoryProof`                   | Computes a merkle proof of Cannon's memory                                                                         |
    52  
    53  #### `trie`
    54  
    55  > **Note**
    56  > Variant required for `trie` mode.
    57  
    58  | Variant                       | Description                                                                                                                               |
    59  | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
    60  | `valid`                       | Generate a test case with a valid proof of inclusion for the k/v pair in the trie.                                                        |
    61  | `extra_proof_elems`           | Generate an invalid test case with an extra proof element attached to an otherwise valid proof of inclusion for the passed k/v.           |
    62  | `corrupted_proof`             | Generate an invalid test case where the proof is malformed.                                                                               |
    63  | `invalid_data_remainder`      | Generate an invalid test case where a random element of the proof has more bytes than the length designates within the RLP list encoding. |
    64  | `invalid_large_internal_hash` | Generate an invalid test case where a long proof element is incorrect for the root.                                                       |
    65  | `invalid_internal_node_hash`  | Generate an invalid test case where a small proof element is incorrect for the root.                                                      |
    66  | `prefixed_valid_key`          | Generate a valid test case with a key that has been given a random prefix                                                                 |
    67  | `empty_key`                   | Generate a valid test case with a proof of inclusion for an empty key.                                                                    |
    68  | `partial_proof`               | Generate an invalid test case with a partially correct proof                                                                              |