webevm 0.0.0 → 0.6.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 (73) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +693 -0
  3. package/dist/engine.d.ts +69 -0
  4. package/dist/engine.d.ts.map +1 -0
  5. package/dist/engine.js +269 -0
  6. package/dist/engine.js.map +1 -0
  7. package/dist/index.d.ts +12 -0
  8. package/dist/index.d.ts.map +1 -0
  9. package/dist/index.js +21 -0
  10. package/dist/index.js.map +1 -0
  11. package/dist/intrinsic-gas.d.ts +149 -0
  12. package/dist/intrinsic-gas.d.ts.map +1 -0
  13. package/dist/intrinsic-gas.js +94 -0
  14. package/dist/intrinsic-gas.js.map +1 -0
  15. package/dist/node.d.ts +3 -0
  16. package/dist/node.d.ts.map +1 -0
  17. package/dist/node.js +1931 -0
  18. package/dist/node.js.map +1 -0
  19. package/dist/persistence.d.ts +22 -0
  20. package/dist/persistence.d.ts.map +1 -0
  21. package/dist/persistence.js +54 -0
  22. package/dist/persistence.js.map +1 -0
  23. package/dist/revm-state-store.d.ts +89 -0
  24. package/dist/revm-state-store.d.ts.map +1 -0
  25. package/dist/revm-state-store.js +394 -0
  26. package/dist/revm-state-store.js.map +1 -0
  27. package/dist/revm.d.ts +124 -0
  28. package/dist/revm.d.ts.map +1 -0
  29. package/dist/revm.js +657 -0
  30. package/dist/revm.js.map +1 -0
  31. package/dist/sender-recovery.d.ts +78 -0
  32. package/dist/sender-recovery.d.ts.map +1 -0
  33. package/dist/sender-recovery.js +53 -0
  34. package/dist/sender-recovery.js.map +1 -0
  35. package/dist/state-manager.d.ts +327 -0
  36. package/dist/state-manager.d.ts.map +1 -0
  37. package/dist/state-manager.js +439 -0
  38. package/dist/state-manager.js.map +1 -0
  39. package/dist/storage-keys.d.ts +21 -0
  40. package/dist/storage-keys.d.ts.map +1 -0
  41. package/dist/storage-keys.js +113 -0
  42. package/dist/storage-keys.js.map +1 -0
  43. package/dist/types.d.ts +696 -0
  44. package/dist/types.d.ts.map +1 -0
  45. package/dist/types.js +12 -0
  46. package/dist/types.js.map +1 -0
  47. package/dist/worker-client.d.ts +21 -0
  48. package/dist/worker-client.d.ts.map +1 -0
  49. package/dist/worker-client.js +77 -0
  50. package/dist/worker-client.js.map +1 -0
  51. package/dist/worker-entry.d.ts +32 -0
  52. package/dist/worker-entry.d.ts.map +1 -0
  53. package/dist/worker-entry.js +29 -0
  54. package/dist/worker-entry.js.map +1 -0
  55. package/dist/worker-host.d.ts +75 -0
  56. package/dist/worker-host.d.ts.map +1 -0
  57. package/dist/worker-host.js +188 -0
  58. package/dist/worker-host.js.map +1 -0
  59. package/package.json +90 -2
  60. package/src/engine.ts +300 -0
  61. package/src/index.ts +46 -0
  62. package/src/intrinsic-gas.ts +191 -0
  63. package/src/node.ts +2150 -0
  64. package/src/persistence.ts +80 -0
  65. package/src/revm-state-store.ts +455 -0
  66. package/src/revm.ts +809 -0
  67. package/src/sender-recovery.ts +142 -0
  68. package/src/state-manager.ts +531 -0
  69. package/src/storage-keys.ts +150 -0
  70. package/src/types.ts +717 -0
  71. package/src/worker-client.ts +112 -0
  72. package/src/worker-entry.ts +31 -0
  73. package/src/worker-host.ts +232 -0
