web3gbit-cli 1.0.0

package/lib/openzeppelin-contracts/contracts/utils/cryptography/README.adoc

@@ -0,0 +1,76 @@
+= Cryptography
+
+[.readme-notice]
+NOTE: This document is better viewed at https://docs.openzeppelin.com/contracts/api/utils#cryptography
+
+A collection of contracts and libraries that implement various signature validation schemes and cryptographic primitives. These utilities enable secure authentication, multisignature operations, and advanced cryptographic operations in smart contracts.
+
+ * {ECDSA}, {MessageHashUtils}: Libraries for interacting with ECDSA signatures.
+ * {P256}: Library for verifying and recovering public keys from secp256r1 signatures.
+ * {RSA}: Library with RSA PKCS#1 v1.5 signature verification utilities.
+ * {SignatureChecker}: A library helper to support regular ECDSA from EOAs as well as ERC-1271 signatures for smart contracts.
+ * {Hashes}: Commonly used hash functions.
+ * {MerkleProof}: Functions for verifying https://en.wikipedia.org/wiki/Merkle_tree[Merkle Tree] proofs.
+ * {TrieProof}: Library for verifying Ethereum Merkle-Patricia trie inclusion proofs.
+ * {EIP712}: Contract with functions to allow processing signed typed structure data according to https://eips.ethereum.org/EIPS/eip-712[EIP-712].
+ * {ERC7739Utils}: Utilities library that implements a defensive rehashing mechanism to prevent replayability of smart contract signatures based on ERC-7739.
+ * {WebAuthn}: Library for verifying WebAuthn Authentication Assertions.
+ * {AbstractSigner}: Abstract contract for internal signature validation in smart contracts.
+ * {ERC7739}: An abstract contract to validate signatures following the rehashing scheme from {ERC7739Utils}.
+ * {SignerECDSA}, {SignerP256}, {SignerRSA}: Implementations of an {AbstractSigner} with specific signature validation algorithms.
+ * {SignerEIP7702}: Implementation of {AbstractSigner} that validates signatures using the contract's own address as the signer, useful for delegated accounts following EIP-7702.
+ * {SignerWebAuthn}: Implementation of {SignerP256} that supports WebAuthn
+ * {SignerERC7913}, {MultiSignerERC7913}, {MultiSignerERC7913Weighted}: Implementations of {AbstractSigner} that validate signatures based on ERC-7913. Including a simple and weighted multisignature scheme.
+ * {ERC7913P256Verifier}, {ERC7913RSAVerifier}, {ERC7913WebAuthnVerifier}: Ready to use ERC-7913 signature verifiers for P256, RSA keys and WebAuthn.
+
+== Utils
+
+{{ECDSA}}
+
+{{MessageHashUtils}}
+
+{{P256}}
+
+{{RSA}}
+
+{{SignatureChecker}}
+
+{{Hashes}}
+
+{{MerkleProof}}
+
+{{TrieProof}}
+
+{{EIP712}}
+
+{{ERC7739Utils}}
+
+{{WebAuthn}}
+
+== Abstract Signers
+
+{{AbstractSigner}}
+
+{{ERC7739}}
+
+{{SignerECDSA}}
+
+{{SignerP256}}
+
+{{SignerRSA}}
+
+{{SignerEIP7702}}
+
+{{SignerERC7913}}
+
+{{MultiSignerERC7913}}
+
+{{MultiSignerERC7913Weighted}}
+
+== Verifiers
+
+{{ERC7913P256Verifier}}
+
+{{ERC7913RSAVerifier}}
+
+{{ERC7913WebAuthnVerifier}}

package/lib/openzeppelin-contracts/contracts/utils/cryptography/RSA.sol

