From f315fc080362bb5fe428135e47d3c2d068f92359 Mon Sep 17 00:00:00 2001 From: Scorbajio Date: Wed, 18 Sep 2024 00:04:24 -0700 Subject: [PATCH] Statemanager doc update (#3675) * Change DefaultStateManager to MerkleStateManager * Fix mispelling * Reword and add example to example description * Update example * Update and reembed example --- packages/statemanager/README.md | 25 +++++++++++++------ .../examples/fromProofInstantiation.ts | 2 +- 2 files changed, 18 insertions(+), 9 deletions(-) diff --git a/packages/statemanager/README.md b/packages/statemanager/README.md index 65bf9cab93..4e98f90fae 100644 --- a/packages/statemanager/README.md +++ b/packages/statemanager/README.md @@ -26,13 +26,13 @@ The `StateManager` provides high-level access and manipulation methods to and fo This library includes several different implementations that all implement the `StateManager` interface which is accepted by the `vm` library. These include: - [`SimpleStateManager`](./src/simpleStateManager.ts) -a minimally functional (and dependency minimized) version of the state manager suitable for most basic EVM bytecode operations -- [`DefaultStateManager`](./src//stateManager.ts) - a Merkle-Patricia Trie-based `DefaultStateManager` implementation that is used by the `@ethereumjs/client` and `@ethereumjs/vm` +- [`MerkleStateManager`](./src//stateManager.ts) - a Merkle-Patricia Trie-based `MerkleStateManager` implementation that is used by the `@ethereumjs/client` and `@ethereumjs/vm` - [`RPCStateManager`](./src/rpcStateManager.ts) - a light-weight implementation that sources state and history data from an external JSON-RPC provider - [`StatelessVerkleStateManager`](./src/statelessVerkleStateManager.ts) - an experimental implementation of a "stateless" state manager that uses Verkle proofs to provide necessary state access for processing verkle-trie based blocks It also includes a checkpoint/revert/commit mechanism to either persist or revert state changes and provides a sophisticated caching mechanism under the hood to reduce the need reading state accesses from disk. -### `DefaultStateManager` +### `MerkleStateManager` #### Usage example @@ -69,7 +69,7 @@ There are now two cache options available: an unbounded cache (`CacheType.ORDERE Caches now "survive" a flush operation and especially long-lived usage scenarios will benefit from increased performance by a growing and more "knowing" cache leading to less and less trie reads. -Have a loot at the extended `CacheOptions` on how to use and leverage the new cache system. +Have a look at the extended `CacheOptions` on how to use and leverage the new cache system. ### `SimpleStateManager` @@ -95,11 +95,20 @@ const main = async () => { void main() ``` -### `DefaultStateManager` -> Proofs +### `MerkleStateManager` -> Proofs #### Instantiating from a Proof -The `DefaultStateManager` has a static constructor `fromProof` that accepts one or more [EIP-1186](https://eips.ethereum.org/EIPS/eip-1186) [proofs](./src/stateManager.ts) and will instantiate a `DefaultStateManager` with a partial trie containing the state provided by the proof(s). Be aware that this constructor accepts the `StateManagerOpts` dictionary as a third parameter (i.e. `stateManager.fromProof(proof, safe, opts)`). Therefore, if you need to use a customized trie (e.g. one that does not use key hashing) or specify caching options, you can pass them in here. If you do instantiate a trie and pass it into the `fromProof` constructor, you also need to instantiate the trie using the corresponding `fromProof` constructor to ensure the state root matches when the proof data is added to the trie. See [this test](./test/stateManager.spec.ts#L287-L288) for more details. +The `MerkleStateManager` has a standalone constructor function `fromMerkleStateProof` that accepts one or more [EIP-1186](https://eips.ethereum.org/EIPS/eip-1186) [proofs](./src/stateManager.ts) and will instantiate a `MerkleStateManager` with a partial trie containing the state provided by the proof(s). Be aware that this constructor accepts the `StateManagerOpts` dictionary as a third parameter (i.e. `fromMerkleStateProof(proof, safe, opts)`). + +Therefore, if you need to use a customized trie (e.g. one that does not use key hashing) or specify caching options, you can pass them in here. If you do instantiate a trie and pass it into the `createTrieFromProof` constructor, you also need to instantiate the trie using the corresponding `createStateManagerFromProof` constructor to ensure the state root matches when the proof data is added to the trie, consider an example: + +```ts +const newTrie = await createTrieFromProof(proof, { useKeyHashing: false }) +const partialSM = await fromMerkleStateProof([proof], true, { + trie: newTrie, +}) +``` See below example for common usage: @@ -108,9 +117,9 @@ See below example for common usage: import { MerkleStateManager, - getMerkleStateProof, - fromMerkleStateProof, addMerkleStateProofData, + fromMerkleStateProof, + getMerkleStateProof, } from '@ethereumjs/statemanager' import { Address, hexToBytes } from '@ethereumjs/util' @@ -139,7 +148,7 @@ const main = async () => { ]) const partialStateManager = await fromMerkleStateProof(proof) - // To add more proof data, use `addProofData` + // To add more proof data, use `addMerkleStateProofData` await addMerkleStateProofData(partialStateManager, proofWithStorage) console.log(await partialStateManager.getCode(contractAddress)) // contract bytecode is not included in proof console.log(await partialStateManager.getStorage(contractAddress, storageKey1), storageValue1) // should match diff --git a/packages/statemanager/examples/fromProofInstantiation.ts b/packages/statemanager/examples/fromProofInstantiation.ts index 6d14ebc1dd..2173110bcf 100644 --- a/packages/statemanager/examples/fromProofInstantiation.ts +++ b/packages/statemanager/examples/fromProofInstantiation.ts @@ -31,7 +31,7 @@ const main = async () => { ]) const partialStateManager = await fromMerkleStateProof(proof) - // To add more proof data, use `addProofData` + // To add more proof data, use `addMerkleStateProofData` await addMerkleStateProofData(partialStateManager, proofWithStorage) console.log(await partialStateManager.getCode(contractAddress)) // contract bytecode is not included in proof console.log(await partialStateManager.getStorage(contractAddress, storageKey1), storageValue1) // should match