webevm 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/README.md +115 -63
  2. package/dist/derived-trie.d.ts +38 -0
  3. package/dist/derived-trie.d.ts.map +1 -0
  4. package/dist/derived-trie.js +187 -0
  5. package/dist/derived-trie.js.map +1 -0
  6. package/dist/engine.d.ts +1 -2
  7. package/dist/engine.d.ts.map +1 -1
  8. package/dist/engine.js +2 -3
  9. package/dist/engine.js.map +1 -1
  10. package/dist/index.d.ts +1 -1
  11. package/dist/index.d.ts.map +1 -1
  12. package/dist/index.js.map +1 -1
  13. package/dist/node.d.ts +45 -0
  14. package/dist/node.d.ts.map +1 -1
  15. package/dist/node.js +1083 -140
  16. package/dist/node.js.map +1 -1
  17. package/dist/revm-state-store.d.ts +5 -0
  18. package/dist/revm-state-store.d.ts.map +1 -1
  19. package/dist/revm-state-store.js +42 -13
  20. package/dist/revm-state-store.js.map +1 -1
  21. package/dist/revm.d.ts.map +1 -1
  22. package/dist/revm.js +5 -19
  23. package/dist/revm.js.map +1 -1
  24. package/dist/state-manager.d.ts +256 -18
  25. package/dist/state-manager.d.ts.map +1 -1
  26. package/dist/state-manager.js +429 -20
  27. package/dist/state-manager.js.map +1 -1
  28. package/dist/storage-keys.d.ts +8 -0
  29. package/dist/storage-keys.d.ts.map +1 -1
  30. package/dist/storage-keys.js +18 -2
  31. package/dist/storage-keys.js.map +1 -1
  32. package/dist/types.d.ts +150 -33
  33. package/dist/types.d.ts.map +1 -1
  34. package/dist/worker-client.d.ts.map +1 -1
  35. package/dist/worker-client.js +20 -12
  36. package/dist/worker-client.js.map +1 -1
  37. package/dist/worker-host.d.ts.map +1 -1
  38. package/dist/worker-host.js +17 -9
  39. package/dist/worker-host.js.map +1 -1
  40. package/dist/worker-rpc-error.d.ts +21 -0
  41. package/dist/worker-rpc-error.d.ts.map +1 -0
  42. package/dist/worker-rpc-error.js +121 -0
  43. package/dist/worker-rpc-error.js.map +1 -0
  44. package/package.json +3 -1
  45. package/src/derived-trie.ts +214 -0
  46. package/src/engine.ts +2 -3
  47. package/src/index.ts +2 -1
  48. package/src/node.ts +1293 -136
  49. package/src/revm-state-store.ts +47 -13
  50. package/src/revm.ts +11 -25
  51. package/src/state-manager.ts +515 -21
  52. package/src/storage-keys.ts +21 -2
  53. package/src/types.ts +152 -34
  54. package/src/worker-client.ts +22 -12
  55. package/src/worker-host.ts +17 -9
  56. package/src/worker-rpc-error.ts +139 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "webevm",
3
- "version": "0.7.0",
3
+ "version": "0.8.0",
4
4
  "description": "Slim, execution-only in-browser EIP-1193 Ethereum node on @ethereumjs/vm. Transport-agnostic core + optional comlink Worker helpers + IndexedDB persistence.",
