Build cross-chain state proof verifier utility

[NkechiOgbuji]

Closes #66

Description

This PR adds a local cross-chain state proof verifier to the SDK.

The goal is to make it easier to verify Ethereum account and storage proofs without depending on an RPC provider, external API, or internet connection. This is useful in cross-chain workflows where proof data has already been collected from another EVM network and needs to be checked locally before it is submitted on-chain.

The new StateProver utility validates EIP-1186 proof data against a trusted stateRoot. It walks through the Merkle Patricia Trie, verifies each referenced node, and checks that the proof resolves to the expected account or storage value.

What was added

• Added StateProver under src/crypto.
• Added local RLP decoding utilities used during trie traversal.
• Added support for:
  • branch nodes;
  • extension nodes;
  • leaf nodes;
  • embedded child nodes;
  • hashed child references.
• Added account proof verification against a supplied state root.
• Added storage proof verification using the verified account’s storage root.
• Added support for valid inclusion and exclusion proofs.
• Added structured results to distinguish:
  • a value that exists;
  • a valid proof that the value is absent;
  • an invalid or malformed proof.
• Added a simple boolean verification helper for callers that only need a valid or invalid result.
• Exported the new utility through the crypto module and main SDK entry point.
• Added documentation explaining how to collect proof data online and verify it locally.

How verification works

The caller provides a trusted block stateRoot together with the output of eth_getProof.

For account proofs, the verifier:

1. Hashes the account address using keccak256.
2. Traverses the account trie using the supplied proof nodes.
3. Validates every hashed or embedded child reference.
4. Decodes the account value.
5. Extracts and verifies the account nonce, balance, storage root, and code hash.

For storage proofs, the verifier:

1. Normalises the storage slot to 32 bytes.
2. Hashes the slot using keccak256.
3. Traverses the storage trie from the verified account’s storage root.
4. Decodes the stored value.
5. Compares it with the value claimed in the EIP-1186 response.

All hashing and proof validation happen locally.

Security and trust model

This utility does not make RPC calls or attempt to retrieve block data automatically. It has no dependency on a provider, transport, wallet client, public client, HTTP request, or WebSocket connection.

The proof is only valid relative to the stateRoot supplied by the caller. The caller is still responsible for obtaining that state root from a trusted block header and deciding whether the source block has sufficient confirmation or finality.

This verifier does not replace on-chain proof validation. It provides a way to prevalidate proof data locally before it is passed to another chain or smart contract.

Tests

Added focused tests covering:

• valid account inclusion proofs;
• valid storage inclusion proofs;
• account and storage exclusion proofs;
• invalid state roots;
• corrupted and incomplete proof nodes;
• branch, extension, and leaf traversal;
• odd and even compact paths;
• embedded and hashed child references;
• malformed RLP data;
• invalid trie node structures;
• zero and large storage values;
• incorrect claimed values;
• proof-size limits;
• deterministic verification;
• complete network isolation.

A separate no-network test confirms that proof verification succeeds without calling any network API.

Validation

• Focused StateProver and RLP tests pass.
• All runnable repository tests pass.
• Remaining failing suites are pre-existing and are in files outside the scope of this change.
• git diff --check passes.
• No new external cryptographic dependency was introduced.
• The implementation reuses the existing audited keccak256 primitive.

Additional note

A minimal correction was made to the malformed vitest entry in package.json because the existing JSON error prevented the test runner from starting. No package was added or upgraded as part of that fix.