@@ -0,0 +1,154 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Contracts (last updated v5.1.0) (utils/cryptography/RSA.sol)
+pragma solidity ^0.8.20;
+
+import {Math} from "../math/Math.sol";
+
+/**
+ * @dev RSA PKCS#1 v1.5 signature verification implementation according to https://datatracker.ietf.org/doc/html/rfc8017[RFC8017].
+ *
+ * This library supports PKCS#1 v1.5 padding to avoid malleability via chosen plaintext attacks in practical implementations.
+ * The padding follows the EMSA-PKCS1-v1_5-ENCODE encoding definition as per section 9.2 of the RFC. This padding makes
+ * RSA semantically secure for signing messages.
+ *
+ * Inspired by https://github.com/adria0/SolRsaVerify/blob/79c6182cabb9102ea69d4a2e996816091d5f1cd1[Adrià Massanet's work] (GNU General Public License v3.0).
+ *
+ * _Available since v5.1._
+ */
+library RSA {
+    /**
+     * @dev Same as {pkcs1Sha256} but using SHA256 to calculate the digest of `data`.
+     */
+    function pkcs1Sha256(
+        bytes memory data,
+        bytes memory s,
+        bytes memory e,
+        bytes memory n
+    ) internal view returns (bool) {
+        return pkcs1Sha256(sha256(data), s, e, n);
+    }
+
+    /**
+     * @dev Verifies a PKCSv1.5 signature given a digest according to the verification
+     * method described in https://datatracker.ietf.org/doc/html/rfc8017#section-8.2.2[section 8.2.2 of RFC8017] with
+     * support for explicit or implicit NULL parameters in the DigestInfo (no other optional parameters are supported).
+     *
+     * IMPORTANT: For security reason, this function requires the signature and modulus to have a length of at least
+     * 2048 bits. If you use a smaller key, consider replacing it with a larger, more secure, one.
+     *
+     * WARNING: This verification algorithm doesn't prevent replayability. If called multiple times with the same
+     * digest, public key and (valid signature), it will return true every time. Consider including an onchain nonce
+     * or unique identifier in the message to prevent replay attacks.
+     *
+     * WARNING: This verification algorithm supports any exponent. NIST recommends using `65537` (or higher).
+     * That is the default value many libraries use, such as OpenSSL. Developers may choose to reject public keys
+     * using a low exponent out of security concerns.
+     *
+     * @param digest the digest to verify
+     * @param s is a buffer containing the signature
+     * @param e is the exponent of the public key
+     * @param n is the modulus of the public key
+     */
+    function pkcs1Sha256(bytes32 digest, bytes memory s, bytes memory e, bytes memory n) internal view returns (bool) {
+        unchecked {
+            // cache and check length
+            uint256 length = n.length;
+            if (
+                length < 0x100 || // Enforce 2048 bits minimum
+                length != s.length // signature must have the same length as the finite field
+            ) {
+                return false;
+            }
+
+            // Verify that s < n to ensure there's only one valid signature for a given message
+            for (uint256 i = 0; i < length; i += 0x20) {
+                uint256 p = Math.min(i, length - 0x20);
+                bytes32 sp = _unsafeReadBytes32(s, p);
+                bytes32 np = _unsafeReadBytes32(n, p);
+                if (sp < np) {
+                    // s < n in the upper bits (everything before is equal) → s < n globally: ok
+                    break;
+                } else if (sp > np || p == length - 0x20) {
+                    // s > n in the upper bits (everything before is equal) → s > n globally: fail
+                    // or
+                    // s = n and we are looking at the lower bits → s = n globally: fail
+                    return false;
+                }
+            }
+
+            // RSAVP1 https://datatracker.ietf.org/doc/html/rfc8017#section-5.2.2
+            // The previous check guarantees that n > 0. Therefore modExp cannot revert.
+            bytes memory buffer = Math.modExp(s, e, n);
+
+            // Check that buffer is well encoded:
+            // buffer ::= 0x00 | 0x01 | PS | 0x00 | DigestInfo
+            //
+            // With
+            // - PS is padding filled with 0xFF
+            // - DigestInfo ::= SEQUENCE {
+            //    digestAlgorithm AlgorithmIdentifier,
+            //      [optional algorithm parameters] -- not currently supported
+            //    digest OCTET STRING
+            // }
+
+            // Get AlgorithmIdentifier from the DigestInfo, and set the config accordingly
+            // - params: includes 00 + first part of DigestInfo
+            // - mask: filter to check the params
+            // - offset: length of the suffix (including digest)
+            bytes32 params; // 0x00 | DigestInfo
+            bytes32 mask;
+            uint256 offset;
+
+            // Digest is expected at the end of the buffer. Therefore if NULL param is present,
+            // it should be at 32 (digest) + 2 bytes from the end. To those 34 bytes, we add the
+            // OID (9 bytes) and its length (2 bytes) to get the position of the DigestInfo sequence,
+            // which is expected to have a length of 0x31 when the NULL param is present or 0x2f if not.
+            if (bytes1(_unsafeReadBytes32(buffer, length - 0x32)) == 0x31) {
+                offset = 0x34;
+                // 00 (1 byte) | SEQUENCE length (0x31) = 3031 (2 bytes) | SEQUENCE length (0x0d) = 300d (2 bytes) | OBJECT_IDENTIFIER length (0x09) = 0609 (2 bytes)
+                // SHA256 OID = 608648016503040201 (9 bytes) | NULL = 0500 (2 bytes) (explicit) | OCTET_STRING length (0x20) = 0420 (2 bytes)
+                params = 0x003031300d060960864801650304020105000420000000000000000000000000;
+                mask = 0xffffffffffffffffffffffffffffffffffffffff000000000000000000000000; // (20 bytes)
+            } else if (bytes1(_unsafeReadBytes32(buffer, length - 0x30)) == 0x2F) {
+                offset = 0x32;
+                // 00 (1 byte) | SEQUENCE length (0x2f) = 302f (2 bytes) | SEQUENCE length (0x0b) = 300b (2 bytes) | OBJECT_IDENTIFIER length (0x09) = 0609 (2 bytes)
+                // SHA256 OID = 608648016503040201 (9 bytes) | NULL = <implicit> | OCTET_STRING length (0x20) = 0420 (2 bytes)
+                params = 0x00302f300b060960864801650304020104200000000000000000000000000000;
+                mask = 0xffffffffffffffffffffffffffffffffffff0000000000000000000000000000; // (18 bytes)
+            } else {
+                // unknown
+                return false;
+            }
+
+            // Length is at least 0x100 and offset is at most 0x34, so this is safe. There is always some padding.
+            uint256 paddingEnd = length - offset;
+
+            // The padding has variable (arbitrary) length, so we check it byte per byte in a loop.
+            // This is required to ensure non-malleability. Not checking would allow an attacker to
+            // use the padding to manipulate the message in order to create a valid signature out of
+            // multiple valid signatures.
+            for (uint256 i = 2; i < paddingEnd; ++i) {
+                if (bytes1(_unsafeReadBytes32(buffer, i)) != 0xFF) {
+                    return false;
+                }
+            }
+
+            // All the other parameters are small enough to fit in a bytes32, so we can check them directly.
+            return
+                bytes2(0x0001) == bytes2(_unsafeReadBytes32(buffer, 0x00)) && // 00 | 01
+                // PS was checked in the loop
+                params == _unsafeReadBytes32(buffer, paddingEnd) & mask && // DigestInfo
+                // Optional parameters are not checked
+                digest == _unsafeReadBytes32(buffer, length - 0x20); // Digest
+        }
+    }
+
+    /// @dev Reads a bytes32 from a bytes array without bounds checking.
+    function _unsafeReadBytes32(bytes memory array, uint256 offset) private pure returns (bytes32 result) {
+        // Memory safeness is guaranteed as long as the provided `array` is a Solidity-allocated bytes array
+        // and `offset` is within bounds. This is the case for all calls to this private function from {pkcs1Sha256}.
+        assembly ("memory-safe") {
+            result := mload(add(add(array, 0x20), offset))
+        }
+    }
+}