5
5
  "keywords": [
6
6
  "ethereum",
@@ -58,6 +58,8 @@
58
58
  "@ethereumjs/block": "^10.1.2",
59
59
  "@ethereumjs/common": "^10.1.2",
60
60
  "@ethereumjs/evm": "^10.1.2",
61
+ "@ethereumjs/mpt": "^10.1.2",
62
+ "@ethereumjs/rlp": "^10.1.2",
61
63
  "@ethereumjs/statemanager": "^10.1.2",
62
64
  "@ethereumjs/tx": "^10.1.2",
63
65
  "@ethereumjs/util": "^10.1.2",
@@ -0,0 +1,214 @@
1
+ /**
2
+ * derived-trie.ts: the Merkle-Patricia trie a `computeStateRoot: true` node DERIVES
3
+ * from its flat state, and nothing else.
4
+ *
5
+ * Every node runs on ONE state representation: the flat
6
+ * `OverlayStorageStateManager` (./state-manager.ts). A node with `computeStateRoot: true`
7
+ * ADDITIONALLY keeps this object, which mirrors that state as a real Ethereum
8
+ * state trie so the node can report a real state root. The decision and what it
9
+ * replaced (`MerkleStateManager` as the node's state manager) are in
10
+ * `docs/adr/0014-the-trie-is-derived-from-the-flat-state-not-a-state-manager.md`.
11
+ *
12
+ * ## The shape, which is Ethereum's
13
+ *
14
+ * - ONE account trie, keyed by `keccak(address)` (the trie hashes the key
15
+ * itself: `useKeyHashing`), whose value is `RLP([nonce, balance, storageRoot,
16
+ * codeHash])`.
17
+ * - ONE storage trie per account, keyed by `keccak(slot)`, whose value is
18
+ * `RLP(value)` with the value in shortest form; a zero value is ABSENT.
19
+ * - An account's `storageRoot` is taken from ITS storage trie at the moment the
20
+ * account is written into the account trie. The flat state's own `Account`
21
+ * objects never carry a real `storageRoot` (`SimpleStateManager` has no trie),
22
+ * and that is deliberate: the collision rule every engine applies reads it, and
23
+ * every node follows the reference spec there (see the ADR).
24
+ *
25
+ * ## The flat state is the source, the change set is the index
26
+ *
27
+ * {@link DerivedStateTrie.build} reads the WHOLE flat state once (at
28
+ * construction, after the genesis baselines, and at the end of `loadState`).
29
+ * From then on {@link DerivedStateTrie.apply} takes a change set (the open record
30
+ * of ./state-manager.ts) and uses it ONLY AS A LIST OF KEYS: every value is read
31
+ * from the flat state as it stands now, never from the record, whose values are
32
+ * the PRIOR ones. That makes `apply` idempotent, which is what lets the node
33
+ * apply the open record for a `getStateRoot()` between blocks and again, as part
34
+ * of the block's record, when the next block is mined.
35
+ *
36
+ * A storage CLEAR (`storageCleared`) replaces the account's storage trie with an
37
+ * empty one before its named slots are re-read: the clear recorded every slot
38
+ * the account held and every later write records its own slot, so the slots the
39
+ * record names are a superset of what can be live afterwards.
40
+ *
41
+ * ## It never runs during execution
42
+ *
43
+ * Both entry points require NO checkpoint to be open (they read the bottom of
44
+ * the flat state's stacks) and the node calls them only at the end of a mined
45
+ * block and inside `getStateRoot()`, both inside the serialisation point. The
46
+ * trie is async (`@ethereumjs/mpt`), and that costs no opcode anything because
47
+ * no engine ever reads it: this is why revm can run on a root-computing node.
48
+ *
49
+ * ## Old nodes are pruned
50
+ *
51
+ * Each trie has its OWN in-memory database and runs with `useNodePruning`, so a
52
+ * node replaced by a write is deleted rather than retained. The node reports the
53
+ * root of its head and nothing older (history is `stateHistory`'s undo log, not
54
+ * old tries), so a retained node could never be read again; keeping them would
55
+ * make a long-lived in-browser node's memory grow with every block. A dropped
56
+ * storage trie (account deleted, storage cleared) is simply released.
57
+ */
58
+ import {MerklePatriciaTrie} from '@ethereumjs/mpt';
59
+ import {RLP} from '@ethereumjs/rlp';
60
+ import type {Common} from '@ethereumjs/common';
61
+ import {Account, equalsBytes, hexToBytes, unpadBytes} from '@ethereumjs/util';
62
+ import type {
63
+ ChangeSet,
64
+ OverlayStorageStateManager,
65
+ PackedAddressKey,
66
+ } from './state-manager.js';
67
+ import {
68
+ packAddressKey,
69
+ packedKeyBytes,
70
+ unpackAddressKey,
71
+ } from './storage-keys.js';
72
+
73
+ /**
74
+ * How many {@link DerivedStateTrie} objects this module has ever created. TEST
75
+ * ONLY: it is how a node without `computeStateRoot` is PROVEN to do no trie work (not one is created
76
+ * by a node that does not compute roots), which a flag on the node could only
77
+ * claim.
78
+ */
79
+ let created = 0;
80
+
81
+ /** See {@link created}. Not exported from `src/index.ts`. */
82
+ export function derivedTriesCreatedForTests(): number {
83
+ return created;
84
+ }
85
+
86
+ export class DerivedStateTrie {
87
+ private readonly accounts: MerklePatriciaTrie;
88
+ /** Only accounts whose storage is non-empty have an entry. */
89
+ private readonly storage = new Map<PackedAddressKey, MerklePatriciaTrie>();
90
+
91
+ private constructor(
92
+ private readonly flat: OverlayStorageStateManager,
93
+ private readonly common: Common,
94
+ ) {
95
+ created++;
96
+ this.accounts = this.newTrie();
97
+ }
98
+
99
+ /**
100
+ * Build the trie from the WHOLE flat state. O(state), paid once per
101
+ * construction or load, never per block.
102
+ */
103
+ static async build(
104
+ flat: OverlayStorageStateManager,
105
+ common: Common,
106
+ ): Promise<DerivedStateTrie> {
107
+ const trie = new DerivedStateTrie(flat, common);
108
+ trie.requireNoCheckpoint('build');
109
+ // Storage first, so every account is written with its final storageRoot.
110
+ // The bottom overlay IS committed storage and holds no tombstones
111
+ // (./state-manager.ts), so its `written` map is the whole of it.
112
+ for (const [addressKey, slots] of flat.storageOverlays[0].written) {
113
+ const st = trie.newTrie();
114
+ for (const [slotKey, value] of slots)
115
+ await putSlot(st, packedKeyBytes(slotKey), value);
116
+ if (!isEmptyTrie(st)) trie.storage.set(addressKey, st);
117
+ }
118
+ for (const [addressHex, account] of flat.accountStack[0])
119
+ if (account !== undefined) await trie.writeAccount(addressHex);
120
+ return trie;
121
+ }
122
+
123
+ /**
124
+ * Bring the trie up to date with every key `changes` names, reading each
125
+ * key's CURRENT value from the flat state. Idempotent. O(keys named).
126
+ */
127
+ async apply(changes: ChangeSet): Promise<void> {
128
+ this.requireNoCheckpoint('apply');
129
+ const dirty = new Set<string>();
130
+ for (const addressHex of changes.accounts.keys()) dirty.add(addressHex);
131
+ for (const addressHex of changes.code.keys()) dirty.add(addressHex);
132
+ for (const addressKey of changes.storageCleared) {
133
+ this.storage.delete(addressKey);
134
+ dirty.add(unpackAddressKey(addressKey));
135
+ }
136
+ for (const [addressKey, slots] of changes.storage) {
137
+ const st = this.storage.get(addressKey) ?? this.newTrie();
138
+ for (const slotKey of slots.keys()) {
139
+ const value = this.flat.storageAt(addressKey, slotKey);
140
+ await putSlot(st, packedKeyBytes(slotKey), value);
141
+ }
142
+ if (isEmptyTrie(st)) this.storage.delete(addressKey);
143
+ else this.storage.set(addressKey, st);
144
+ dirty.add(unpackAddressKey(addressKey));
145
+ }
146
+ for (const addressHex of dirty) await this.writeAccount(addressHex);
147
+ }
148
+
149
+ /** The state root: the account trie's root. */
150
+ root(): Uint8Array {
151
+ return this.accounts.root();
152
+ }
153
+
154
+ /**
155
+ * Write one account into the account trie as the flat state holds it now,
156
+ * with its `storageRoot` from its storage trie, or delete it when the flat
157
+ * state has none.
158
+ */
159
+ private async writeAccount(addressHex: string): Promise<void> {
160
+ const key = hexToBytes(addressHex as `0x${string}`);
161
+ const account = this.flat.accountStack[0].get(addressHex as `0x${string}`);
162
+ if (account === undefined) {
163
+ await this.accounts.del(key);
164
+ return;
165
+ }
166
+ const st = this.storage.get(packAddressKey(key));
167
+ const derived = new Account(
168
+ account.nonce,
169
+ account.balance,
170
+ st === undefined ? undefined : st.root(),
171
+ account.codeHash,
172
+ );
173
+ await this.accounts.put(key, derived.serialize());
174
+ }
175
+
176
+ private newTrie(): MerklePatriciaTrie {
177
+ return new MerklePatriciaTrie({
178
+ useKeyHashing: true,
179
+ useNodePruning: true,
180
+ common: this.common,
181
+ });
182
+ }
183
+
184
+ /**
185
+ * The trie reads the BOTTOM of the flat state's stacks, which is committed
186
+ * state only while no checkpoint is open. Anything else would put a
187
+ * mid-execution state into the root, so it is refused rather than guessed at.
188
+ */
189
+ private requireNoCheckpoint(what: string): void {
190
+ if (
191
+ this.flat.accountStack.length !== 1 ||
192
+ this.flat.storageOverlays.length !== 1
193
+ )
194
+ throw new Error(
195
+ `webevm: the derived state trie was asked to ${what} with a checkpoint ` +
196
+ 'open; a state root is computed only between executions.',
197
+ );
198
+ }
199
+ }
200
+
201
+ /** One slot into a storage trie: shortest form, RLP-encoded; zero deletes. */
202
+ async function putSlot(
203
+ trie: MerklePatriciaTrie,
204
+ slot: Uint8Array,
205
+ value: Uint8Array | undefined,
206
+ ): Promise<void> {
207
+ const short = value === undefined ? undefined : unpadBytes(value);
208
+ if (short === undefined || short.length === 0) await trie.del(slot);
209
+ else await trie.put(slot, RLP.encode(short));
210
+ }
211
+
212
+ function isEmptyTrie(trie: MerklePatriciaTrie): boolean {
213
+ return equalsBytes(trie.root(), trie.EMPTY_TRIE_ROOT);
214
+ }
package/src/engine.ts CHANGED
@@ -237,8 +237,7 @@ function effectiveGasPrice(tx: TypedTransaction, blockBaseFee: bigint): bigint {
237
237
  * engine to mine on, so this is a missing capability the node cannot supply;
238
238
  * 3. its `connect(context)` throws, either because it cannot initialise (no
239
239
  * wasm, no memory) or because it refuses this node's configuration (the
240
- * revm engine refuses `stateMode:'trie'`, having no synchronous view of a
241
- * `MerkleStateManager` to read through).
240
+ * revm engine refuses a hardfork it cannot cost, ADR 0008).
242
241
  *