@@ -0,0 +1,150 @@
1
+ /**
2
+ * storage-keys.ts — the node's `stateMode:'none'` STORAGE KEY encoding, and the
3
+ * ONE place either side of it is allowed to build a key.
4
+ *
5
+ * A storage key here is **PACKED**: two bytes per UTF-16 code unit, so an
6
+ * address is 10 code units and a slot is 16, rather than the 42- and
7
+ * 66-character `0x`-hex strings the node used to build. It is `revm-wasm`'s own
8
+ * `MemoryStore` encoding, adopted for the reason it exists there.
9
+ *
10
+ * ## Why, with the number
11
+ *
12
+ * A cold revm storage access with the `0x`-hex key was 1.21-1.33 µs through the
13
+ * real wasm module, and **83-87% of that was JS-side key handling**, not the wasm
14
+ * crossing (0.17-0.20 µs). Per-account NESTING recovers none of it (the cost is
15
+ * building hex at all, not concatenating it). This encoding takes the access to
16
+ * **0.36-0.39 µs: 70-73% recovered**, measured against the SHIPPED store, arm for
17
+ * arm, in `docs/spikes/revm-state-store-packed-storage-keys/measurements.md`. The
18
+ * question was first asked, of four candidate stores, in
19
+ * `docs/spikes/spike-storage-layout-cost-for-the-revm-write-half/measurements.md`
20
+ * (Q4), which predicted 50% from a prototype.
21
+ *
22
+ * The win was only available once the NODE owned the representation, which it
23
+ * does as of ADR 0009; before that the key format was `SimpleStateManager`'s and
24
+ * had to be reproduced byte for byte (ADR 0005).
25
+ *
26
+ * ## THE DANGEROUS FAILURE IS TWO KEY FORMATS THAT BOTH WORK
27
+ *
28
+ * `@ethereumjs/evm` writes storage through the ASYNC `putStorage`; revm reads it
29
+ * through the SYNCHRONOUS `storageAt`. If those two disagreed about the key,
30
+ * every read would be a MISS — and a miss reads as ZERO, not as an error, and
31
+ * costs identical gas, so neither the cross-backend gas gate nor any receipt
32
+ * diff could see it. That is why this module exists at all instead of two
33
+ * private helpers: `src/state-manager.ts` (the async half, plus `dumpState`'s
34
+ * view) and `src/revm-state-store.ts` (the synchronous half) both import THESE
35
+ * functions, so the two formats cannot drift without an edit that is visible
36
+ * here. `test/helpers/revm-storage-keys.ts` then asserts the agreement end to
37
+ * end, in both directions, on a real slot.
38
+ *
39
+ * ## Fixed width, and why it is not a generic "pack any bytes"
40
+ *
41
+ * A length-agnostic pack is NOT injective: a 31-byte key and the 32-byte key
42
+ * with a trailing zero byte produce the same string, i.e. two different slots
43
+ * would silently become one. So the two encoders take a FIXED width (20 bytes
44
+ * for an address, 32 for a slot) and NORMALISE anything else by left-padding it
45
+ * to that width rather than encoding it ambiguously. Normalising is safe and
46
+ * unreachable in practice: `@ethereumjs/evm` always hands over a 32-byte slot
47
+ * key, every caller in `src/node.ts` pads to 32 first, and `MerkleStateManager`
48
+ * (the other state mode) REFUSES a key that is not 32 bytes at all — so a short
49
+ * key names the slot it obviously means instead of an unreadable one.
50
+ *
51
+ * ## What this is NOT the key format for
52
+ *
53
+ * ACCOUNTS and CODE. Those live in `SimpleStateManager`'s own `accountStack` /
54
+ * `codeStack`, keyed `address.toString()` (`0x`-prefixed lowercase hex), and
55
+ * that format is upstream's to dictate — ADR 0005's "reproduce it byte for byte"
56
+ * still applies there, unchanged.
57
+ *
58
+ * The SERIALISED format is not this either. `dumpState` / `loadState` output is
59
+ * persisted data (IndexedDB, `loadState` fixtures) and stays `{address: {slot:
60
+ * value}}` in `0x`-hex: {@link OverlayStorageStateManager.liveStorage} converts
61
+ * back through {@link unpackAddressKey} / {@link unpackSlotKey} on the way out,
62
+ * and `test/storage-overlay.spec.ts` asserts the dump byte-identical against a
63
+ * fixture captured from the pre-overlay build. The internal key moves under that
64
+ * format; the format does not move.
65
+ */
66
+ import {setLengthLeft} from '@ethereumjs/util';
67
+
68
+ /** One byte as two lowercase hex digits, for the dump-path conversions below. */
69
+ const HEX_BYTE = /* @__PURE__ */ (() => {
70
+ const t: string[] = [];
71
+ for (let i = 0; i < 256; i++) t.push(i.toString(16).padStart(2, '0'));
72
+ return t;
73
+ })();
74
+
75
+ /** An account's storage key: 10 UTF-16 code units, two address bytes each. */
76
+ export type PackedAddressKey = string;
77
+ /** A slot's storage key: 16 UTF-16 code units, two slot bytes each. */
78
+ export type PackedSlotKey = string;
79
+ /** `0x`-prefixed lowercase hex — the SERIALISED (dumpState) form of either. */
80
+ export type HexKey = string;
81
+
82
+ /**
83
+ * The storage key for an account, from its 20 address bytes.
84
+ *
85
+ * Takes the BYTES rather than an `Address` on purpose: the synchronous revm
86
+ * store is handed revm's own 20-byte scratch buffer and must not have to
87
+ * construct anything to build a key. Pass `address.bytes` from the async side.
88
+ */
89
+ export function packAddressKey(address: Uint8Array): PackedAddressKey {
90
+ if (address.length !== 20) return packAddressKey(setLengthLeft(address, 20));
91
+ return String.fromCharCode(
92
+ (address[0] << 8) | address[1],
93
+ (address[2] << 8) | address[3],
94
+ (address[4] << 8) | address[5],
95
+ (address[6] << 8) | address[7],
96
+ (address[8] << 8) | address[9],
97
+ (address[10] << 8) | address[11],
98
+ (address[12] << 8) | address[13],
99
+ (address[14] << 8) | address[15],
100
+ (address[16] << 8) | address[17],
101
+ (address[18] << 8) | address[19],
102
+ );
103
+ }
104
+
105
+ /** The storage key for one slot, from its 32 key bytes. */
106
+ export function packSlotKey(slot: Uint8Array): PackedSlotKey {
107
+ if (slot.length !== 32) return packSlotKey(setLengthLeft(slot, 32));
108
+ return String.fromCharCode(
109
+ (slot[0] << 8) | slot[1],
110
+ (slot[2] << 8) | slot[3],
111
+ (slot[4] << 8) | slot[5],
112
+ (slot[6] << 8) | slot[7],
113
+ (slot[8] << 8) | slot[9],
114
+ (slot[10] << 8) | slot[11],
115
+ (slot[12] << 8) | slot[13],
116
+ (slot[14] << 8) | slot[15],
117
+ (slot[16] << 8) | slot[17],
118
+ (slot[18] << 8) | slot[19],
119
+ (slot[20] << 8) | slot[21],
120
+ (slot[22] << 8) | slot[23],
121
+ (slot[24] << 8) | slot[25],
122
+ (slot[26] << 8) | slot[27],
123
+ (slot[28] << 8) | slot[29],
124
+ (slot[30] << 8) | slot[31],
125
+ );
126
+ }
127
+
128
+ /** `0x` + 40 hex digits, i.e. exactly what `address.toString()` would give. */
129
+ export function unpackAddressKey(key: PackedAddressKey): HexKey {
130
+ return unpack(key);
131
+ }
132
+
133
+ /** `0x` + 64 hex digits, i.e. exactly what `bytesToHex(slot32)` would give. */
134
+ export function unpackSlotKey(key: PackedSlotKey): HexKey {
135
+ return unpack(key);
136
+ }
137
+
138
+ /**
139
+ * The inverse of the two encoders, for the dump path ONLY — it allocates a
140
+ * string per key and is O(live slots) over a whole dump. Read one slot with
141
+ * `storageAt()`; never round-trip a key through here to read it.
142
+ */
143
+ function unpack(key: string): HexKey {
144
+ let s = '0x';
145
+ for (let i = 0; i < key.length; i++) {
146
+ const c = key.charCodeAt(i);
147
+ s += HEX_BYTE[c >>> 8] + HEX_BYTE[c & 0xff];
148
+ }
149
+ return s;
150
+ }