package/lib/openzeppelin-contracts/contracts/utils/cryptography/SignatureChecker.sol

@@ -0,0 +1,191 @@
+// SPDX-License-Identifier: MIT
+// OpenZeppelin Contracts (last updated v5.5.0) (utils/cryptography/SignatureChecker.sol)
+
+pragma solidity ^0.8.24;
+
+import {ECDSA} from "./ECDSA.sol";
+import {IERC1271} from "../../interfaces/IERC1271.sol";
+import {IERC7913SignatureVerifier} from "../../interfaces/IERC7913.sol";
+import {Bytes} from "../Bytes.sol";
+
+/**
+ * @dev Signature verification helper that can be used instead of `ECDSA.recover` to seamlessly support:
+ *
+ * * ECDSA signatures from externally owned accounts (EOAs)
+ * * ERC-1271 signatures from smart contract wallets like Argent and Safe Wallet (previously Gnosis Safe)
+ * * ERC-7913 signatures from keys that do not have an Ethereum address of their own
+ *
+ * See https://eips.ethereum.org/EIPS/eip-1271[ERC-1271] and https://eips.ethereum.org/EIPS/eip-7913[ERC-7913].
+ */
+library SignatureChecker {
+    using Bytes for bytes;
+
+    /**
+     * @dev Checks if a signature is valid for a given signer and data hash. If the signer has code, the
+     * signature is validated against it using ERC-1271, otherwise it's validated using `ECDSA.recover`.
+     *
+     * NOTE: Unlike ECDSA signatures, contract signatures are revocable, and the outcome of this function can thus
+     * change through time. It could return true at block N and false at block N+1 (or the opposite).
+     *
+     * NOTE: For an extended version of this function that supports ERC-7913 signatures, see {isValidSignatureNow-bytes-bytes32-bytes-}.
+     */
+    function isValidSignatureNow(address signer, bytes32 hash, bytes memory signature) internal view returns (bool) {
+        if (signer.code.length == 0) {
+            (address recovered, ECDSA.RecoverError err, ) = ECDSA.tryRecover(hash, signature);
+            return err == ECDSA.RecoverError.NoError && recovered == signer;
+        } else {
+            return isValidERC1271SignatureNow(signer, hash, signature);
+        }
+    }
+
+    /**
+     * @dev Variant of {isValidSignatureNow} that takes a signature in calldata
+     */
+    function isValidSignatureNowCalldata(
+        address signer,
+        bytes32 hash,
+        bytes calldata signature
+    ) internal view returns (bool) {
+        if (signer.code.length == 0) {
+            (address recovered, ECDSA.RecoverError err, ) = ECDSA.tryRecoverCalldata(hash, signature);
+            return err == ECDSA.RecoverError.NoError && recovered == signer;
+        } else {
+            return isValidERC1271SignatureNowCalldata(signer, hash, signature);
+        }
+    }
+
+    /**
+     * @dev Checks if a signature is valid for a given signer and data hash. The signature is validated
+     * against the signer smart contract using ERC-1271.
+     *
+     * NOTE: Unlike ECDSA signatures, contract signatures are revocable, and the outcome of this function can thus
+     * change through time. It could return true at block N and false at block N+1 (or the opposite).
+     */
+    function isValidERC1271SignatureNow(
+        address signer,
+        bytes32 hash,
+        bytes memory signature
+    ) internal view returns (bool result) {
+        bytes4 selector = IERC1271.isValidSignature.selector;
+        uint256 length = signature.length;
+
+        assembly ("memory-safe") {
+            // Encoded calldata is :
+            // [ 0x00 - 0x03 ] <selector>
+            // [ 0x04 - 0x23 ] <hash>
+            // [ 0x24 - 0x43 ] <signature offset> (0x40)
+            // [ 0x44 - 0x63 ] <signature length>
+            // [ 0x64 - ...  ] <signature data>
+            let ptr := mload(0x40)
+            mstore(ptr, selector)
+            mstore(add(ptr, 0x04), hash)
+            mstore(add(ptr, 0x24), 0x40)
+            mcopy(add(ptr, 0x44), signature, add(length, 0x20))
+
+            let success := staticcall(gas(), signer, ptr, add(length, 0x64), 0x00, 0x20)
+            result := and(success, and(gt(returndatasize(), 0x1f), eq(mload(0x00), selector)))
+        }
+    }
+
+    function isValidERC1271SignatureNowCalldata(
+        address signer,
+        bytes32 hash,
+        bytes calldata signature
+    ) internal view returns (bool result) {
+        bytes4 selector = IERC1271.isValidSignature.selector;
+        uint256 length = signature.length;
+
+        assembly ("memory-safe") {
+            // Encoded calldata is :
+            // [ 0x00 - 0x03 ] <selector>
+            // [ 0x04 - 0x23 ] <hash>
+            // [ 0x24 - 0x43 ] <signature offset> (0x40)
+            // [ 0x44 - 0x63 ] <signature length>
+            // [ 0x64 - ...  ] <signature data>
+            let ptr := mload(0x40)
+            mstore(ptr, selector)
+            mstore(add(ptr, 0x04), hash)
+            mstore(add(ptr, 0x24), 0x40)
+            mstore(add(ptr, 0x44), length)
+            calldatacopy(add(ptr, 0x64), signature.offset, length)
+
+            let success := staticcall(gas(), signer, ptr, add(length, 0x64), 0x00, 0x20)
+            result := and(success, and(gt(returndatasize(), 0x1f), eq(mload(0x00), selector)))
+        }
+    }
+
+    /**
+     * @dev Verifies a signature for a given ERC-7913 signer and hash.
+     *
+     * The signer is a `bytes` object that is the concatenation of an address and optionally a key:
+     * `verifier || key`. A signer must be at least 20 bytes long.
+     *
+     * Verification is done as follows:
+     *
+     * * If `signer.length < 20`: verification fails
+     * * If `signer.length == 20`: verification is done using {isValidSignatureNow}
+     * * Otherwise: verification is done using {IERC7913SignatureVerifier}
+     *
+     * NOTE: Unlike ECDSA signatures, contract signatures are revocable, and the outcome of this function can thus
+     * change through time. It could return true at block N and false at block N+1 (or the opposite).
+     */
+    function isValidSignatureNow(
+        bytes memory signer,
+        bytes32 hash,
+        bytes memory signature
+    ) internal view returns (bool) {
+        if (signer.length < 20) {
+            return false;
+        } else if (signer.length == 20) {
+            return isValidSignatureNow(address(bytes20(signer)), hash, signature);
+        } else {
+            (bool success, bytes memory result) = address(bytes20(signer)).staticcall(
+                abi.encodeCall(IERC7913SignatureVerifier.verify, (signer.slice(20), hash, signature))
+            );
+            return (success &&
+                result.length >= 32 &&
+                abi.decode(result, (bytes32)) == bytes32(IERC7913SignatureVerifier.verify.selector));
+        }
+    }
+
+    /**
+     * @dev Verifies multiple ERC-7913 `signatures` for a given `hash` using a set of `signers`.
+     * Returns `false` if the number of signers and signatures is not the same.
+     *
+     * The signers should be ordered by their `keccak256` hash to ensure efficient duplication check. Unordered
+     * signers are supported, but the uniqueness check will be more expensive.
+     *
+     * NOTE: Unlike ECDSA signatures, contract signatures are revocable, and the outcome of this function can thus
+     * change through time. It could return true at block N and false at block N+1 (or the opposite).
+     */
+    function areValidSignaturesNow(
+        bytes32 hash,
+        bytes[] memory signers,
+        bytes[] memory signatures
+    ) internal view returns (bool) {
+        if (signers.length != signatures.length) return false;
+
+        bytes32 lastId = bytes32(0);
+
+        for (uint256 i = 0; i < signers.length; ++i) {
+            bytes memory signer = signers[i];
+
+            // If one of the signatures is invalid, reject the batch
+            if (!isValidSignatureNow(signer, hash, signatures[i])) return false;
+
+            bytes32 id = keccak256(signer);
+            // If the current signer ID is greater than all previous IDs, then this is a new signer.
+            if (lastId < id) {
+                lastId = id;
+            } else {
+                // If this signer id is not greater than all the previous ones, verify that it is not a duplicate of a previous one
+                // This loop is never executed if the signers are ordered by id.
+                for (uint256 j = 0; j < i; ++j) {
+                    if (id == keccak256(signers[j])) return false;
+                }
+            }
+        }
+
+        return true;
+    }
+}