243
242
  * The engine's own message is preserved verbatim inside the thrown error's
244
243
  * message (not only as `cause`), because the engine is the only party that
@@ -279,7 +278,7 @@ export async function connectEngine(
279
278
  throw new Error(
280
279
  `webevm: the engine '${engine.id}' could not be connected, so the node was NOT created. ` +
281
280
  `It is deliberately NOT replaced by the default @ethereumjs/evm engine: that node would work, return correct results, and run at a completely different speed from the one you asked for, silently. ` +
282
- `Fix the configuration (this node is stateMode:'${context.stateMode}') or pass a different engine. Cause: ${message(err)}`,
281
+ `Fix the engine's configuration or pass a different engine. Cause: ${message(err)}`,
283
282
  {cause: err},
284
283
  );
285
284
  }
package/src/index.ts CHANGED
@@ -15,8 +15,8 @@ export type {
15
15
  ServedPort,
16
16
  NodeOptions,
17
17
  MiningConfig,
18
- StateMode,
19
18
  SenderMode,
19
+ StateHistoryOptions,
20
20
  // The engine seam: implement `Engine` to put a different EVM behind the node —
21
21
  // its reads (`call`) and its transactions (`transact`). Types only, so the core
22
22
  // never imports a non-default engine.
@@ -33,6 +33,7 @@ export type {
33
33
  PersistenceAdapter,
34
34
  RequestArguments,
35
35
  SerializedState,
36
+ SerializedHistoryBlock,
36
37
  } from './types.js';
37
38
  export {RpcError} from './types.js';
38
39
  // The revm engine is intentionally NOT re-exported here either, for the same