@feelyourprotocol/statemanager 8141.0.0

package/dist/cjs/merkleStateManager.d.ts

@@ -0,0 +1,260 @@
+import { Common } from '@feelyourprotocol/common';
+import { MerklePatriciaTrie } from '@feelyourprotocol/mpt';
+import { Account } from '@feelyourprotocol/util';
+import { OriginalStorageCache } from './cache/index.ts';
+import type { Caches, MerkleStateManagerOpts } from './index.ts';
+import type { AccountFields, StateManagerInterface, StorageDump, StorageRange } from '@feelyourprotocol/common';
+import type { Address, DB } from '@feelyourprotocol/util';
+import type { Debugger } from 'debug';
+/**
+ * Prefix to distinguish between a contract deployed with code `0x80`
+ * and `RLP([])` (also having the value `0x80`).
+ *
+ * Otherwise the creation of the code hash for the `0x80` contract
+ * will be the same as the hash of the empty trie which leads to
+ * misbehaviour in the underlying trie library.
+ */
+export declare const CODEHASH_PREFIX: Uint8Array<ArrayBufferLike>;
+/**
+ * Default StateManager implementation for the VM.
+ *
+ * The state manager abstracts from the underlying data store
+ * by providing higher level access to accounts, contract code
+ * and storage slots.
+ *
+ * The default state manager implementation uses a
+ * `@feelyourprotocol/mpt` trie as a data backend.
+ *
+ * Note that there is a `SimpleStateManager` dependency-free state
+ * manager implementation available shipped with the `@feelyourprotocol/statemanager`
+ * package which might be an alternative to this implementation
+ * for many basic use cases.
+ */
+export declare class MerkleStateManager implements StateManagerInterface {
+    protected _debug: Debugger;
+    protected _caches?: Caches;
+    originalStorageCache: OriginalStorageCache;
+    protected _trie: MerklePatriciaTrie;
+    protected _storageTries: {
+        [key: string]: MerklePatriciaTrie;
+    };
+    protected readonly _prefixCodeHashes: boolean;
+    protected readonly _prefixStorageTrieKeys: boolean;
+    readonly common: Common;
+    protected _checkpointCount: number;
+    private keccakFunction;
+    /**
+     * StateManager is run in DEBUG mode (default: false)
+     * Taken from DEBUG environment variable
+     *
+     * Safeguards on debug() calls are added for
+     * performance reasons to avoid string literal evaluation
+     * @hidden
+     */
+    protected readonly DEBUG: boolean;
+    /**
+     * Instantiate the StateManager interface.
+     */
+    constructor(opts?: MerkleStateManagerOpts);
+    /**
+     * Gets the account associated with `address` or `undefined` if account does not exist
+     * @param address - Address of the `account` to get
+     */
+    getAccount(address: Address): Promise<Account | undefined>;
+    /**
+     * Saves an account into state under the provided `address`.
+     * @param address - Address under which to store `account`
+     * @param account - The account to store or undefined if to be deleted
+     */
+    putAccount(address: Address, account: Account | undefined): Promise<void>;
+    /**
+     * Gets the account associated with `address`, modifies the given account
+     * fields, then saves the account into state. Account fields can include
+     * `nonce`, `balance`, `storageRoot`, and `codeHash`.
+     * @param address - Address of the account to modify
+     * @param accountFields - Object containing account fields and values to modify
+     */
+    modifyAccountFields(address: Address, accountFields: AccountFields): Promise<void>;
+    /**
+     * Deletes an account from state under the provided `address`.
+     * @param address - Address of the account which should be deleted
+     */
+    deleteAccount(address: Address): Promise<void>;
+    /**
+     * Adds `value` to the state trie as code, and sets `codeHash` on the account
+     * corresponding to `address` to reference this.
+     * @param address - Address of the `account` to add the `code` for
+     * @param value - The value of the `code`
+     */
+    putCode(address: Address, value: Uint8Array): Promise<void>;
+    /**
+     * Gets the code corresponding to the provided `address`.
+     * @param address - Address to get the `code` for
+     * @returns {Promise<Uint8Array>} -  Resolves with the code corresponding to the provided address.
+     * Returns an empty `Uint8Array` if the account has no associated code.
+     */
+    getCode(address: Address): Promise<Uint8Array>;
+    getCodeSize(address: Address): Promise<number>;
+    /**
+     * Gets the storage trie for the EVM-internal account identified by the provided address/hash.
+     * If the storage trie is not in the local cache ('this._storageTries'),
+     *   generates a new storage trie object based on a lookup (shallow copy from 'this._trie'),
+     *   applies the storage root of the provided rootAccount (or an
+     *   empty trie root if no rootAccount is provided), and stores the new entry
+     *   in the local cache.
+     * @param addressOrHash Address (or other object) with populated 'bytes', or a raw Uint8Array.
+     *   Used to identify the requested storage trie in the local cache and define the
+     *   prefix used when creating a new storage trie.
+     * @param  rootAccount (Optional) Account object whose 'storageRoot' is to be used as
+     *   the root of the new storageTrie returned when there is no pre-existing trie.
+     *   If left undefined, the EMPTY_TRIE_ROOT will be used as the root instead.
+     * @returns storage MerklePatriciaTrie object
+     * @private
+     */
+    protected _getStorageTrie(addressOrHash: Address | {
+        bytes: Uint8Array;
+    } | Uint8Array, rootAccount?: Account): MerklePatriciaTrie;
+    /**
+     * Gets the storage trie for an account from the storage
+     * cache or does a lookup.
+     * @private
+     */
+    protected _getAccountTrie(): MerklePatriciaTrie;
+    /**
+     * Gets the storage trie for an account from the storage
+     * cache or does a lookup.
+     * @private
+     */
+    protected _getCodeDB(): DB;
+    /**
+     * Gets the storage value associated with the provided `address` and `key`. This method returns
+     * the shortest representation of the stored value.
+     * @param address -  Address of the account to get the storage for
+     * @param key - Key in the account's storage to get the value for. Must be 32 bytes long.
+     * @returns - The storage value for the account
+     * corresponding to the provided address at the provided key.
+     * If this does not exist an empty `Uint8Array` is returned.
+     */
+    getStorage(address: Address, key: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Modifies the storage trie of an account.
+     * @private
+     * @param address -  Address of the account whose storage is to be modified
+     * @param modifyTrie - Function to modify the storage trie of the account
+     */
+    protected _modifyContractStorage(address: Address, account: Account, modifyTrie: (storageTrie: MerklePatriciaTrie, done: Function) => void): Promise<void>;
+    protected _writeContractStorage(address: Address, account: Account, key: Uint8Array, value: Uint8Array): Promise<void>;
+    /**
+     * Adds value to the state trie for the `account`
+     * corresponding to `address` at the provided `key`.
+     * @param address -  Address to set a storage value for
+     * @param key - Key to set the value at. Must be 32 bytes long.
+     * @param value - Value to set at `key` for account corresponding to `address`.
+     * Cannot be more than 32 bytes. Leading zeros are stripped.
+     * If it is a empty or filled with zeros, deletes the value.
+     */
+    putStorage(address: Address, key: Uint8Array, value: Uint8Array): Promise<void>;
+    /**
+     * Clears all storage entries for the account corresponding to `address`.
+     * @param address - Address to clear the storage of
+     */
+    clearStorage(address: Address): Promise<void>;
+    /**
+     * Checkpoints the current state of the StateManager instance.
+     * State changes that follow can then be committed by calling
+     * `commit` or `reverted` by calling rollback.
+     */
+    checkpoint(): Promise<void>;
+    /**
+     * Commits the current change-set to the instance since the
+     * last call to checkpoint.
+     */
+    commit(): Promise<void>;
+    /**
+     * Reverts the current change-set to the instance since the
+     * last call to checkpoint.
+     */
+    revert(): Promise<void>;
+    /**
+     * Writes all cache items to the trie
+     */
+    flush(): Promise<void>;
+    /**
+     * Gets the state-root of the Merkle-Patricia trie representation
+     * of the state of this StateManager. Will error if there are uncommitted
+     * checkpoints on the instance.
+     * @returns {Promise<Uint8Array>} - Returns the state-root of the `StateManager`
+     */
+    getStateRoot(): Promise<Uint8Array>;
+    /**
+     * Sets the state of the instance to that represented
+     * by the provided `stateRoot`. Will error if there are uncommitted
+     * checkpoints on the instance or if the state root does not exist in
+     * the state trie.
+     * @param stateRoot - The state-root to reset the instance to
+     */
+    setStateRoot(stateRoot: Uint8Array, clearCache?: boolean): Promise<void>;
+    /**
+     * Dumps the RLP-encoded storage values for an `account` specified by `address`.
+     * @param address - The address of the `account` to return storage for
+     * @returns {Promise<StorageDump>} - The state of the account as an `Object` map.
+     * Keys are are the storage keys, values are the storage values as strings.
+     * Both are represented as hex strings without the `0x` prefix.
+     */
+    dumpStorage(address: Address): Promise<StorageDump>;
+    /**
+     Dumps a limited number of RLP-encoded storage values for an account specified by `address`,
+     starting from `startKey` or greater.
+     @param address - The address of the `account` to return storage for.
+     @param startKey - The bigint representation of the smallest storage key that will be returned.
+     @param limit - The maximum number of storage values that will be returned.
+     @returns {Promise<StorageRange>} - A {@link StorageRange} object that will contain at most `limit` entries in its `storage` field.
+     The object will also contain `nextKey`, the next (hashed) storage key after the range included in `storage`.
+     */
+    dumpStorageRange(address: Address, startKey: bigint, limit: number): Promise<StorageRange>;
+    /**
+     * Initializes the provided genesis state into the state trie.
+     * Will error if there are uncommitted checkpoints on the instance.
+     * @param initState address -> balance | [balance, code, storage]
+     */
+    generateCanonicalGenesis(initState: any): Promise<void>;
+    /**
+     * Checks whether there is a state corresponding to a stateRoot
+     */
+    hasStateRoot(root: Uint8Array): Promise<boolean>;
+    /**
+     * Copies the current instance of the `StateManager`
+     * at the last fully committed point, i.e. as if all current
+     * checkpoints were reverted.
+     *
+     * Caches are downleveled (so: adopted for short-term usage)
+     * by default.
+     *
+     * This means in particular:
+     * 1. For caches instantiated as an LRU cache type
+     * the copy() method will instantiate with an ORDERED_MAP cache
+     * instead, since copied instances are mostly used in
+     * short-term usage contexts and LRU cache instantiation would create
+     * a large overhead here.
+     * 2. The underlying trie object is initialized with 0 cache size
+     *
+     * Both adoptions can be deactivated by setting `downlevelCaches` to
+     * `false`.
+     *
+     * Cache values are generally not copied along regardless of the
+     * `downlevelCaches` setting.
+     */
+    shallowCopy(downlevelCaches?: boolean): MerkleStateManager;
+    /**
+     * Clears all underlying caches
+     */
+    clearCaches(): void;
+    /**
+     * Returns the applied key for a given address
+     * Used for saving preimages
+     * @param address - The address to return the applied key
+     * @returns {Uint8Array} - The applied key (e.g. hashed address)
+     */
+    getAppliedKey(address: Uint8Array): Uint8Array;
+}
+//# sourceMappingURL=merkleStateManager.d.ts.map

package/dist/cjs/merkleStateManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merkleStateManager.d.ts","sourceRoot":"","sources":["../../src/merkleStateManager.ts"],"names":[],"mappings":"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"}