package/lib/openzeppelin-contracts/contracts/utils/cryptography/TrieProof.sol

@@ -0,0 +1,230 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.26;
+
+import {Bytes} from "../Bytes.sol";
+import {Memory} from "../Memory.sol";
+import {RLP} from "../RLP.sol";
+
+/**
+ * @dev Library for verifying Ethereum Merkle-Patricia trie inclusion proofs.
+ *
+ * The {traverse} and {verify} functions can be used to prove the following value:
+ *
+ * * Transaction against the transactionsRoot of a block.
+ * * Event against receiptsRoot of a block.
+ * * Account details (RLP encoding of [nonce, balance, storageRoot, codeHash]) against the stateRoot of a block.
+ * * Storage slot (RLP encoding of the value) against the storageRoot of a account.
+ *
+ * Proving a storage slot is usually done in 3 steps:
+ *
+ * * From the stateRoot of a block, process the account proof (see `eth_getProof`) to get the account details.
+ * * RLP decode the account details to extract the storageRoot.
+ * * Use storageRoot of that account to process the storageProof (again, see `eth_getProof`).
+ *
+ * See https://ethereum.org/en/developers/docs/data-structures-and-encoding/patricia-merkle-trie[Merkle-Patricia trie]
+ *
+ * Based on https://github.com/ethereum-optimism/optimism/blob/ef970556e668b271a152124023a8d6bb5159bacf/packages/contracts-bedrock/src/libraries/trie/MerkleTrie.sol[this implementation from optimism].
+ */
+library TrieProof {
+    using Bytes for *;
+    using RLP for *;
+    using Memory for *;
+
+    enum Prefix {
+        EXTENSION_EVEN, // 0 - Extension node with even length path
+        EXTENSION_ODD, // 1 - Extension node with odd length path
+        LEAF_EVEN, // 2 - Leaf node with even length path
+        LEAF_ODD // 3 - Leaf node with odd length path
+    }
+
+    enum ProofError {
+        NO_ERROR, // No error occurred during proof traversal
+        EMPTY_KEY, // The provided key is empty
+        INVALID_ROOT, // The validation of the root node failed
+        INVALID_LARGE_NODE, // The validation of a large node failed
+        INVALID_SHORT_NODE, // The validation of a short node failed
+        EMPTY_PATH, // The path in a leaf or extension node is empty
+        INVALID_PATH_REMAINDER, // The path remainder in a leaf or extension node is invalid
+        EMPTY_EXTENSION_PATH_REMAINDER, // The path remainder in an extension node is empty
+        INVALID_EXTRA_PROOF_ELEMENT, // A leaf value should be the last proof element
+        EMPTY_VALUE, // The leaf value is empty
+        MISMATCH_LEAF_PATH_KEY_REMAINDER, // The path remainder in a leaf node doesn't match the key remainder
+        UNKNOWN_NODE_PREFIX, // The node prefix is unknown
+        UNPARSEABLE_NODE, // The node cannot be parsed from RLP encoding
+        INVALID_PROOF // General failure during proof traversal
+    }
+
+    error TrieProofTraversalError(ProofError err);
+
+    /// @dev The radix of the Ethereum trie
+    uint256 internal constant EVM_TREE_RADIX = 16;
+
+    /// @dev Number of items in a branch node (16 children + 1 value)
+    uint256 internal constant BRANCH_NODE_LENGTH = EVM_TREE_RADIX + 1;
+
+    /// @dev Number of items in leaf or extension nodes (always 2)
+    uint256 internal constant LEAF_OR_EXTENSION_NODE_LENGTH = 2;
+
+    /// @dev Verifies a `proof` against a given `key`, `value`, `and root` hash.
+    function verify(
+        bytes memory value,
+        bytes32 root,
+        bytes memory key,
+        bytes[] memory proof
+    ) internal pure returns (bool) {
+        (bytes memory processedValue, ProofError err) = tryTraverse(root, key, proof);
+        return processedValue.equal(value) && err == ProofError.NO_ERROR;
+    }
+
+    /**
+     * @dev Traverses a proof with a given key and returns the value.
+     *
+     * Reverts with {TrieProofTraversalError} if proof is invalid.
+     */
+    function traverse(bytes32 root, bytes memory key, bytes[] memory proof) internal pure returns (bytes memory) {
+        (bytes memory value, ProofError err) = tryTraverse(root, key, proof);
+        require(err == ProofError.NO_ERROR, TrieProofTraversalError(err));
+        return value;
+    }
+
+    /**
+     * @dev Traverses a proof with a given key and returns the value and an error flag
+     * instead of reverting if the proof is invalid. This function may still revert if
+     * malformed input leads to RLP decoding errors.
+     */
+    function tryTraverse(
+        bytes32 root,
+        bytes memory key,
+        bytes[] memory proof
+    ) internal pure returns (bytes memory value, ProofError err) {
+        if (key.length == 0) return (_emptyBytesMemory(), ProofError.EMPTY_KEY);
+
+        // Expand the key
+        bytes memory keyExpanded = key.toNibbles();
+
+        bytes32 currentNodeId;
+        uint256 currentNodeIdLength;
+
+        // Free memory pointer cache
+        Memory.Pointer fmp = Memory.getFreeMemoryPointer();
+
+        // Traverse proof
+        uint256 keyIndex = 0;
+        uint256 proofLength = proof.length;
+        for (uint256 i = 0; i < proofLength; ++i) {
+            // validates the encoded node matches the expected node id
+            bytes memory encoded = proof[i];
+            if (keyIndex == 0) {
+                // Root node must match root hash
+                if (keccak256(encoded) != root) return (_emptyBytesMemory(), ProofError.INVALID_ROOT);
+            } else if (encoded.length >= 32) {
+                // Large nodes are stored as hashes
+                if (currentNodeIdLength != 32 || keccak256(encoded) != currentNodeId)
+                    return (_emptyBytesMemory(), ProofError.INVALID_LARGE_NODE);
+            } else {
+                // Small nodes must match directly
+                if (currentNodeIdLength != encoded.length || bytes32(encoded) != currentNodeId)
+                    return (_emptyBytesMemory(), ProofError.INVALID_SHORT_NODE);
+            }
+
+            // decode the current node as an RLP list, and process it
+            Memory.Slice[] memory decoded = encoded.decodeList();
+            if (decoded.length == BRANCH_NODE_LENGTH) {
+                // If we've consumed the entire key, the value must be in the last slot
+                // Otherwise, continue down the branch specified by the next nibble in the key
+                if (keyIndex == keyExpanded.length) {
+                    return _validateLastItem(decoded[EVM_TREE_RADIX], proofLength, i);
+                } else {
+                    bytes1 branchKey = keyExpanded[keyIndex];
+                    (currentNodeId, currentNodeIdLength) = _getNodeId(decoded[uint8(branchKey)]);
+                    keyIndex += 1;
+                }
+            } else if (decoded.length == LEAF_OR_EXTENSION_NODE_LENGTH) {
+                bytes memory path = decoded[0].readBytes().toNibbles(); // expanded path
+                // The following is equivalent to path.length < 2 because toNibbles can't return odd-length buffers
+                if (path.length == 0) {
+                    return (_emptyBytesMemory(), ProofError.EMPTY_PATH);
+                }
+                uint8 prefix = uint8(path[0]);
+                Memory.Slice keyRemainder = keyExpanded.asSlice().slice(keyIndex); // Remaining key to match
+                Memory.Slice pathRemainder = path.asSlice().slice(2 - (prefix % 2)); // Path after the prefix
+                uint256 pathRemainderLength = pathRemainder.length();
+
+                // pathRemainder must not be longer than keyRemainder, and it must be a prefix of it
+                if (
+                    pathRemainderLength > keyRemainder.length() ||
+                    !pathRemainder.equal(keyRemainder.slice(0, pathRemainderLength))
+                ) {
+                    return (_emptyBytesMemory(), ProofError.INVALID_PATH_REMAINDER);
+                }
+
+                if (prefix <= uint8(Prefix.EXTENSION_ODD)) {
+                    // Eq to: prefix == EXTENSION_EVEN || prefix == EXTENSION_ODD
+                    if (pathRemainderLength == 0) {
+                        return (_emptyBytesMemory(), ProofError.EMPTY_EXTENSION_PATH_REMAINDER);
+                    }
+                    // Increment keyIndex by the number of nibbles consumed and continue traversal
+                    (currentNodeId, currentNodeIdLength) = _getNodeId(decoded[1]);
+                    keyIndex += pathRemainderLength;
+                } else if (prefix <= uint8(Prefix.LEAF_ODD)) {
+                    // Eq to: prefix == LEAF_EVEN || prefix == LEAF_ODD
+                    //
+                    // Leaf node (terminal) - return its value if key matches completely
+                    // we already know that pathRemainder is a prefix of keyRemainder, so checking the length sufficient
+                    return
+                        pathRemainderLength == keyRemainder.length()
+                            ? _validateLastItem(decoded[1], proofLength, i)
+                            : (_emptyBytesMemory(), ProofError.MISMATCH_LEAF_PATH_KEY_REMAINDER);
+                } else {
+                    return (_emptyBytesMemory(), ProofError.UNKNOWN_NODE_PREFIX);
+                }
+            } else {
+                return (_emptyBytesMemory(), ProofError.UNPARSEABLE_NODE);
+            }
+
+            // Reset memory before next iteration. Deallocates `decoded` and `path`.
+            Memory.setFreeMemoryPointer(fmp);
+        }
+
+        // If we've gone through all proof elements without finding a value, the proof is invalid
+        return (_emptyBytesMemory(), ProofError.INVALID_PROOF);
+    }
+
+    /**
+     * @dev Validates that we've reached a valid leaf value and this is the last proof element.
+     * Ensures the value is not empty and no extra proof elements exist.
+     */
+    function _validateLastItem(
+        Memory.Slice item,
+        uint256 trieProofLength,
+        uint256 i
+    ) private pure returns (bytes memory, ProofError) {
+        if (i != trieProofLength - 1) {
+            return (_emptyBytesMemory(), ProofError.INVALID_EXTRA_PROOF_ELEMENT);
+        }
+        bytes memory value = item.readBytes();
+        return (value, value.length == 0 ? ProofError.EMPTY_VALUE : ProofError.NO_ERROR);
+    }
+
+    /**
+     * @dev Extracts the node ID (hash or raw data based on size)
+     *
+     * For small nodes (encoded length < 32 bytes) the node ID is the node content itself,
+     * For larger nodes, the node ID is the hash of the encoded node data.
+     *
+     * NOTE: Under normal operation, the input should never be exactly 32-byte inputs. If such an input is provided,
+     * it will be used directly, similarly to how small nodes are processed. The following traversal check whether
+     * the next node is a large one, and whether its hash matches the raw 32 bytes we have here. If that is the case,
+     * the value will be accepted. Otherwise, the next step will return an {INVALID_LARGE_NODE} error.
+     */
+    function _getNodeId(Memory.Slice node) private pure returns (bytes32 nodeId, uint256 nodeIdLength) {
+        uint256 nodeLength = node.length();
+        return nodeLength < 33 ? (node.load(0), nodeLength) : (node.readBytes32(), 32);
+    }
+
+    function _emptyBytesMemory() private pure returns (bytes memory result) {
+        assembly ("memory-safe") {
+            result := 0x60 // mload(0x60) is always 0
+        }
+    }
+}