diff --git a/CHANGELOG.md b/CHANGELOG.md index 80f805415e..f8d0fda649 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -92,6 +92,14 @@ The sections do not signal obligations; the prefixes do. it uses. If members depend on each other in a cycle, the pointer is invalid." +- The description of `places` in the fixed-point types calls the integer + before scaling an "unscaled value" instead of a "raw value". "Raw" now + means bytes only. + - Schemas: **ethdebug/format/type/elementary/fixed**, + **ethdebug/format/type/elementary/ufixed** + - Producers: no change needed. + - Consumers: no change needed. + - Variables now have a stated sort. A list's `each` variable is an integer. A `define` variable has the sort of its expression, so a bytes variable keeps its width. A template's `expect`ed variable takes the sort of the diff --git a/RELEASING.md b/RELEASING.md index f4dcd33d9c..14afbe0201 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -21,8 +21,8 @@ guards that run in CI live in `bin/check-tarballs.ts` and packages work but implement a draft. Releases before `0.1.0-draft.0` used a plain number (`0.1.0-0` to `0.1.0-2`); they sort before the named ones. -- Ten workspaces can take part in a release: the seven public - packages (`format`, `pointers`, `evm`, `bugc`, `bugc-react`, +- Eleven workspaces can take part in a release: the eight public + packages (`format`, `common`, `pointers`, `evm`, `bugc`, `bugc-react`, `pointers-react`, `programs-react`) and the three private ones (`format-web`, `bug-playground`, `conformance`). Private workspaces get versions and tags like the others, but the publish script skips @@ -32,8 +32,9 @@ guards that run in CI live in `bin/check-tarballs.ts` and not count), `@ethdebug/format` when `schemas/` changed (the schemas live outside the package directory but ship inside it), and every workspace that depends on a moving one, directly or transitively. - Every workspace depends on `@ethdebug/format`, so a specification - change moves all ten. + Every workspace except `@ethdebug/common` and `@ethdebug/evm` + depends on `@ethdebug/format`, so a specification change moves the + other nine. - Series convention, for now: all workspaces start a `major.minor` series together and graduate together with the spec; between those events each workspace moves only when it or a dependency changed, diff --git a/bin/check-react-consumers.ts b/bin/check-react-consumers.ts index 6503056824..871c745673 100644 --- a/bin/check-react-consumers.ts +++ b/bin/check-react-consumers.ts @@ -9,6 +9,7 @@ import { join } from "node:path"; // type-checks with skipLibCheck off, so a broken .d.ts fails. const packed = [ "format", + "common", "pointers", "evm", "programs-react", diff --git a/bin/start b/bin/start index 05b20cc07e..84527ea3bc 100755 --- a/bin/start +++ b/bin/start @@ -11,8 +11,9 @@ fi # Run the commands with concurrently concurrently \ - --names=format,pointers,evm,bugc,bugc-react,pointers-react,programs-react,playground,web,tests \ + --names=format,common,pointers,evm,bugc,bugc-react,pointers-react,programs-react,playground,web,tests \ "cd ./packages/format && yarn watch" \ + "cd ./packages/common && yarn watch" \ "cd ./packages/pointers && yarn watch" \ "cd ./packages/evm && yarn watch" \ "cd ./packages/bugc && yarn watch" \ diff --git a/packages/bugc-react/tsconfig.typecheck.json b/packages/bugc-react/tsconfig.typecheck.json index 2d774f1e30..5f1f2bd6ee 100644 --- a/packages/bugc-react/tsconfig.typecheck.json +++ b/packages/bugc-react/tsconfig.typecheck.json @@ -7,6 +7,7 @@ "rootDir": "../..", "paths": { "@ethdebug/bugc": ["../bugc/src/index.ts"], + "@ethdebug/common": ["../common/src/index.ts"], "@ethdebug/evm": ["../evm/src/index.ts"], "@ethdebug/format": ["../format/src/index.ts"], "@ethdebug/pointers": ["../pointers/src/index.ts"], diff --git a/packages/bugc/CHANGELOG.md b/packages/bugc/CHANGELOG.md index 5cdaa2b151..07339ddd49 100644 --- a/packages/bugc/CHANGELOG.md +++ b/packages/bugc/CHANGELOG.md @@ -40,6 +40,8 @@ support. Changes to the specification itself are tracked in the root ### Changed +- The tests read machine state as `Raw` from `@ethdebug/common`, a new + development dependency. - `==`, `!=` and a mapping key with bytes or a string in calldata are now type errors. Before, they compared or hashed the calldata reference's word (offset and length), not the bytes ([#379]). diff --git a/packages/bugc/package.json b/packages/bugc/package.json index 9e2f3099dc..7312e10460 100644 --- a/packages/bugc/package.json +++ b/packages/bugc/package.json @@ -209,6 +209,7 @@ }, "license": "MIT", "devDependencies": { + "@ethdebug/common": "^0.1.0-preview.2", "@ethdebug/evm": "^0.1.0-preview.2", "@ethdebug/pointers": "^0.1.0-preview.2", "@hyperjump/browser": "^1.2.0", diff --git a/packages/bugc/src/evmgen/call-contexts.test.ts b/packages/bugc/src/evmgen/call-contexts.test.ts index 8ab682099d..bfdf4c1cb1 100644 --- a/packages/bugc/src/evmgen/call-contexts.test.ts +++ b/packages/bugc/src/evmgen/call-contexts.test.ts @@ -3,6 +3,7 @@ import { describe, it, expect } from "vitest"; import { compile } from "#compiler"; import type * as Format from "@ethdebug/format"; import { Pointer, Program } from "@ethdebug/format"; +import { Raw } from "@ethdebug/common"; import { dereference } from "@ethdebug/pointers"; import { traceLocals } from "#test/evm/locals"; @@ -140,7 +141,7 @@ code { const view = await cursor.view(state); const values = await Promise.all( ["a", "b"].map(async (name) => - (await view.read(view.regions.lookup[name])).asUint(), + Raw.asUint(await view.read(view.regions.lookup[name])), ), ); expect(values).toEqual([10n, 20n]); diff --git a/packages/bugc/src/evmgen/call-timing.test.ts b/packages/bugc/src/evmgen/call-timing.test.ts index 54e6bf028a..a85eb0a19f 100644 --- a/packages/bugc/src/evmgen/call-timing.test.ts +++ b/packages/bugc/src/evmgen/call-timing.test.ts @@ -9,6 +9,7 @@ * `return` data pointer must read the returned value. */ import { describe, it, expect } from "vitest"; +import { Raw } from "@ethdebug/common"; import { dereference } from "@ethdebug/pointers"; import { Program } from "@ethdebug/format"; import type * as Format from "@ethdebug/format"; @@ -157,7 +158,7 @@ describe("call frame timing", () => { const state = stateAt(i); const cursor = await dereference(ret.data.pointer, { state }); const view = await cursor.view(state); - read.push((await view.read(view.regions[0])).asUint()); + read.push(Raw.asUint(await view.read(view.regions[0]))); } else { read.push(undefined); } diff --git a/packages/bugc/src/evmgen/debug/local-variables.soundness.test.ts b/packages/bugc/src/evmgen/debug/local-variables.soundness.test.ts index 71ead6bba0..26295d270a 100644 --- a/packages/bugc/src/evmgen/debug/local-variables.soundness.test.ts +++ b/packages/bugc/src/evmgen/debug/local-variables.soundness.test.ts @@ -12,6 +12,7 @@ import { describe, it, expect } from "vitest"; import { Program } from "@ethdebug/format"; import type * as Format from "@ethdebug/format"; +import { Raw } from "@ethdebug/common"; import { dereference } from "@ethdebug/pointers"; import { executeProgram } from "#test/evm/behavioral"; import { @@ -1707,16 +1708,16 @@ describe.each(levels)("a calldata reference's word at O%i", (level) => { return regions[0]; }); expect(length.location).toEqual(offset.location); - expect(offset.length?.asUint()).toEqual(16n); - expect(length.length?.asUint()).toEqual(16n); + expect(offset.length && Raw.asUint(offset.length)).toEqual(16n); + expect(length.length && Raw.asUint(length.length)).toEqual(16n); if (offset.location === "stack" && length.location === "stack") { - expect(length.slot.asUint()).toEqual(offset.slot.asUint()); - expect(offset.offset?.asUint()).toEqual(0n); - expect(length.offset?.asUint()).toEqual(16n); + expect(Raw.asUint(length.slot)).toEqual(Raw.asUint(offset.slot)); + expect(offset.offset && Raw.asUint(offset.offset)).toEqual(0n); + expect(length.offset && Raw.asUint(length.offset)).toEqual(16n); } else { expect(offset.location).toEqual("memory"); - expect(length.offset!.asUint()).toEqual( - offset.offset!.asUint() + 16n, + expect(Raw.asUint(length.offset!)).toEqual( + Raw.asUint(offset.offset!) + 16n, ); } expect(view.regions.named(name)).toHaveLength(0); diff --git a/packages/bugc/src/evmgen/storage-array-layout.test.ts b/packages/bugc/src/evmgen/storage-array-layout.test.ts index 16c4c2b8da..0f2aa66fd3 100644 --- a/packages/bugc/src/evmgen/storage-array-layout.test.ts +++ b/packages/bugc/src/evmgen/storage-array-layout.test.ts @@ -12,6 +12,7 @@ import { describe, it, expect } from "vitest"; import { keccak256 } from "ethereum-cryptography/keccak"; import { bytesToHex } from "ethereum-cryptography/utils"; +import { Raw } from "@ethdebug/common"; import { dereference } from "@ethdebug/pointers"; import type * as Format from "@ethdebug/format"; @@ -173,7 +174,7 @@ describe("storage array pointers", () => { const read = await Promise.all( view.regions .filter((region) => region.name === regionName) - .map(async (region) => (await view.read(region)).asUint()), + .map(async (region) => Raw.asUint(await view.read(region))), ); expect(read, `${identifier}: ${regionName}`).toEqual(values); } diff --git a/packages/bugc/src/evmgen/storage-array-push.test.ts b/packages/bugc/src/evmgen/storage-array-push.test.ts index cf7f9d86ad..c4ff619c92 100644 --- a/packages/bugc/src/evmgen/storage-array-push.test.ts +++ b/packages/bugc/src/evmgen/storage-array-push.test.ts @@ -7,6 +7,7 @@ import { describe, it, expect } from "vitest"; import { keccak256 } from "ethereum-cryptography/keccak"; import { bytesToHex } from "ethereum-cryptography/utils"; +import { Raw } from "@ethdebug/common"; import { dereference } from "@ethdebug/pointers"; import type * as Format from "@ethdebug/format"; @@ -143,7 +144,7 @@ code { h.push(5); h.push(7); h.push(9); }`, const read = await Promise.all( view.regions .filter((region) => region.name === "element") - .map(async (region) => (await view.read(region)).asUint()), + .map(async (region) => Raw.asUint(await view.read(region))), ); expect(read).toEqual([5n, 7n, 9n]); }); diff --git a/packages/bugc/src/irgen/debug/templates.test.ts b/packages/bugc/src/irgen/debug/templates.test.ts index 372d0f9b50..20c19009be 100644 --- a/packages/bugc/src/irgen/debug/templates.test.ts +++ b/packages/bugc/src/irgen/debug/templates.test.ts @@ -13,7 +13,8 @@ import path from "path"; import { glob } from "glob"; import * as Format from "@ethdebug/format"; import { createMachineState } from "@ethdebug/evm"; -import { dereference, type Data, type Machine } from "@ethdebug/pointers"; +import { type Machine, Raw } from "@ethdebug/common"; +import { dereference } from "@ethdebug/pointers"; import { localsOf, traceLocals } from "#test/evm/locals"; import { parseTestBlocks } from "#test/examples/annotations"; @@ -97,15 +98,15 @@ async function read( ).view(state); const regions = []; for (const region of view.regions) { - const at = (["slot", "offset", "length"] as const).map((key) => [ - key, - (region as Partial>)[key]?.toHex(), - ]); + const at = (["slot", "offset", "length"] as const).map((key) => { + const value = (region as Partial>)[key]; + return [key, value && Raw.toHex(value)]; + }); regions.push({ name: region.name, location: region.location, ...Object.fromEntries(at), - bytes: (await view.read(region)).toHex(), + bytes: Raw.toHex(await view.read(region)), }); } return regions; diff --git a/packages/bugc/src/irgen/debug/variables.test.ts b/packages/bugc/src/irgen/debug/variables.test.ts index 6ab1ca9033..7b6c4e14be 100644 --- a/packages/bugc/src/irgen/debug/variables.test.ts +++ b/packages/bugc/src/irgen/debug/variables.test.ts @@ -8,6 +8,7 @@ import { describe, it, expect } from "vitest"; import { bytesToHex, hexToBytes } from "ethereum-cryptography/utils"; import { Executor, createMachineState } from "@ethdebug/evm"; +import { Raw } from "@ethdebug/common"; import { dereference } from "@ethdebug/pointers"; import * as Format from "@ethdebug/format"; @@ -242,7 +243,7 @@ code { expect(inner.name).toEqual("value"); if (!("slot" in inner)) throw new Error("not a storage region"); const cell = entryOf(pointerOf("grid"), templates, "value-entry", { - slot: inner.slot.toHex(), + slot: Raw.toHex(inner.slot), key: text.length, }); expect(await readRegions(cell, state, templates, "value")).toEqual([ diff --git a/packages/bugc/src/irgen/generate/storage.test.ts b/packages/bugc/src/irgen/generate/storage.test.ts index daa61aa571..0aecd9847b 100644 --- a/packages/bugc/src/irgen/generate/storage.test.ts +++ b/packages/bugc/src/irgen/generate/storage.test.ts @@ -2,6 +2,7 @@ import { describe, it, expect } from "vitest"; import { keccak256 } from "ethereum-cryptography/keccak"; import { bytesToHex, hexToBytes } from "ethereum-cryptography/utils"; +import { Raw } from "@ethdebug/common"; import { dereference } from "@ethdebug/pointers"; import { createMachineState } from "@ethdebug/evm"; @@ -136,7 +137,7 @@ describe("packed storage struct field pointers", () => { }); const view = await cursor.view(state); const read = async (name: string) => - (await view.read(view.regions.lookup[name])).asUint(); + Raw.asUint(await view.read(view.regions.lookup[name])); expect(await read("a")).toBe(7n); expect(await read("b")).toBe(1988n); diff --git a/packages/bugc/test/evm/locals.ts b/packages/bugc/test/evm/locals.ts index 067a1cfc0f..1ac5779f5f 100644 --- a/packages/bugc/test/evm/locals.ts +++ b/packages/bugc/test/evm/locals.ts @@ -13,7 +13,8 @@ import { type Trace, type TraceStep, } from "@ethdebug/evm"; -import { dereference, type Machine } from "@ethdebug/pointers"; +import { type Machine, Raw } from "@ethdebug/common"; +import { dereference } from "@ethdebug/pointers"; import { bytesToHex } from "ethereum-cryptography/utils"; import type * as Format from "@ethdebug/format"; @@ -347,8 +348,8 @@ async function regionsAt(pointer: unknown, run: LocalsTrace, index: number) { const data = await view.read(region); if (region.location === "memory" || region.location === "calldata") { const bytes = region.location === "memory" ? memory : calldata; - const start = region.offset!.asUint(); - const length = region.length!.asUint(); + const start = Raw.asUint(region.offset!); + const length = Raw.asUint(region.length!); if (offset !== undefined && start !== offset) { throw new Error(`${name} at ${start}, expected ${offset}`); } @@ -357,7 +358,7 @@ async function regionsAt(pointer: unknown, run: LocalsTrace, index: number) { } const actual = new Uint8Array(Number(length)); actual.set(bytes.slice(Number(start), Number(start + length))); - if (data.toHex() !== "0x" + bytesToHex(actual)) { + if (Raw.toHex(data) !== "0x" + bytesToHex(actual)) { throw new Error( `${name} does not read ${region.location} at ${start}`, ); @@ -377,7 +378,7 @@ async function readScalar( ): Promise { const regions = await regionsAt(pointer, run, index); regions.seek(name); - return (await regions.read(name)).toHex(); + return Raw.toHex(await regions.read(name)); } /** @@ -400,9 +401,9 @@ async function readReference( if (shape.kind === "calldata") { regions.seek(`${name}-offset`); - const offset = (await regions.read(`${name}-offset`)).asUint(); - const length = (await regions.read(`${name}-length`)).asUint(); - return (await regions.read(`${name}-data`, offset, length)).toHex(); + const offset = Raw.asUint(await regions.read(`${name}-offset`)); + const length = Raw.asUint(await regions.read(`${name}-length`)); + return Raw.toHex(await regions.read(`${name}-data`, offset, length)); } regions.seek(name); @@ -415,9 +416,9 @@ async function readReference( ): Promise => { if (shape.kind === "scalar") { const size = BigInt(shape.size); - return (await regions.read(prefix, word + 32n - size, size)).asUint(); + return Raw.asUint(await regions.read(prefix, word + 32n - size, size)); } - const address = (await regions.read(prefix, word, 32n)).asUint(); + const address = Raw.asUint(await regions.read(prefix, word, 32n)); return decode(shape, prefix, address); }; @@ -435,9 +436,13 @@ async function readReference( } return value; } - const length = (await regions.read(`${prefix}-length`, base, 32n)).asUint(); + const length = Raw.asUint( + await regions.read(`${prefix}-length`, base, 32n), + ); if (shape.kind !== "array") { - return (await regions.read(`${prefix}-data`, base + 32n, length)).toHex(); + return Raw.toHex( + await regions.read(`${prefix}-data`, base + 32n, length), + ); } const values: RefValue[] = []; for (let i = 0n; i < length; i++) { @@ -447,6 +452,6 @@ async function readReference( return values; }; - const base = (await regions.read(name)).asUint(); + const base = Raw.asUint(await regions.read(name)); return decode(shape, name, base); } diff --git a/packages/bugc/test/examples/runners.ts b/packages/bugc/test/examples/runners.ts index 66629055cb..05d48b35c3 100644 --- a/packages/bugc/test/examples/runners.ts +++ b/packages/bugc/test/examples/runners.ts @@ -7,6 +7,7 @@ import type * as Evm from "#evm"; import * as Format from "@ethdebug/format"; +import { Raw } from "@ethdebug/common"; import { dereference } from "@ethdebug/pointers"; import { bytesToHex } from "ethereum-cryptography/utils"; @@ -184,7 +185,7 @@ async function checkScalarValue( } const data = await view.read(view.regions[0]); - const actual = data.asUint(); + const actual = Raw.asUint(data); const expected = BigInt(expectedValue); if (actual !== expected) { @@ -275,7 +276,7 @@ async function checkRegionValues( for (let i = 0; i < expectedValue.length; i++) { const data = await view.read(regions[i]); - const actual = data.asUint(); + const actual = Raw.asUint(data); const expected = BigInt(expectedValue[i]); if (actual !== expected) { @@ -292,7 +293,7 @@ async function checkRegionValues( } else { // Check single region const data = await view.read(regions[0]); - const actual = data.asUint(); + const actual = Raw.asUint(data); const expected = BigInt(expectedValue); if (actual !== expected) { diff --git a/packages/bugc/tsconfig.build.json b/packages/bugc/tsconfig.build.json index f394fe4c90..803a342381 100644 --- a/packages/bugc/tsconfig.build.json +++ b/packages/bugc/tsconfig.build.json @@ -11,6 +11,7 @@ ], "references": [ { "path": "../format/tsconfig.build.json" }, + { "path": "../common/tsconfig.build.json" }, { "path": "../pointers/tsconfig.build.json" }, { "path": "../evm/tsconfig.build.json" } ] diff --git a/packages/bugc/tsconfig.json b/packages/bugc/tsconfig.json index 845e84acc5..56999db46d 100644 --- a/packages/bugc/tsconfig.json +++ b/packages/bugc/tsconfig.json @@ -63,6 +63,7 @@ "exclude": ["node_modules", "dist"], "references": [ { "path": "../format" }, + { "path": "../common" }, { "path": "../pointers" }, { "path": "../evm" } ] diff --git a/packages/bugc/tsconfig.typecheck.json b/packages/bugc/tsconfig.typecheck.json index ef688383cb..bf9988627e 100644 --- a/packages/bugc/tsconfig.typecheck.json +++ b/packages/bugc/tsconfig.typecheck.json @@ -6,6 +6,7 @@ "incremental": false, "rootDir": "../..", "paths": { + "@ethdebug/common": ["../common/src/index.ts"], "@ethdebug/evm": ["../evm/src/index.ts"], "@ethdebug/format": ["../format/src/index.ts"], "@ethdebug/pointers": ["../pointers/src/index.ts"] diff --git a/packages/common/CHANGELOG.md b/packages/common/CHANGELOG.md new file mode 100644 index 0000000000..d42401b19a --- /dev/null +++ b/packages/common/CHANGELOG.md @@ -0,0 +1,18 @@ +# Changelog + +This file tracks changes to the `@ethdebug/common` npm package, the runtime +code that the `ethdebug/format` packages share. Changes to the specification +itself are tracked in the root [`CHANGELOG.md`](../../CHANGELOG.md). + +## Unreleased + +### Added + +- First release. `Raw` is a byte string (a `Uint8Array`) with functions to + make, read and resize one (`Raw.fromHex`, `Raw.toHex`, `Raw.asUint`, + `Raw.resizeTo`, `Raw.concat`, and so on). It replaces the `Data` class from + `@ethdebug/pointers`. +- The `Machine` interfaces, which describe the EVM state that a debugger reads + (stack, memory, storage, calldata, returndata, transient storage and code). + Every read gives a `Raw`. They used to live in `@ethdebug/pointers`. +- `keccak256(raw)`, the Keccak-256 hash of a `Raw`. diff --git a/packages/common/LICENSE b/packages/common/LICENSE new file mode 100644 index 0000000000..5d84fb65eb --- /dev/null +++ b/packages/common/LICENSE @@ -0,0 +1,25 @@ +Note: This license applies to all files in this repository EXCEPT those in the +schemas/ directory, which are licensed under CC0 1.0 Universal. See +schemas/LICENSE for details. + +MIT License + +Copyright (c) 2024 ethdebug contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/packages/common/README.md b/packages/common/README.md new file mode 100644 index 0000000000..caaf40597b --- /dev/null +++ b/packages/common/README.md @@ -0,0 +1,15 @@ +# @ethdebug/common + +_This NPM package contains runtime code that the **ethdebug/format** packages +share._ + +It provides `Raw`, a byte string (a `Uint8Array`) with functions to make, +read and resize one; the `Machine` interfaces, which model a running EVM for +a debugger to read; and `keccak256`. `@ethdebug/pointers`, `@ethdebug/evm` +and the React packages use it. + +## TypeScript + +This package uses `package.json` `imports` for internal modules. +Consumers must use `moduleResolution` `node16`, `nodenext`, or +`bundler`. The legacy `node10` resolution is not supported. diff --git a/packages/common/package.json b/packages/common/package.json new file mode 100644 index 0000000000..e360e2d11e --- /dev/null +++ b/packages/common/package.json @@ -0,0 +1,52 @@ +{ + "name": "@ethdebug/common", + "version": "0.1.0-preview.2", + "description": "Shared runtime code for the ethdebug/format packages", + "main": "dist/src/index.js", + "type": "module", + "repository": { + "type": "git", + "url": "git+https://github.com/ethdebug/format.git", + "directory": "packages/common" + }, + "license": "MIT", + "files": [ + "dist", + "!dist/**/*.tsbuildinfo", + "CHANGELOG.md" + ], + "engines": { + "node": ">=20" + }, + "imports": { + "#raw": { + "types": "./src/raw.ts", + "default": "./dist/src/raw.js" + }, + "#machine": { + "types": "./src/machine.ts", + "default": "./dist/src/machine.js" + }, + "#keccak": { + "types": "./src/keccak.ts", + "default": "./dist/src/keccak.js" + } + }, + "scripts": { + "build": "rm -rf dist && tsc --build tsconfig.build.json", + "prepare": "yarn build", + "typecheck": "tsc -p tsconfig.typecheck.json", + "watch": "tsc --build --watch", + "test": "vitest" + }, + "devDependencies": { + "typescript": "^5.9.3", + "vitest": "^3.2.4" + }, + "dependencies": { + "ethereum-cryptography": "^2.2.1" + }, + "publishConfig": { + "access": "public" + } +} diff --git a/packages/common/src/index.ts b/packages/common/src/index.ts new file mode 100644 index 0000000000..228b768074 --- /dev/null +++ b/packages/common/src/index.ts @@ -0,0 +1,3 @@ +export { Raw } from "#raw"; +export type { Machine } from "#machine"; +export { keccak256 } from "#keccak"; diff --git a/packages/common/src/keccak.test.ts b/packages/common/src/keccak.test.ts new file mode 100644 index 0000000000..b0024162d5 --- /dev/null +++ b/packages/common/src/keccak.test.ts @@ -0,0 +1,18 @@ +import { expect, describe, it } from "vitest"; + +import { Raw } from "#raw"; +import { keccak256 } from "#keccak"; + +describe("keccak256", () => { + it("hashes the empty string", () => { + expect(Raw.toHex(keccak256(Raw.zero()))).toBe( + "0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470", + ); + }); + + it("hashes a zero word", () => { + expect(Raw.toHex(keccak256(Raw.fromHex("0x" + "00".repeat(32))))).toBe( + "0x290decd9548b62a8d60345a988386fc84ba6bc95484008f6362f93160ef3e563", + ); + }); +}); diff --git a/packages/common/src/keccak.ts b/packages/common/src/keccak.ts new file mode 100644 index 0000000000..d5ee0b9c1f --- /dev/null +++ b/packages/common/src/keccak.ts @@ -0,0 +1,10 @@ +import { keccak256 as hash } from "ethereum-cryptography/keccak"; + +import type { Raw } from "#raw"; + +/** + * The Keccak-256 hash of a byte string, as the EVM computes it. + */ +export function keccak256(raw: Raw): Raw { + return hash(raw); +} diff --git a/packages/pointers/src/machine.ts b/packages/common/src/machine.ts similarity index 78% rename from packages/pointers/src/machine.ts rename to packages/common/src/machine.ts index 293140ceb8..8b6413d6ce 100644 --- a/packages/pointers/src/machine.ts +++ b/packages/common/src/machine.ts @@ -1,4 +1,4 @@ -import type { Data } from "#data"; +import type { Raw } from "#raw"; export interface Machine { trace(): AsyncIterable; @@ -29,17 +29,17 @@ export namespace Machine { get length(): Promise; /** read element at position from top of stack */ - peek(options: { depth: bigint; slice?: Slice }): Promise; + peek(options: { depth: bigint; slice?: Slice }): Promise; } export interface Bytes { get length(): Promise; - read(options: { slice: Slice }): Promise; + read(options: { slice: Slice }): Promise; } export interface Words { - read(options: { slot: Data; slice?: Slice }): Promise; + read(options: { slot: Raw; slice?: Slice }): Promise; } } } diff --git a/packages/common/src/raw.test.ts b/packages/common/src/raw.test.ts new file mode 100644 index 0000000000..702291e76e --- /dev/null +++ b/packages/common/src/raw.test.ts @@ -0,0 +1,99 @@ +import { expect, describe, it } from "vitest"; + +import { Raw } from "#raw"; + +const bytes = (...values: number[]) => new Uint8Array(values); + +describe("Raw", () => { + describe(".asUint()", () => { + it("correctly converts to integers (big endian)", () => { + expect(`${Raw.asUint(bytes(0x01, 0x00))}`).toBe("256"); + }); + + it("gives 0n for an empty Raw", () => { + expect(Raw.asUint(Raw.zero())).toBe(0n); + }); + }); + + describe(".fromUint()", () => { + it("correctly creates Raw values from bigints", () => { + expect(Raw.fromUint(0n)).toEqual(bytes()); + expect(Raw.fromUint(255n)).toEqual(bytes(0xff)); + expect(Raw.fromUint(256n)).toEqual(bytes(0x01, 0x00)); + expect(Raw.fromUint(1234567890n)).toEqual(bytes(0x49, 0x96, 0x02, 0xd2)); + }); + }); + + describe(".fromNumber()", () => { + it("correctly creates Raw values from numbers", () => { + expect(Raw.fromNumber(0)).toEqual(Raw.zero()); + expect(Raw.fromNumber(0)).toEqual(bytes()); + expect(Raw.fromNumber(255)).toEqual(bytes(0xff)); + expect(Raw.fromNumber(256)).toEqual(bytes(0x01, 0x00)); + }); + }); + + describe(".fromHex()", () => { + it("correctly creates Raw values from hex strings", () => { + expect(Raw.fromHex("0x00")).toEqual(bytes(0x00)); + expect(Raw.fromHex("0xff")).toEqual(bytes(0xff)); + expect(Raw.fromHex("0x0100")).toEqual(bytes(0x01, 0x00)); + expect(Raw.fromHex("0x499602d2")).toEqual(bytes(0x49, 0x96, 0x02, 0xd2)); + }); + + it("reads an odd digit count as one byte per pair", () => { + expect(Raw.fromHex("0x1")).toEqual(bytes(0x01)); + }); + + it("throws an error for invalid hex string format", () => { + expect(() => Raw.fromHex("ff")).toThrow( + 'Invalid hex string format. Expected "0x" prefix.', + ); + }); + }); + + describe(".toHex()", () => { + it("gives a 0x-prefixed hex string", () => { + expect(Raw.toHex(bytes(0x01, 0xab))).toBe("0x01ab"); + expect(Raw.toHex(Raw.zero())).toBe("0x"); + }); + }); + + describe(".concat()", () => { + it("joins the bytes in order", () => { + expect(Raw.concat(bytes(1), bytes(), bytes(2, 3))).toEqual( + bytes(1, 2, 3), + ); + }); + + it("gives an empty Raw with no operands", () => { + expect(Raw.concat()).toEqual(bytes()); + }); + }); + + describe(".resizeTo()", () => { + it("keeps the low-order bytes when shorter", () => { + expect(Raw.resizeTo(bytes(1, 2, 3), 2)).toEqual(bytes(2, 3)); + }); + + it("pads on the left when longer", () => { + expect(Raw.resizeTo(bytes(1), 3)).toEqual(bytes(0, 0, 1)); + }); + + it("returns the same object at equal length", () => { + const raw = bytes(1, 2); + expect(Raw.resizeTo(raw, raw.length)).toBe(raw); + }); + }); + + describe(".padUntilAtLeast()", () => { + it("pads on the left when shorter", () => { + expect(Raw.padUntilAtLeast(bytes(1), 3)).toEqual(bytes(0, 0, 1)); + }); + + it("returns the same object when long enough", () => { + const raw = bytes(1, 2); + expect(Raw.padUntilAtLeast(raw, 1)).toBe(raw); + }); + }); +}); diff --git a/packages/common/src/raw.ts b/packages/common/src/raw.ts new file mode 100644 index 0000000000..4e294ced52 --- /dev/null +++ b/packages/common/src/raw.ts @@ -0,0 +1,99 @@ +import { toHex as hexOf } from "ethereum-cryptography/utils"; + +/** + * A byte string, most significant byte first. + */ +export type Raw = Uint8Array; + +export namespace Raw { + export function zero(): Raw { + return new Uint8Array([]); + } + + export function fromUint(value: bigint): Raw { + if (value === 0n) { + return zero(); + } + + const byteCount = Math.ceil(Number(value.toString(2).length) / 8); + const bytes = new Uint8Array(byteCount); + for (let i = byteCount - 1; i >= 0; i--) { + bytes[i] = Number(value & 0xffn); + value >>= 8n; + } + return bytes; + } + + export function fromNumber(value: number): Raw { + const byteCount = Math.ceil(Math.log2(value + 1) / 8); + const bytes = new Uint8Array(byteCount); + for (let i = byteCount - 1; i >= 0; i--) { + bytes[i] = value & 0xff; + value >>= 8; + } + return bytes; + } + + export function fromHex(hex: string): Raw { + if (!hex.startsWith("0x")) { + throw new Error('Invalid hex string format. Expected "0x" prefix.'); + } + const bytes = new Uint8Array((hex.length - 2) / 2 + 0.5); + for (let i = 2; i < hex.length; i += 2) { + bytes[i / 2 - 1] = parseInt(hex.slice(i, i + 2), 16); + } + return bytes; + } + + export function asUint(raw: Raw): bigint { + const bits = 8n; + + let value = 0n; + for (const byte of raw.values()) { + const byteValue = BigInt(byte); + value = (value << bits) + byteValue; + } + return value; + } + + export function toHex(raw: Raw): string { + return `0x${hexOf(raw)}`; + } + + export function padUntilAtLeast(raw: Raw, length: number): Raw { + if (raw.length >= length) { + return raw; + } + + const padded = new Uint8Array(length); + padded.set(raw, length - raw.length); + return padded; + } + + export function resizeTo(raw: Raw, length: number): Raw { + if (raw.length === length) { + return raw; + } + + const resized = new Uint8Array(length); + + if (raw.length < length) { + resized.set(raw, length - raw.length); + } else { + resized.set(raw.slice(raw.length - length)); + } + + return resized; + } + + export function concat(...raws: Raw[]): Raw { + const length = raws.reduce((total, raw) => total + raw.length, 0); + const joined = new Uint8Array(length); + let offset = 0; + for (const raw of raws) { + joined.set(raw, offset); + offset += raw.length; + } + return joined; + } +} diff --git a/packages/common/tsconfig.build.json b/packages/common/tsconfig.build.json new file mode 100644 index 0000000000..523e0c76ed --- /dev/null +++ b/packages/common/tsconfig.build.json @@ -0,0 +1,6 @@ +{ + "extends": "./tsconfig.json", + "compilerOptions": { "declarationMap": false }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist", "**/*.test.ts"] +} diff --git a/packages/common/tsconfig.json b/packages/common/tsconfig.json new file mode 100644 index 0000000000..e70121057e --- /dev/null +++ b/packages/common/tsconfig.json @@ -0,0 +1,14 @@ +{ + "extends": "../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "./", + "outDir": "./dist/", + "baseUrl": "./", + "paths": { + "#raw": ["./src/raw"], + "#machine": ["./src/machine"], + "#keccak": ["./src/keccak"] + } + }, + "exclude": ["node_modules", "dist"] +} diff --git a/packages/common/tsconfig.typecheck.json b/packages/common/tsconfig.typecheck.json new file mode 100644 index 0000000000..42e0aadc57 --- /dev/null +++ b/packages/common/tsconfig.typecheck.json @@ -0,0 +1,9 @@ +{ + "extends": "./tsconfig.json", + "compilerOptions": { + "noEmit": true, + "composite": false, + "incremental": false, + "rootDir": "../.." + } +} diff --git a/packages/common/vitest.config.ts b/packages/common/vitest.config.ts new file mode 100644 index 0000000000..dd9e8a795d --- /dev/null +++ b/packages/common/vitest.config.ts @@ -0,0 +1,5 @@ +import { defineProject } from "vitest/config"; + +export default defineProject({ + test: {}, +}); diff --git a/packages/conformance/tsconfig.typecheck.json b/packages/conformance/tsconfig.typecheck.json index 3d9d538686..09ca2724ff 100644 --- a/packages/conformance/tsconfig.typecheck.json +++ b/packages/conformance/tsconfig.typecheck.json @@ -7,6 +7,7 @@ "rootDir": "../..", "paths": { "@ethdebug/bugc": ["../bugc/src/index.ts"], + "@ethdebug/common": ["../common/src/index.ts"], "@ethdebug/evm": ["../evm/src/index.ts"], "@ethdebug/format": ["../format/src/index.ts"], "@ethdebug/pointers": ["../pointers/src/index.ts"] diff --git a/packages/evm/CHANGELOG.md b/packages/evm/CHANGELOG.md index 9ed121056f..6ef6d9ffb3 100644 --- a/packages/evm/CHANGELOG.md +++ b/packages/evm/CHANGELOG.md @@ -41,6 +41,13 @@ specification itself are tracked in the root ### Changed +- **Breaking:** the `Machine` interfaces that `createMachine` and + `createMachineState` implement now come from `@ethdebug/common`, and + their reads give a `Raw` (a `Uint8Array`) from that package instead of + `Data` from `@ethdebug/pointers`. Use `Raw.asUint(value)` and + `Raw.toHex(value)` where you used `value.asUint()` and `value.toHex()`. +- The package no longer depends on `@ethdebug/pointers`. To evaluate + pointers against its machine state, install `@ethdebug/pointers` too. - **Breaking:** a `TraceStep` is the event only: `pc`, `opcode`, `op` (the opcode byte), `gasRemaining`, `gasCost`, `depth`, `address` and `codeAddress`. Its stack and memory moved to `Trace.stateAt` ([#375]). diff --git a/packages/evm/package.json b/packages/evm/package.json index a61434285b..a53f4ebdec 100644 --- a/packages/evm/package.json +++ b/packages/evm/package.json @@ -41,7 +41,7 @@ "test": "vitest run" }, "dependencies": { - "@ethdebug/pointers": "^0.1.0-preview.2", + "@ethdebug/common": "^0.1.0-preview.2", "@ethereumjs/common": "^10.0.0", "@ethereumjs/evm": "^10.0.0", "@ethereumjs/statemanager": "^10.0.0", diff --git a/packages/evm/src/executor.ts b/packages/evm/src/executor.ts index 03b74e51ae..5fe2ffc877 100644 --- a/packages/evm/src/executor.ts +++ b/packages/evm/src/executor.ts @@ -21,7 +21,7 @@ import { generateAddress2, bigIntToBytes, } from "@ethereumjs/util"; -import { keccak256 } from "ethereum-cryptography/keccak"; +import { keccak256 } from "@ethdebug/common"; import { hexToBytes, bytesToHex } from "ethereum-cryptography/utils"; import { recorder } from "#trace"; diff --git a/packages/evm/src/machine.test.ts b/packages/evm/src/machine.test.ts index 29fa04e9d0..880cd633c1 100644 --- a/packages/evm/src/machine.test.ts +++ b/packages/evm/src/machine.test.ts @@ -1,5 +1,5 @@ import { describe, it, expect } from "vitest"; -import { Data } from "@ethdebug/pointers"; +import { Raw } from "@ethdebug/common"; import { Executor } from "#executor"; import { createMachineState } from "#machine"; import type { StepState } from "#trace"; @@ -25,14 +25,14 @@ describe("createMachineState", () => { it("reads the stack, top first", async () => { const state = createMachineState(stepState); expect(await state.stack.length).toBe(3n); - expect((await state.stack.peek({ depth: 0n })).asUint()).toBe(0xdeadbeefn); - expect((await state.stack.peek({ depth: 2n })).asUint()).toBe(100n); - expect((await state.stack.peek({ depth: 5n })).asUint()).toBe(0n); + expect(Raw.asUint(await state.stack.peek({ depth: 0n }))).toBe(0xdeadbeefn); + expect(Raw.asUint(await state.stack.peek({ depth: 2n }))).toBe(100n); + expect(Raw.asUint(await state.stack.peek({ depth: 5n }))).toBe(0n); const sliced = await state.stack.peek({ depth: 0n, slice: { offset: 28n, length: 4n }, }); - expect(sliced.asUint()).toBe(0xdeadbeefn); + expect(Raw.asUint(sliced)).toBe(0xdeadbeefn); }); it("reads memory, zero past its end", async () => { @@ -40,21 +40,21 @@ describe("createMachineState", () => { expect(await state.memory.length).toBe(64n); const read = (offset: bigint) => state.memory.read({ slice: { offset, length: 32n } }); - expect((await read(0n)).asUint()).toBe(0xffn); - expect((await read(32n)).asUint()).toBe(0xabn); - expect((await read(64n)).asUint()).toBe(0n); + expect(Raw.asUint(await read(0n))).toBe(0xffn); + expect(Raw.asUint(await read(32n))).toBe(0xabn); + expect(Raw.asUint(await read(64n))).toBe(0n); }); it("reads storage and transient storage, with slices", async () => { const state = createMachineState(stepState); - const slot = (n: bigint) => Data.fromUint(n); - expect((await state.storage.read({ slot: slot(1n) })).asUint()).toBe(7n); + const slot = (n: bigint) => Raw.fromUint(n); + expect(Raw.asUint(await state.storage.read({ slot: slot(1n) }))).toBe(7n); const byte = await state.storage.read({ slot: slot(1n), slice: { offset: 31n, length: 1n }, }); - expect(byte.asUint()).toBe(7n); - expect((await state.transient.read({ slot: slot(2n) })).asUint()).toBe(9n); + expect(Raw.asUint(byte)).toBe(7n); + expect(Raw.asUint(await state.transient.read({ slot: slot(2n) }))).toBe(9n); }); it("reads calldata, returndata and code", async () => { @@ -63,10 +63,10 @@ describe("createMachineState", () => { const calldata = await state.calldata.read({ slice: { offset: 2n, length: 2n }, }); - expect(calldata.asUint()).toBe(0x0304n); + expect(Raw.asUint(calldata)).toBe(0x0304n); expect(await state.returndata.length).toBe(2n); const code = await state.code.read({ slice: { offset: 0n, length: 1n } }); - expect(code.asUint()).toBe(0x60n); + expect(Raw.asUint(code)).toBe(0x60n); }); it("takes the pc, opcode and trace index", async () => { @@ -101,8 +101,8 @@ describe("Executor.currentState", () => { await executor.execute(); const state = createMachineState(await executor.currentState()); - const value = await state.storage.read({ slot: Data.fromUint(0n) }); - expect(value.asUint()).toBe(42n); + const value = await state.storage.read({ slot: Raw.fromUint(0n) }); + expect(Raw.asUint(value)).toBe(42n); expect(await state.code.length).toBe(6n); expect(await state.stack.length).toBe(0n); expect(await state.memory.length).toBe(0n); @@ -110,7 +110,7 @@ describe("Executor.currentState", () => { // it reads live: a later change shows await executor.setStorage(0n, 43n); - const later = await state.storage.read({ slot: Data.fromUint(0n) }); - expect(later.asUint()).toBe(43n); + const later = await state.storage.read({ slot: Raw.fromUint(0n) }); + expect(Raw.asUint(later)).toBe(43n); }); }); diff --git a/packages/evm/src/machine.ts b/packages/evm/src/machine.ts index 3348550deb..3bd5348a76 100644 --- a/packages/evm/src/machine.ts +++ b/packages/evm/src/machine.ts @@ -1,12 +1,11 @@ /** * Machine.State Adapter * - * Implements the @ethdebug/pointers Machine.State interface over a + * Implements the @ethdebug/common Machine.State interface over a * complete step state, to enable pointer evaluation at a trace step. */ -import type { Machine } from "@ethdebug/pointers"; -import { Data } from "@ethdebug/pointers"; +import { type Machine, Raw } from "@ethdebug/common"; import type { StepState } from "#trace"; /** @@ -47,10 +46,10 @@ export function createMachineState( stack: { length: Promise.resolve(BigInt(stack.length)), - async peek({ depth, slice }): Promise { + async peek({ depth, slice }): Promise { const index = stack.length - 1 - Number(depth); if (index < 0 || index >= stack.length) { - return Data.zero(); + return Raw.zero(); } return sliceWord(stack[index], slice); }, @@ -59,8 +58,8 @@ export function createMachineState( memory: bytesRegion(state.memory), storage: { - async read({ slot, slice }): Promise { - return sliceWord(await state.storage(slot.asUint()), slice); + async read({ slot, slice }): Promise { + return sliceWord(await state.storage(Raw.asUint(slot)), slice); }, }, @@ -71,8 +70,8 @@ export function createMachineState( code: bytesRegion(state.code), transient: { - async read({ slot, slice }): Promise { - return sliceWord(await state.transient(slot.asUint()), slice); + async read({ slot, slice }): Promise { + return sliceWord(await state.transient(Raw.asUint(slot)), slice); }, }, }; @@ -83,16 +82,14 @@ interface Slice { length: bigint; } -function sliceWord(value: bigint, slice?: Slice): Data { - const padded = Data.fromUint(value).padUntilAtLeast(32); +function sliceWord(value: bigint, slice?: Slice): Raw { + const padded = Raw.padUntilAtLeast(Raw.fromUint(value), 32); if (!slice) { return padded; } - return Data.fromBytes( - new Uint8Array(padded).slice( - Number(slice.offset), - Number(slice.offset + slice.length), - ), + return new Uint8Array(padded).slice( + Number(slice.offset), + Number(slice.offset + slice.length), ); } @@ -102,16 +99,16 @@ function sliceWord(value: bigint, slice?: Slice): Data { */ function bytesRegion(bytes: Uint8Array): { length: Promise; - read(options: { slice: Slice }): Promise; + read(options: { slice: Slice }): Promise; } { return { length: Promise.resolve(BigInt(bytes.length)), - async read({ slice }): Promise { + async read({ slice }): Promise { const offset = Number(slice.offset); const length = Number(slice.length); const out = new Uint8Array(length); out.set(bytes.subarray(offset, offset + length)); - return Data.fromBytes(out); + return out; }, }; } diff --git a/packages/evm/src/trace.test.ts b/packages/evm/src/trace.test.ts index 5f69afd06b..aac948afb8 100644 --- a/packages/evm/src/trace.test.ts +++ b/packages/evm/src/trace.test.ts @@ -100,14 +100,14 @@ describe("createTrace", () => { traceIndex: sstore, }); expect(await state.opcode).toBe("SSTORE"); - const { Data } = await import("@ethdebug/pointers"); - const slot0 = await state.storage.read({ slot: Data.fromUint(0n) }); - expect(slot0.asUint()).toBe(0n); + const { Raw } = await import("@ethdebug/common"); + const slot0 = await state.storage.read({ slot: Raw.fromUint(0n) }); + expect(Raw.asUint(slot0)).toBe(0n); const calldata = await state.calldata.read({ slice: { offset: 0n, length: 32n }, }); - expect(calldata.asUint()).toBe(7n); - expect((await state.stack.peek({ depth: 1n })).asUint()).toBe(7n); + expect(Raw.asUint(calldata)).toBe(7n); + expect(Raw.asUint(await state.stack.peek({ depth: 1n }))).toBe(7n); // a trace's state knows its step const own = createMachineState(trace.stateAt(sstore)); @@ -474,14 +474,14 @@ describe("createMachine", () => { await executor.execute(); const machine = createMachine(executor); - const { Data } = await import("@ethdebug/pointers"); + const { Raw } = await import("@ethdebug/common"); for await (const state of machine.trace()) { const val = await state.storage.read({ - slot: Data.fromUint(0n), + slot: Raw.fromUint(0n), }); // After the first execute, slot 0 = 42 - expect(val.asUint()).toBe(42n); + expect(Raw.asUint(val)).toBe(42n); break; // just check first state } }); diff --git a/packages/evm/src/trace.ts b/packages/evm/src/trace.ts index 61da6e9ab2..13132f8c9d 100644 --- a/packages/evm/src/trace.ts +++ b/packages/evm/src/trace.ts @@ -6,7 +6,7 @@ * `StepState` at any of its steps. */ -import type { Machine } from "@ethdebug/pointers"; +import type { Machine } from "@ethdebug/common"; import type { Executor, ExecutionOptions } from "#executor"; import { createMachineState } from "#machine"; diff --git a/packages/evm/tsconfig.build.json b/packages/evm/tsconfig.build.json index 171e4e488a..1e82d8e403 100644 --- a/packages/evm/tsconfig.build.json +++ b/packages/evm/tsconfig.build.json @@ -9,5 +9,5 @@ "**/*.test.tsx", "test/**" ], - "references": [{ "path": "../pointers/tsconfig.build.json" }] + "references": [{ "path": "../common/tsconfig.build.json" }] } diff --git a/packages/evm/tsconfig.json b/packages/evm/tsconfig.json index 18545ef8cc..1283d1abbc 100644 --- a/packages/evm/tsconfig.json +++ b/packages/evm/tsconfig.json @@ -12,5 +12,5 @@ }, "include": ["src/**/*"], "exclude": ["node_modules", "dist"], - "references": [{ "path": "../pointers" }] + "references": [{ "path": "../common" }] } diff --git a/packages/evm/tsconfig.typecheck.json b/packages/evm/tsconfig.typecheck.json index 6e118cf769..74fd726ef9 100644 --- a/packages/evm/tsconfig.typecheck.json +++ b/packages/evm/tsconfig.typecheck.json @@ -6,8 +6,7 @@ "incremental": false, "rootDir": "../..", "paths": { - "@ethdebug/format": ["../format/src/index.ts"], - "@ethdebug/pointers": ["../pointers/src/index.ts"] + "@ethdebug/common": ["../common/src/index.ts"] } } } diff --git a/packages/pointers-react/CHANGELOG.md b/packages/pointers-react/CHANGELOG.md index 7b93f1e535..a211a60801 100644 --- a/packages/pointers-react/CHANGELOG.md +++ b/packages/pointers-react/CHANGELOG.md @@ -16,6 +16,13 @@ root [`CHANGELOG.md`](../../CHANGELOG.md). ### Changed +- **Breaking:** the package no longer re-exports `Data` and `Machine` + from `@ethdebug/pointers`. Import `Raw` and `Machine` from + `@ethdebug/common`. `createMockState`, `formatData` and + `formatDataShort` take and give `Raw` values. +- **Breaking:** the package no longer re-exports the `Pointer` type from + `@ethdebug/format` or the `Cursor` type from `@ethdebug/pointers`. + Import them from those packages. - The `react` and `react-dom` peer ranges now include React 19 (`^18.0.0 || ^19.0.0`) ([#374]). The components' return types now read `React.JSX.Element`, which both React 18 and 19 types define; diff --git a/packages/pointers-react/package.json b/packages/pointers-react/package.json index e971d13787..4d562f8318 100644 --- a/packages/pointers-react/package.json +++ b/packages/pointers-react/package.json @@ -41,6 +41,7 @@ "test": "vitest run" }, "dependencies": { + "@ethdebug/common": "^0.1.0-preview.2", "@ethdebug/format": "^0.1.0-draft.2", "@ethdebug/pointers": "^0.1.0-preview.2" }, diff --git a/packages/pointers-react/src/components/RegionOutput.tsx b/packages/pointers-react/src/components/RegionOutput.tsx index 199c94d43b..c100bcc340 100644 --- a/packages/pointers-react/src/components/RegionOutput.tsx +++ b/packages/pointers-react/src/components/RegionOutput.tsx @@ -3,14 +3,15 @@ */ import React from "react"; -import type { Cursor, Data } from "@ethdebug/pointers"; +import { Raw } from "@ethdebug/common"; +import type { Cursor } from "@ethdebug/pointers"; import { formatData, formatDataShort } from "#utils/mockState"; export interface RegionOutputProps { /** Resolved regions to display */ regions: Cursor.Region[]; /** Values read from each region */ - values: Map; + values: Map; /** Whether to show full hex values or shortened */ showFullValues?: boolean; } @@ -52,7 +53,7 @@ function RegionItem({ index, }: { region: Cursor.Region; - value: Data | undefined; + value: Raw | undefined; showFullValues: boolean; index: number; }): React.JSX.Element { diff --git a/packages/pointers-react/src/hooks/usePointerResolution.ts b/packages/pointers-react/src/hooks/usePointerResolution.ts index 58a47b405f..ffec5bdf59 100644 --- a/packages/pointers-react/src/hooks/usePointerResolution.ts +++ b/packages/pointers-react/src/hooks/usePointerResolution.ts @@ -4,7 +4,8 @@ import { useState, useCallback, useEffect } from "react"; import type { Pointer } from "@ethdebug/format"; -import { dereference, type Cursor, Data } from "@ethdebug/pointers"; +import { Raw } from "@ethdebug/common"; +import { dereference, type Cursor } from "@ethdebug/pointers"; import { createMockState, type MockStateSpec } from "#utils/mockState"; /** @@ -14,7 +15,7 @@ export interface ResolutionResult { /** The resolved regions */ regions: Cursor.Region[]; /** Values read from each region */ - values: Map; + values: Map; /** Named region lookup */ namedRegions: Record; /** Most recent region for each name */ @@ -107,7 +108,7 @@ export function usePointerResolution( const view = await cursor.view(state); // Read values for each region - const values = new Map(); + const values = new Map(); for (const region of view.regions) { try { const data = await view.read(region); diff --git a/packages/pointers-react/src/index.ts b/packages/pointers-react/src/index.ts index 85112741d2..dd2123bcc1 100644 --- a/packages/pointers-react/src/index.ts +++ b/packages/pointers-react/src/index.ts @@ -38,10 +38,6 @@ export { type MockStateSpec, } from "#utils/mockState"; -// Re-export types from dependencies for convenience -export type { Pointer } from "@ethdebug/format"; -export type { Cursor, Machine, Data } from "@ethdebug/pointers"; - // CSS - the package ships stylesheets under dist/src/components/. // Import variables.css first (the component stylesheets use its // --pointers-* custom properties without fallbacks), then whichever diff --git a/packages/pointers-react/src/utils/mockState.ts b/packages/pointers-react/src/utils/mockState.ts index 4abdd85aab..c9412f6cec 100644 --- a/packages/pointers-react/src/utils/mockState.ts +++ b/packages/pointers-react/src/utils/mockState.ts @@ -2,7 +2,7 @@ * Utilities for creating mock Machine.State objects for visualization. */ -import { type Machine, Data } from "@ethdebug/pointers"; +import { type Machine, Raw } from "@ethdebug/common"; /** * Specification for creating a mock Machine.State. @@ -39,30 +39,35 @@ export interface MockStateSpec { export function createMockState(spec: MockStateSpec): Machine.State { const stackEntries = (spec.stack || []).map((entry) => typeof entry === "string" - ? Data.fromHex(entry).padUntilAtLeast(32) - : Data.fromUint(entry).padUntilAtLeast(32), + ? Raw.padUntilAtLeast(Raw.fromHex(entry), 32) + : Raw.padUntilAtLeast(Raw.fromUint(entry), 32), ); - const memoryData = spec.memory ? Data.fromHex(spec.memory) : Data.zero(); + const memoryData = spec.memory ? Raw.fromHex(spec.memory) : Raw.zero(); - const storageMap = new Map(); + const storageMap = new Map(); for (const [slot, value] of Object.entries(spec.storage || {})) { - const normalizedSlot = Data.fromHex(slot).padUntilAtLeast(32).toHex(); - storageMap.set(normalizedSlot, Data.fromHex(value).padUntilAtLeast(32)); + const normalizedSlot = Raw.toHex( + Raw.padUntilAtLeast(Raw.fromHex(slot), 32), + ); + storageMap.set(normalizedSlot, Raw.padUntilAtLeast(Raw.fromHex(value), 32)); } - const calldataData = spec.calldata - ? Data.fromHex(spec.calldata) - : Data.zero(); + const calldataData = spec.calldata ? Raw.fromHex(spec.calldata) : Raw.zero(); const returndataData = spec.returndata - ? Data.fromHex(spec.returndata) - : Data.zero(); - const codeData = spec.code ? Data.fromHex(spec.code) : Data.zero(); + ? Raw.fromHex(spec.returndata) + : Raw.zero(); + const codeData = spec.code ? Raw.fromHex(spec.code) : Raw.zero(); - const transientMap = new Map(); + const transientMap = new Map(); for (const [slot, value] of Object.entries(spec.transient || {})) { - const normalizedSlot = Data.fromHex(slot).padUntilAtLeast(32).toHex(); - transientMap.set(normalizedSlot, Data.fromHex(value).padUntilAtLeast(32)); + const normalizedSlot = Raw.toHex( + Raw.padUntilAtLeast(Raw.fromHex(slot), 32), + ); + transientMap.set( + normalizedSlot, + Raw.padUntilAtLeast(Raw.fromHex(value), 32), + ); } const stack: Machine.State.Stack = { @@ -79,9 +84,7 @@ export function createMockState(spec: MockStateSpec): Machine.State { return entry; } const { offset, length } = slice; - return Data.fromBytes( - entry.slice(Number(offset), Number(offset + length)), - ); + return entry.slice(Number(offset), Number(offset + length)); }, }; @@ -100,24 +103,22 @@ export function createMockState(spec: MockStateSpec): Machine.State { if (available > 0 && start < memoryData.length) { result.set(memoryData.slice(start, start + available), 0); } - return Data.fromBytes(result); + return result; } - return Data.fromBytes(memoryData.slice(start, end)); + return memoryData.slice(start, end); }, }; const storage: Machine.State.Words = { async read({ slot, slice }) { - const normalizedSlot = slot.padUntilAtLeast(32).toHex(); + const normalizedSlot = Raw.toHex(Raw.padUntilAtLeast(slot, 32)); const value = - storageMap.get(normalizedSlot) || Data.zero().padUntilAtLeast(32); + storageMap.get(normalizedSlot) || Raw.padUntilAtLeast(Raw.zero(), 32); if (!slice) { return value; } const { offset, length } = slice; - return Data.fromBytes( - value.slice(Number(offset), Number(offset + length)), - ); + return value.slice(Number(offset), Number(offset + length)); }, }; @@ -135,9 +136,9 @@ export function createMockState(spec: MockStateSpec): Machine.State { if (available > 0 && start < calldataData.length) { result.set(calldataData.slice(start, start + available), 0); } - return Data.fromBytes(result); + return result; } - return Data.fromBytes(calldataData.slice(start, end)); + return calldataData.slice(start, end); }, }; @@ -155,9 +156,9 @@ export function createMockState(spec: MockStateSpec): Machine.State { if (available > 0 && start < returndataData.length) { result.set(returndataData.slice(start, start + available), 0); } - return Data.fromBytes(result); + return result; } - return Data.fromBytes(returndataData.slice(start, end)); + return returndataData.slice(start, end); }, }; @@ -175,24 +176,22 @@ export function createMockState(spec: MockStateSpec): Machine.State { if (available > 0 && start < codeData.length) { result.set(codeData.slice(start, start + available), 0); } - return Data.fromBytes(result); + return result; } - return Data.fromBytes(codeData.slice(start, end)); + return codeData.slice(start, end); }, }; const transient: Machine.State.Words = { async read({ slot, slice }) { - const normalizedSlot = slot.padUntilAtLeast(32).toHex(); + const normalizedSlot = Raw.toHex(Raw.padUntilAtLeast(slot, 32)); const value = - transientMap.get(normalizedSlot) || Data.zero().padUntilAtLeast(32); + transientMap.get(normalizedSlot) || Raw.padUntilAtLeast(Raw.zero(), 32); if (!slice) { return value; } const { offset, length } = slice; - return Data.fromBytes( - value.slice(Number(offset), Number(offset + length)), - ); + return value.slice(Number(offset), Number(offset + length)); }, }; @@ -217,10 +216,10 @@ export function createMockState(spec: MockStateSpec): Machine.State { } /** - * Format a Data value as a shortened hex string for display. + * Format a Raw value as a shortened hex string for display. */ -export function formatDataShort(data: Data, maxLength = 10): string { - const hex = data.toHex(); +export function formatDataShort(data: Raw, maxLength = 10): string { + const hex = Raw.toHex(data); if (hex.length <= maxLength + 2) { return hex; } @@ -230,8 +229,8 @@ export function formatDataShort(data: Data, maxLength = 10): string { } /** - * Format a Data value as a full hex string. + * Format a Raw value as a full hex string. */ -export function formatData(data: Data): string { - return data.toHex(); +export function formatData(data: Raw): string { + return Raw.toHex(data); } diff --git a/packages/pointers-react/tsconfig.build.json b/packages/pointers-react/tsconfig.build.json index 1ee184372e..6deb77389a 100644 --- a/packages/pointers-react/tsconfig.build.json +++ b/packages/pointers-react/tsconfig.build.json @@ -11,6 +11,7 @@ ], "references": [ { "path": "../format/tsconfig.build.json" }, + { "path": "../common/tsconfig.build.json" }, { "path": "../pointers/tsconfig.build.json" } ] } diff --git a/packages/pointers-react/tsconfig.json b/packages/pointers-react/tsconfig.json index 80d8f4b3d2..1cc0a4aa76 100644 --- a/packages/pointers-react/tsconfig.json +++ b/packages/pointers-react/tsconfig.json @@ -14,5 +14,9 @@ }, "include": ["src/**/*"], "exclude": ["node_modules", "dist"], - "references": [{ "path": "../format" }, { "path": "../pointers" }] + "references": [ + { "path": "../format" }, + { "path": "../common" }, + { "path": "../pointers" } + ] } diff --git a/packages/pointers-react/tsconfig.typecheck.json b/packages/pointers-react/tsconfig.typecheck.json index 6e118cf769..36bfa2a097 100644 --- a/packages/pointers-react/tsconfig.typecheck.json +++ b/packages/pointers-react/tsconfig.typecheck.json @@ -6,6 +6,7 @@ "incremental": false, "rootDir": "../..", "paths": { + "@ethdebug/common": ["../common/src/index.ts"], "@ethdebug/format": ["../format/src/index.ts"], "@ethdebug/pointers": ["../pointers/src/index.ts"] } diff --git a/packages/pointers/CHANGELOG.md b/packages/pointers/CHANGELOG.md index eb0ed3a3ac..37ff13c53d 100644 --- a/packages/pointers/CHANGELOG.md +++ b/packages/pointers/CHANGELOG.md @@ -6,6 +6,15 @@ itself are tracked in the root [`CHANGELOG.md`](../../CHANGELOG.md). ## Unreleased +### Breaking + +- `Data` and `Machine` moved to the new `@ethdebug/common` package, and this + package no longer exports them. `Data` is now `Raw`: a plain `Uint8Array` + type with functions in place of methods, so `data.toHex()` becomes + `Raw.toHex(data)` and `Data.fromBytes(bytes)` becomes `bytes`. + `Cursor.View.read` gives a `Raw`, and the `Machine` interfaces read and give + `Raw` values. + ### Added - `dereference` and `read` support virtual regions. A concrete virtual @@ -15,6 +24,8 @@ itself are tracked in the root [`CHANGELOG.md`](../../CHANGELOG.md). ### Changed +- `ethereum-cryptography` is now a development dependency only. The + package no longer uses it at run time. - `dereference` evaluates the members of a scope's `define` in dependency order, not member order. A member sees the other members by name, and its own name means the variable of the enclosing scope. A cycle of members throws @@ -27,11 +38,6 @@ itself are tracked in the root [`CHANGELOG.md`](../../CHANGELOG.md). which the region begins). It threw "does not have ... needed by lookup" before. A concrete region of these locations now always has `offset` and `length` ([#411]). -- The published type declarations no longer reference Node's `util` types. - `Data.inspect` and its `util.inspect.custom` hook used - `util.InspectOptionsStylized`, which newer `@types/node` versions no longer - export, so consumers that type-checked with `skipLibCheck: false` got errors. - The options parameter is now a small local interface. ## 0.1.0-preview.2 — 2026-10-07 diff --git a/packages/pointers/package.json b/packages/pointers/package.json index 6bf85c8358..17bfb8dbdb 100644 --- a/packages/pointers/package.json +++ b/packages/pointers/package.json @@ -23,18 +23,10 @@ "types": "./src/cursor.ts", "default": "./dist/src/cursor.js" }, - "#data": { - "types": "./src/data.ts", - "default": "./dist/src/data.js" - }, "#evaluate": { "types": "./src/evaluate.ts", "default": "./dist/src/evaluate.js" }, - "#machine": { - "types": "./src/machine.ts", - "default": "./dist/src/machine.js" - }, "#read": { "types": "./src/read.ts", "default": "./dist/src/read.js" @@ -60,6 +52,7 @@ "devDependencies": { "chalk": "^5.6.2", "cli-highlight": "^2.1.11", + "ethereum-cryptography": "^2.2.1", "ganache": "7.9.x", "solc": "^0.8.33", "ts-node": "^10.9.2", @@ -67,8 +60,8 @@ "vitest": "^3.2.4" }, "dependencies": { - "@ethdebug/format": "^0.1.0-draft.2", - "ethereum-cryptography": "^2.2.1" + "@ethdebug/common": "^0.1.0-preview.2", + "@ethdebug/format": "^0.1.0-draft.2" }, "publishConfig": { "access": "public" diff --git a/packages/pointers/src/cursor.ts b/packages/pointers/src/cursor.ts index 53b6e925be..ffa5ae4805 100644 --- a/packages/pointers/src/cursor.ts +++ b/packages/pointers/src/cursor.ts @@ -1,6 +1,5 @@ import type { Pointer } from "@ethdebug/format"; -import type { Machine } from "#machine"; -import type { Data } from "#data"; +import type { Machine, Raw } from "@ethdebug/common"; /** * The result of dereferencing a pointer @@ -25,7 +24,7 @@ export namespace Cursor { * Read bytes from the machine state corresponding to the bytes range * for a particular concrete Cursor.Region */ - read(region: Cursor.Region): Promise; + read(region: Cursor.Region): Promise; } /** @@ -36,9 +35,9 @@ export namespace Cursor { export type Region = { [K in keyof R]: K extends "slot" | "offset" | "length" | "expression" ? R[K] extends Pointer.Expression - ? Data + ? Raw : R[K] extends Pointer.Expression | undefined - ? Data | undefined + ? Raw | undefined : R[K] : R[K]; }; diff --git a/packages/pointers/src/data.test.ts b/packages/pointers/src/data.test.ts deleted file mode 100644 index b8c32362bb..0000000000 --- a/packages/pointers/src/data.test.ts +++ /dev/null @@ -1,64 +0,0 @@ -import { expect, describe, it } from "vitest"; - -import { Data } from "./data.js"; - -describe("Data", () => { - describe(".prototype.asUint()", () => { - it("correctly converts to integers (big endian)", () => { - const data = new Data([0x01, 0x00]); - - expect(`${data.asUint()}`).toBe("256"); - }); - }); - - describe(".fromUint()", () => { - it("correctly creates Data instances from bigints", () => { - const data1 = Data.fromUint(0n); - expect(data1).toEqual(new Data([])); - - const data2 = Data.fromUint(255n); - expect(data2).toEqual(new Data([0xff])); - - const data3 = Data.fromUint(256n); - expect(data3).toEqual(new Data([0x01, 0x00])); - - const data4 = Data.fromUint(1234567890n); - expect(data4).toEqual(new Data([0x49, 0x96, 0x02, 0xd2])); - }); - }); - - describe(".fromNumber()", () => { - it("correctly creates Data instances from numbers", () => { - const data1 = Data.fromNumber(0); - expect(data1).toEqual(Data.zero()); - - const data2 = Data.fromNumber(255); - expect(data2).toEqual(new Data([0xff])); - - const data3 = Data.fromNumber(256); - expect(data3).toEqual(new Data([0x01, 0x00])); - }); - }); - - describe(".fromHex()", () => { - it("correctly creates Data instances from hex strings", () => { - const data1 = Data.fromHex("0x00"); - expect(data1).toEqual(new Data([0x00])); - - const data2 = Data.fromHex("0xff"); - expect(data2).toEqual(new Data([0xff])); - - const data3 = Data.fromHex("0x0100"); - expect(data3).toEqual(new Data([0x01, 0x00])); - - const data4 = Data.fromHex("0x499602d2"); - expect(data4).toEqual(new Data([0x49, 0x96, 0x02, 0xd2])); - }); - - it("throws an error for invalid hex string format", () => { - expect(() => Data.fromHex("ff")).toThrow( - 'Invalid hex string format. Expected "0x" prefix.', - ); - }); - }); -}); diff --git a/packages/pointers/src/data.ts b/packages/pointers/src/data.ts deleted file mode 100644 index 196054a181..0000000000 --- a/packages/pointers/src/data.ts +++ /dev/null @@ -1,126 +0,0 @@ -import { toHex } from "ethereum-cryptography/utils"; - -/** - * The part of Node's `util.inspect` options that `Data` uses. Declared here so - * the published types do not depend on `@types/node`. - */ -export interface InspectOptions { - stylize(text: string, styleType: string): string; - depth?: number | null; -} - -/** - * Structural stand-in for Node's `util.inspect` function. - */ -export type Inspect = (value: unknown, ...rest: unknown[]) => string; - -// Symbol for custom inspect (Node.js util.inspect.custom) -// We use a well-known symbol value to avoid top-level await issues -const customInspectSymbol = Symbol.for("nodejs.util.inspect.custom"); - -export class Data extends Uint8Array { - static zero(): Data { - return new Data([]); - } - - static fromUint(value: bigint): Data { - if (value === 0n) { - return this.zero(); - } - - const byteCount = Math.ceil(Number(value.toString(2).length) / 8); - const bytes = new Uint8Array(byteCount); - for (let i = byteCount - 1; i >= 0; i--) { - bytes[i] = Number(value & 0xffn); - value >>= 8n; - } - return new Data(bytes); - } - - static fromNumber(value: number): Data { - const byteCount = Math.ceil(Math.log2(value + 1) / 8); - const bytes = new Uint8Array(byteCount); - for (let i = byteCount - 1; i >= 0; i--) { - bytes[i] = value & 0xff; - value >>= 8; - } - return new Data(bytes); - } - - static fromHex(hex: string): Data { - if (!hex.startsWith("0x")) { - throw new Error('Invalid hex string format. Expected "0x" prefix.'); - } - const bytes = new Uint8Array((hex.length - 2) / 2 + 0.5); - for (let i = 2; i < hex.length; i += 2) { - bytes[i / 2 - 1] = parseInt(hex.slice(i, i + 2), 16); - } - return new Data(bytes); - } - - static fromBytes(bytes: Uint8Array): Data { - return new Data(bytes); - } - - asUint(): bigint { - const bits = 8n; - - let value = 0n; - for (const byte of this.values()) { - const byteValue = BigInt(byte); - value = (value << bits) + byteValue; - } - return value; - } - - toHex(): string { - return `0x${toHex(this)}`; - } - - padUntilAtLeast(length: number): Data { - if (this.length >= length) { - return this; - } - - const padded = new Uint8Array(length); - padded.set(this, length - this.length); - return Data.fromBytes(padded); - } - - resizeTo(length: number): Data { - if (this.length === length) { - return this; - } - - const resized = new Uint8Array(length); - - if (this.length < length) { - resized.set(this, length - this.length); - } else { - resized.set(this.slice(this.length - length)); - } - - return Data.fromBytes(resized); - } - - concat(...others: Data[]): Data { - // HACK concatenate via string representation - const concatenatedHex = [this, ...others] - .map((data) => data.toHex().slice(2)) - .reduce((accumulator, hex) => `${accumulator}${hex}`, "0x"); - - return Data.fromHex(concatenatedHex); - } - - inspect(_depth: number, options: InspectOptions, _inspect: Inspect): string { - return `Data[${options.stylize(this.toHex(), "number")}]`; - } - - [customInspectSymbol]( - depth: number, - options: InspectOptions, - inspect: Inspect, - ): string { - return this.inspect(depth, options, inspect); - } -} diff --git a/packages/pointers/src/dereference/cursor.ts b/packages/pointers/src/dereference/cursor.ts index 3236efea8c..9daf5cb9e5 100644 --- a/packages/pointers/src/dereference/cursor.ts +++ b/packages/pointers/src/dereference/cursor.ts @@ -1,4 +1,4 @@ -import type { Machine } from "#machine"; +import type { Machine } from "@ethdebug/common"; import type { Cursor } from "#cursor"; import { read } from "#read"; diff --git a/packages/pointers/src/dereference/generate.ts b/packages/pointers/src/dereference/generate.ts index 80fea15093..49184a2a78 100644 --- a/packages/pointers/src/dereference/generate.ts +++ b/packages/pointers/src/dereference/generate.ts @@ -1,5 +1,5 @@ import type { Pointer } from "@ethdebug/format"; -import type { Machine } from "#machine"; +import type { Machine } from "@ethdebug/common"; import type { Cursor } from "#cursor"; import type { Value } from "#evaluate"; diff --git a/packages/pointers/src/dereference/index.test.ts b/packages/pointers/src/dereference/index.test.ts index f7905936dc..9c1f1b0008 100644 --- a/packages/pointers/src/dereference/index.test.ts +++ b/packages/pointers/src/dereference/index.test.ts @@ -1,7 +1,6 @@ import { vitest, expect, describe, it, beforeEach } from "vitest"; import { Pointer, schemas } from "@ethdebug/format"; -import { Machine } from "#machine"; -import { Data } from "#data"; +import { type Machine, Raw } from "@ethdebug/common"; import { dereference } from "./index.js"; describe("dereference", () => { @@ -11,39 +10,25 @@ describe("dereference", () => { state = { stack: { length: Promise.resolve(10n), - peek: vitest.fn(async () => - Data.fromBytes(new Uint8Array([0x11, 0x22, 0x33, 0x44])), - ), + peek: vitest.fn(async () => new Uint8Array([0x11, 0x22, 0x33, 0x44])), }, memory: { - read: vitest.fn(async () => - Data.fromBytes(new Uint8Array([0x55, 0x66, 0x77, 0x88])), - ), + read: vitest.fn(async () => new Uint8Array([0x55, 0x66, 0x77, 0x88])), }, storage: { - read: vitest.fn(async () => - Data.fromBytes(new Uint8Array([0xaa, 0xbb, 0xcc, 0xdd])), - ), + read: vitest.fn(async () => new Uint8Array([0xaa, 0xbb, 0xcc, 0xdd])), }, calldata: { - read: vitest.fn(async () => - Data.fromBytes(new Uint8Array([0x11, 0x22, 0x33, 0x44])), - ), + read: vitest.fn(async () => new Uint8Array([0x11, 0x22, 0x33, 0x44])), }, returndata: { - read: vitest.fn(async () => - Data.fromBytes(new Uint8Array([0x55, 0x66, 0x77, 0x88])), - ), + read: vitest.fn(async () => new Uint8Array([0x55, 0x66, 0x77, 0x88])), }, transient: { - read: vitest.fn(async () => - Data.fromBytes(new Uint8Array([0xaa, 0xbb, 0xcc, 0xdd])), - ), + read: vitest.fn(async () => new Uint8Array([0xaa, 0xbb, 0xcc, 0xdd])), }, code: { - read: vitest.fn(async () => - Data.fromBytes(new Uint8Array([0x11, 0x22, 0x33, 0x44])), - ), + read: vitest.fn(async () => new Uint8Array([0x11, 0x22, 0x33, 0x44])), }, } as unknown as Machine.State; }); @@ -64,8 +49,8 @@ describe("dereference", () => { expect(regions).toHaveLength(1); expect(regions[0]).toEqual({ location: "memory", - offset: Data.fromNumber(0x60), - length: Data.fromNumber(0x20), + offset: Raw.fromNumber(0x60), + length: Raw.fromNumber(0x20), }); }); @@ -98,13 +83,13 @@ describe("dereference", () => { expect(regions.lookup["a"]).toEqual({ name: "a", location: "memory", - offset: Data.fromNumber(0x60), - length: Data.fromNumber(0x20), + offset: Raw.fromNumber(0x60), + length: Raw.fromNumber(0x20), }); expect(regions[1]).toEqual({ location: "memory", - offset: Data.fromNumber(0x80), - length: Data.fromNumber(0x20), + offset: Raw.fromNumber(0x80), + length: Raw.fromNumber(0x20), }); }); @@ -126,17 +111,17 @@ describe("dereference", () => { const { regions } = await cursor.view(state); expect(regions.lookup["a"]).toMatchObject({ - offset: Data.fromNumber(0), - length: Data.fromNumber(32), + offset: Raw.fromNumber(0), + length: Raw.fromNumber(32), }); expect(regions.lookup["b"]).toMatchObject({ - offset: Data.fromNumber(12), - length: Data.fromNumber(20), + offset: Raw.fromNumber(12), + length: Raw.fromNumber(20), }); expect(regions[2]).toEqual({ location: "memory", - offset: Data.fromNumber(0), - length: Data.fromNumber(52), + offset: Raw.fromNumber(0), + length: Raw.fromNumber(52), }); }); @@ -167,8 +152,8 @@ describe("dereference", () => { expect(region).toEqual({ name: "item", location: "memory", - offset: Data.fromUint(BigInt(index) * 32n), - length: Data.fromNumber(32), + offset: Raw.fromUint(BigInt(index) * 32n), + length: Raw.fromNumber(32), }); } }); @@ -187,8 +172,8 @@ describe("dereference", () => { expect(regions).toHaveLength(1); expect(regions[0]).toEqual({ location: "memory", - offset: Data.fromNumber(32), - length: Data.fromNumber(32), + offset: Raw.fromNumber(32), + length: Raw.fromNumber(32), }); }); @@ -206,8 +191,8 @@ describe("dereference", () => { expect(regions).toHaveLength(1); expect(regions[0]).toEqual({ location: "memory", - offset: Data.fromNumber(32), - length: Data.fromNumber(32), + offset: Raw.fromNumber(32), + length: Raw.fromNumber(32), }); }); @@ -226,9 +211,9 @@ describe("dereference", () => { expect(regions).toHaveLength(1); expect(regions[0]).toEqual({ location: "storage", - slot: Data.fromNumber(32), - offset: Data.fromNumber(32), - length: Data.fromNumber(32), + slot: Raw.fromNumber(32), + offset: Raw.fromNumber(32), + length: Raw.fromNumber(32), }); }); @@ -257,7 +242,7 @@ describe("dereference", () => { const { regions } = await cursor.view(state); - expect(regions.map(({ offset }) => offset!.asUint())).toEqual([ + expect(regions.map(({ offset }) => Raw.asUint(offset!))).toEqual([ 64n, 96n, 128n, @@ -337,8 +322,8 @@ describe("dereference", () => { const { regions } = await cursor.view(state); expect(regions).toHaveLength(1); - expect(regions[0].offset).toEqual(Data.fromNumber(0)); - expect(regions[0].length).toEqual(Data.fromNumber(32)); + expect(regions[0].offset).toEqual(Raw.fromNumber(0)); + expect(regions[0].length).toEqual(Raw.fromNumber(32)); }); it("scopes defined variables to their `in`", async () => { @@ -364,8 +349,8 @@ describe("dereference", () => { const { regions } = await cursor.view(state); expect(regions.map(({ name }) => name)).toEqual(["a", "b"]); - expect(regions[0]).toMatchObject({ slot: Data.fromNumber(1) }); - expect(regions[1]).toMatchObject({ slot: Data.fromNumber(2) }); + expect(regions[0]).toMatchObject({ slot: Raw.fromNumber(1) }); + expect(regions[1]).toMatchObject({ slot: Raw.fromNumber(2) }); }); describe("define member order", () => { @@ -386,7 +371,7 @@ describe("dereference", () => { it("evaluates members after the members they use", async () => { expect( await regionOf({ result: { "~sum": ["a", 1] }, a: 5 }), - ).toMatchObject({ slot: Data.fromNumber(6) }); + ).toMatchObject({ slot: Raw.fromNumber(6) }); }); it("evaluates a longer chain in any order", async () => { @@ -397,19 +382,19 @@ describe("dereference", () => { b: { "~sum": ["a", 2] }, a: 1, }), - ).toMatchObject({ slot: Data.fromNumber(7) }); + ).toMatchObject({ slot: Raw.fromNumber(7) }); }); it("binds a member's own name to the enclosing scope", async () => { expect( await regionOf({ result: { "~sum": ["result", 1] } }, { result: 4 }), - ).toMatchObject({ slot: Data.fromNumber(5) }); + ).toMatchObject({ slot: Raw.fromNumber(5) }); }); it("hides an outer variable from the other members", async () => { expect( await regionOf({ result: { "~sum": ["a", 1] }, a: 5 }, { a: 100 }), - ).toMatchObject({ slot: Data.fromNumber(6) }); + ).toMatchObject({ slot: Raw.fromNumber(6) }); }); it("resolves the scope schema's out-of-order example", async () => { @@ -421,8 +406,8 @@ describe("dereference", () => { )!; const { regions } = await (await dereference(example)).view(state); expect(regions[0]).toMatchObject({ - offset: Data.fromNumber(96), - length: Data.fromNumber(32), + offset: Raw.fromNumber(96), + length: Raw.fromNumber(32), }); }); @@ -475,8 +460,8 @@ describe("dereference", () => { const { regions } = await cursor.view(state); - expect(regions[0]).toMatchObject({ slot: Data.fromNumber(1) }); - expect(regions[1]).toMatchObject({ slot: Data.fromNumber(2) }); + expect(regions[0]).toMatchObject({ slot: Raw.fromNumber(1) }); + expect(regions[1]).toMatchObject({ slot: Raw.fromNumber(2) }); }); it("works for templates", async () => { @@ -506,8 +491,8 @@ describe("dereference", () => { const { regions } = await cursor.view(state); expect(regions).toHaveLength(1); - expect(regions[0].offset).toEqual(Data.fromNumber(0)); - expect(regions[0].length).toEqual(Data.fromNumber(32)); + expect(regions[0].offset).toEqual(Raw.fromNumber(0)); + expect(regions[0].length).toEqual(Raw.fromNumber(32)); }); it("works for template references with yields (basic rename)", async () => { @@ -656,13 +641,13 @@ describe("dereference", () => { expect(regions).toHaveLength(2); expect(regions[0].name).toEqual("my-first"); - expect(regions[0].offset).toEqual(Data.fromNumber(64)); - expect(regions[0].length).toEqual(Data.fromNumber(32)); + expect(regions[0].offset).toEqual(Raw.fromNumber(64)); + expect(regions[0].length).toEqual(Raw.fromNumber(32)); // Second region depends on first via internal reference expect(regions[1].name).toEqual("my-second"); - expect(regions[1].offset).toEqual(Data.fromNumber(96)); // 64 + 32 - expect(regions[1].length).toEqual(Data.fromNumber(32)); + expect(regions[1].offset).toEqual(Raw.fromNumber(96)); // 64 + 32 + expect(regions[1].length).toEqual(Raw.fromNumber(32)); }); it("works for nested template references with yields", async () => { @@ -730,8 +715,8 @@ describe("dereference", () => { const { regions } = await cursor.view(state); expect(regions).toHaveLength(2); - expect(regions[1].offset).toEqual(Data.fromNumber(32)); - expect(regions[1].length).toEqual(Data.fromNumber(4)); + expect(regions[1].offset).toEqual(Raw.fromNumber(32)); + expect(regions[1].length).toEqual(Raw.fromNumber(4)); }); it("allows renaming the region with yields", async () => { @@ -812,8 +797,8 @@ describe("dereference", () => { const { regions } = await cursor.view(state); expect(regions).toHaveLength(1); - expect(regions[0].offset).toEqual(Data.fromNumber(0)); - expect(regions[0].length).toEqual(Data.fromNumber(32)); + expect(regions[0].offset).toEqual(Raw.fromNumber(0)); + expect(regions[0].length).toEqual(Raw.fromNumber(32)); }); it("inline templates take precedence over external templates", async () => { @@ -893,7 +878,7 @@ describe("dereference", () => { expect(regions).toHaveLength(1); expect(regions[0].name).toEqual("data"); - expect(regions[0].offset).toEqual(Data.fromNumber(128)); + expect(regions[0].offset).toEqual(Raw.fromNumber(128)); }); it("inline templates with yields work correctly", async () => { @@ -940,14 +925,14 @@ describe("dereference", () => { it("defaults to the whole value of the expression", async () => { const { regions, read } = await view(x); - const value = Data.fromNumber(0x11223345).resizeTo(32); + const value = Raw.resizeTo(Raw.fromNumber(0x11223345), 32); expect(regions.lookup["x"]).toEqual({ name: "x", location: "virtual", expression: value, - offset: Data.fromUint(0n), - length: Data.fromNumber(32), + offset: Raw.fromUint(0n), + length: Raw.fromNumber(32), }); expect(await read(regions.lookup["x"])).toEqual(value); }); @@ -963,11 +948,11 @@ describe("dereference", () => { }, ); - expect(await read(regions.lookup["x"])).toEqual(Data.fromHex("0x2233")); + expect(await read(regions.lookup["x"])).toEqual(Raw.fromHex("0x2233")); expect(await read(regions.lookup["rest"])).toEqual( - Data.fromHex("0xadbeef"), + Raw.fromHex("0xadbeef"), ); - expect(regions.lookup["rest"].length).toEqual(Data.fromNumber(3)); + expect(regions.lookup["rest"].length).toEqual(Raw.fromNumber(3)); }); it("allows lookups of offset and length from a later region", async () => { @@ -987,8 +972,8 @@ describe("dereference", () => { expect(regions[2]).toEqual({ location: "memory", - offset: Data.fromNumber(1), - length: Data.fromNumber(3), + offset: Raw.fromNumber(1), + length: Raw.fromNumber(3), }); }); @@ -1000,7 +985,7 @@ describe("dereference", () => { length: 2, }); - expect(await read(regions.lookup["y"])).toEqual(Data.fromHex("0x0000")); + expect(await read(regions.lookup["y"])).toEqual(Raw.fromHex("0x0000")); expect(regions.lookup["y"]).toHaveProperty("expression.length", 33); }); @@ -1048,8 +1033,8 @@ describe("dereference", () => { expect(regions[1]).toEqual({ location: "memory", - offset: Data.fromNumber(0x40), - length: Data.fromNumber(0x10), + offset: Raw.fromNumber(0x40), + length: Raw.fromNumber(0x10), }); }); @@ -1077,8 +1062,8 @@ describe("dereference", () => { expect(regions[0]).toEqual({ location: "memory", - offset: Data.fromNumber(7), - length: Data.fromNumber(7), + offset: Raw.fromNumber(7), + length: Raw.fromNumber(7), }); }); diff --git a/packages/pointers/src/dereference/index.ts b/packages/pointers/src/dereference/index.ts index 8c6f59119c..554421dfa2 100644 --- a/packages/pointers/src/dereference/index.ts +++ b/packages/pointers/src/dereference/index.ts @@ -1,5 +1,5 @@ import type { Pointer } from "@ethdebug/format"; -import type { Machine } from "#machine"; +import type { Machine } from "@ethdebug/common"; import type { Cursor } from "#cursor"; import { generateRegions, type GenerateRegionsOptions } from "./generate.js"; diff --git a/packages/pointers/src/dereference/process.ts b/packages/pointers/src/dereference/process.ts index fc9d6b7bd7..5e091e5f29 100644 --- a/packages/pointers/src/dereference/process.ts +++ b/packages/pointers/src/dereference/process.ts @@ -1,5 +1,5 @@ import { Pointer } from "@ethdebug/format"; -import type { Machine } from "#machine"; +import type { Machine } from "@ethdebug/common"; import type { Cursor } from "#cursor"; import { evaluate, Value } from "#evaluate"; diff --git a/packages/pointers/src/dereference/region.ts b/packages/pointers/src/dereference/region.ts index a1e93b526d..f6dc73118c 100644 --- a/packages/pointers/src/dereference/region.ts +++ b/packages/pointers/src/dereference/region.ts @@ -1,6 +1,6 @@ import { Pointer } from "@ethdebug/format"; import type { Cursor } from "#cursor"; -import { Data } from "#data"; +import { Raw } from "@ethdebug/common"; import { evaluate, Value, type EvaluateOptions } from "#evaluate"; /** @@ -21,7 +21,7 @@ export async function evaluateRegion( options: EvaluateOptions, ): Promise> { const evaluatedProperties: { - [K in keyof R]?: Data; + [K in keyof R]?: Raw; } = {}; const propertyAttempts: { [K in keyof R]?: number; @@ -128,7 +128,7 @@ export async function evaluateRegion( */ async function evaluateFragment( region: Pointer.Region.Virtual, - { offset, length }: { offset?: Data; length?: Data }, + { offset, length }: { offset?: Raw; length?: Raw }, options: EvaluateOptions, ): Promise> { const value = await evaluate(region.expression, options); @@ -143,10 +143,10 @@ async function evaluateFragment( } const width = BigInt(value.data.length); - const start = offset?.asUint() ?? 0n; - const end = length ? start + length.asUint() : width; + const start = offset ? Raw.asUint(offset) : 0n; + const end = length ? start + Raw.asUint(length) : width; if (start > width || end > width) { - const fields = length ? `${start}, length ${length.asUint()}` : start; + const fields = length ? `${start}, length ${Raw.asUint(length)}` : start; throw new Error( `Fragment of virtual region (offset ${fields}) extends outside ` + `the ${width} bytes of its expression's value`, @@ -156,8 +156,8 @@ async function evaluateFragment( return { ...region, expression: value.data, - offset: Data.fromUint(start), - length: Data.fromUint(end - start), + offset: Raw.fromUint(start), + length: Raw.fromUint(end - start), }; } diff --git a/packages/pointers/src/evaluate.examples.test.ts b/packages/pointers/src/evaluate.examples.test.ts index e257b0a949..2212d3920b 100644 --- a/packages/pointers/src/evaluate.examples.test.ts +++ b/packages/pointers/src/evaluate.examples.test.ts @@ -2,8 +2,7 @@ import { expect, describe, it } from "vitest"; import { Pointer, schemaIds, schemas } from "@ethdebug/format"; -import type { Machine } from "#machine"; -import { Data } from "#data"; +import { type Machine, Raw } from "@ethdebug/common"; import type { Cursor } from "#cursor"; import { evaluate, Value, type EvaluateOptions } from "./evaluate.js"; @@ -35,12 +34,12 @@ function stubValue(expression: Pointer.Expression): Value { Pointer.Expression.isRead(expression) || isWidthSensitive(expression) ) { - return Value.bytes(Data.fromNumber(0).resizeTo(32)); + return Value.bytes(Raw.resizeTo(Raw.fromNumber(0), 32)); } if (typeof expression === "string" && expression.startsWith("0x")) { return (expression.length - 2) % 2 === 0 - ? Value.bytes(Data.fromHex(expression)) + ? Value.bytes(Raw.fromHex(expression)) : Value.integer(BigInt(expression)); } @@ -88,7 +87,7 @@ const zeros = async ({ slice: { length }, }: { slice: Machine.State.Slice; -}): Promise => Data.fromBytes(new Uint8Array(Number(length))); +}): Promise => new Uint8Array(Number(length)); const state = { memory: { read: zeros }, @@ -99,8 +98,8 @@ const regions = new Proxy({} as { [identifier: string]: Cursor.Region }, { get: (_target, name): Cursor.Region => ({ name: String(name), location: "memory", - offset: Data.fromNumber(0), - length: Data.fromNumber(32), + offset: Raw.fromNumber(0), + length: Raw.fromNumber(32), }), }); diff --git a/packages/pointers/src/evaluate.test.ts b/packages/pointers/src/evaluate.test.ts index 98718c7d33..36052a83f6 100644 --- a/packages/pointers/src/evaluate.test.ts +++ b/packages/pointers/src/evaluate.test.ts @@ -4,8 +4,7 @@ import { keccak256 } from "ethereum-cryptography/keccak"; import { Pointer } from "@ethdebug/format"; -import { Machine } from "#machine"; -import { Data } from "#data"; +import { type Machine, Raw } from "@ethdebug/common"; import { Cursor } from "#cursor"; import { evaluate, Value, type EvaluateOptions } from "./evaluate.js"; @@ -19,7 +18,7 @@ const state: Machine.State = { } as any, memory: { read: vitest.fn(async ({ slice: { length } }) => - Data.fromBytes(new Uint8Array(Number(length)).fill(0xee)), + new Uint8Array(Number(length)).fill(0xee), ), } as any, storage: {} as any, @@ -29,8 +28,7 @@ const state: Machine.State = { code: {} as any, }; -const word = (byte: number): Data => - Data.fromBytes(new Uint8Array(32).fill(byte)); +const word = (byte: number): Raw => new Uint8Array(32).fill(byte); describe("evaluate", () => { let regions: { [identifier: string]: Cursor.Region }; @@ -40,22 +38,22 @@ describe("evaluate", () => { beforeEach(() => { variables = { foo: Value.integer(42n), - bar: Value.bytes(Data.fromHex("0x1f")), + bar: Value.bytes(Raw.fromHex("0x1f")), }; regions = { stack: { name: "stack", location: "stack", - slot: Data.fromNumber(42), - offset: Data.fromNumber(0x60), - length: Data.fromNumber(0x1f / 2), + slot: Raw.fromNumber(42), + offset: Raw.fromNumber(0x60), + length: Raw.fromNumber(0x1f / 2), }, memory: { name: "memory", location: "memory", - offset: Data.fromNumber(0x20 * 0x05), - length: Data.fromNumber(42 - 0x1f), + offset: Raw.fromNumber(0x20 * 0x05), + length: Raw.fromNumber(42 - 0x1f), }, }; @@ -74,11 +72,11 @@ describe("evaluate", () => { it("evaluates even-digit hex to bytes of that width", async () => { expect(await evaluate("0x1f", options)).toEqual( - Value.bytes(Data.fromHex("0x1f")), + Value.bytes(Raw.fromHex("0x1f")), ); const zeros = await evaluate("0x0000", options); - expect(zeros).toEqual(Value.bytes(Data.fromHex("0x0000"))); + expect(zeros).toEqual(Value.bytes(Raw.fromHex("0x0000"))); expect(Value.isBytes(zeros) && zeros.data.length).toBe(2); }); @@ -96,7 +94,7 @@ describe("evaluate", () => { expect(await evaluate("foo", options)).toEqual(Value.integer(42n)); expect(await evaluate("bar", options)).toEqual( - Value.bytes(Data.fromHex("0x1f")), + Value.bytes(Raw.fromHex("0x1f")), ); }); @@ -175,8 +173,8 @@ describe("evaluate", () => { const thisRegion = { name: "~this", location: "memory", - offset: Data.fromNumber(0x120), - length: Data.fromNumber(0x40), + offset: Raw.fromNumber(0x120), + length: Raw.fromNumber(0x40), } as const; expect( @@ -215,75 +213,73 @@ describe("evaluate", () => { it("evaluates ~read to bytes of the region's length", async () => { const result = await evaluate({ "~read": "memory" }, options); - expect(result).toEqual( - Value.bytes(Data.fromBytes(new Uint8Array(11).fill(0xee))), - ); + expect(result).toEqual(Value.bytes(new Uint8Array(11).fill(0xee))); }); describe("resize", () => { it("gives an integer a width", async () => { expect(await evaluate({ "~sized1": 0 }, options)).toEqual( - Value.bytes(Data.fromHex("0x00")), + Value.bytes(Raw.fromHex("0x00")), ); expect(await evaluate({ "~sized2": 42 }, options)).toEqual( - Value.bytes(Data.fromHex("0x002a")), + Value.bytes(Raw.fromHex("0x002a")), ); expect(await evaluate({ "~wordsized": 0xabcd }, options)).toEqual( - Value.bytes(Data.fromNumber(0xabcd).resizeTo(32)), + Value.bytes(Raw.resizeTo(Raw.fromNumber(0xabcd), 32)), ); }); it("resizes bytes, padding or truncating on the left", async () => { expect(await evaluate({ "~sized1": "0xabcd" }, options)).toEqual( - Value.bytes(Data.fromHex("0xcd")), + Value.bytes(Raw.fromHex("0xcd")), ); expect(await evaluate({ "~sized4": "0xabcd" }, options)).toEqual( - Value.bytes(Data.fromHex("0x0000abcd")), + Value.bytes(Raw.fromHex("0x0000abcd")), ); expect(await evaluate({ "~wordsized": "0xabcd" }, options)).toEqual( - Value.bytes(Data.fromHex("0xabcd").resizeTo(32)), + Value.bytes(Raw.resizeTo(Raw.fromHex("0xabcd"), 32)), ); }); it("truncates an integer too large for the requested width", async () => { expect(await evaluate({ "~sized1": 0x1234 }, options)).toEqual( - Value.bytes(Data.fromHex("0x34")), + Value.bytes(Raw.fromHex("0x34")), ); }); it("gives arithmetic results a width", async () => { expect( await evaluate({ "~sized2": { "~sum": [1, 2] } }, options), - ).toEqual(Value.bytes(Data.fromHex("0x0003"))); + ).toEqual(Value.bytes(Raw.fromHex("0x0003"))); }); }); describe("~concat", () => { it("concatenates hex literals", async () => { expect(await evaluate({ "~concat": ["0x00", "0x00"] }, options)).toEqual( - Value.bytes(Data.fromHex("0x0000")), + Value.bytes(Raw.fromHex("0x0000")), ); }); it("concatenates multiple values preserving byte widths", async () => { expect( await evaluate({ "~concat": ["0xdead", "0xbeef"] }, options), - ).toEqual(Value.bytes(Data.fromHex("0xdeadbeef"))); + ).toEqual(Value.bytes(Raw.fromHex("0xdeadbeef"))); }); it("returns empty bytes for an empty operand list", async () => { expect(await evaluate({ "~concat": [] }, options)).toEqual( - Value.bytes(Data.zero()), + Value.bytes(Raw.zero()), ); }); it("preserves a single operand unchanged", async () => { expect(await evaluate({ "~concat": ["0xabcdef"] }, options)).toEqual( - Value.bytes(Data.fromHex("0xabcdef")), + Value.bytes(Raw.fromHex("0xabcdef")), ); }); @@ -293,7 +289,7 @@ describe("evaluate", () => { options, ); - expect(result).toEqual(Value.bytes(Data.fromHex("0x00010002"))); + expect(result).toEqual(Value.bytes(Raw.fromHex("0x00010002"))); }); it("concatenates bytes-valued variables and resized integers", async () => { @@ -306,7 +302,7 @@ describe("evaluate", () => { }; expect(await evaluate(expression, options)).toEqual( - Value.bytes(Data.fromHex("0x002a1f03")), + Value.bytes(Raw.fromHex("0x002a1f03")), ); }); @@ -361,16 +357,15 @@ describe("evaluate", () => { ], }; - const preimage = Data.fromNumber(42) - .resizeTo(32) - .concat( - Data.fromHex("0x1f"), - Data.fromHex("0x2a"), - Data.fromHex("0x1f"), - ); + const preimage = Raw.concat( + Raw.resizeTo(Raw.fromNumber(42), 32), + Raw.fromHex("0x1f"), + Raw.fromHex("0x2a"), + Raw.fromHex("0x1f"), + ); expect(await evaluate(expression, options)).toEqual( - Value.bytes(Data.fromBytes(keccak256(preimage))), + Value.bytes(keccak256(preimage)), ); }); @@ -378,9 +373,7 @@ describe("evaluate", () => { const result = await evaluate({ "~keccak256": [] }, options); expect(Value.isBytes(result) && result.data.length).toBe(32); - expect(result).toEqual( - Value.bytes(Data.fromBytes(keccak256(new Uint8Array(0)))), - ); + expect(result).toEqual(Value.bytes(keccak256(new Uint8Array(0)))); }); it("hashes a word-sized key and slot over 64 bytes", async () => { @@ -388,11 +381,14 @@ describe("evaluate", () => { "~keccak256": [{ "~wordsized": "0x1234" }, { "~wordsized": 0 }], }; - const preimage = Data.fromHex("0x1234").resizeTo(32).concat(word(0)); + const preimage = Raw.concat( + Raw.resizeTo(Raw.fromHex("0x1234"), 32), + word(0), + ); expect(preimage).toHaveLength(64); expect(await evaluate(expression, options)).toEqual( - Value.bytes(Data.fromBytes(keccak256(preimage))), + Value.bytes(keccak256(preimage)), ); }); @@ -419,8 +415,8 @@ describe("evaluate, with names that start with $", () => { const region = (name: string, offset: number): Cursor.Region => ({ name, location: "memory", - offset: Data.fromNumber(offset), - length: Data.fromNumber(0x20), + offset: Raw.fromNumber(offset), + length: Raw.fromNumber(0x20), }); const options: EvaluateOptions = { @@ -467,16 +463,16 @@ describe("evaluate, with names that start with $", () => { describe("Value", () => { it("coerces bytes to a big-endian integer", () => { - expect(Value.toInteger(Value.bytes(Data.fromHex("0x0100")))).toBe(256n); - expect(Value.toInteger(Value.bytes(Data.zero()))).toBe(0n); + expect(Value.toInteger(Value.bytes(Raw.fromHex("0x0100")))).toBe(256n); + expect(Value.toInteger(Value.bytes(Raw.zero()))).toBe(0n); expect(Value.toInteger(Value.integer(7n))).toBe(7n); }); it("encodes an integer as minimal big-endian bytes for region data", () => { - expect(Value.toData(Value.integer(0n))).toEqual(Data.zero()); - expect(Value.toData(Value.integer(256n))).toEqual(Data.fromHex("0x0100")); - expect(Value.toData(Value.bytes(Data.fromHex("0x0000")))).toEqual( - Data.fromHex("0x0000"), + expect(Value.toData(Value.integer(0n))).toEqual(Raw.zero()); + expect(Value.toData(Value.integer(256n))).toEqual(Raw.fromHex("0x0100")); + expect(Value.toData(Value.bytes(Raw.fromHex("0x0000")))).toEqual( + Raw.fromHex("0x0000"), ); }); }); diff --git a/packages/pointers/src/evaluate.ts b/packages/pointers/src/evaluate.ts index f208c37b06..2f9b8643ab 100644 --- a/packages/pointers/src/evaluate.ts +++ b/packages/pointers/src/evaluate.ts @@ -1,9 +1,7 @@ import { Pointer } from "@ethdebug/format"; -import type { Machine } from "#machine"; -import { Data } from "#data"; +import { type Machine, Raw, keccak256 } from "@ethdebug/common"; import type { Cursor } from "#cursor"; import { read } from "#read"; -import { keccak256 } from "ethereum-cryptography/keccak"; /** * The result of evaluating an expression: one of two sorts of value. @@ -27,7 +25,7 @@ export namespace Value { export interface Bytes { sort: "bytes"; - data: Data; + data: Raw; } export const integer = (value: bigint): Integer => ({ @@ -35,7 +33,7 @@ export namespace Value { value, }); - export const bytes = (data: Data): Bytes => ({ sort: "bytes", data }); + export const bytes = (data: Raw): Bytes => ({ sort: "bytes", data }); export const isInteger = (value: Value): value is Integer => value.sort === "integer"; @@ -49,16 +47,16 @@ export namespace Value { * are read as the non-negative integer they encode big-endian. */ export const toInteger = (value: Value): bigint => - isInteger(value) ? value.value : value.data.asUint(); + isInteger(value) ? value.value : Raw.asUint(value.data); /** - * Represent as `Data` for storage on a concrete `Cursor.Region`. Bytes + * Represent as `Raw` for storage on a concrete `Cursor.Region`. Bytes * keep their width; an integer is encoded as its minimal big-endian * bytes (a region's slot/offset/length are integers, so this width is * not significant). */ - export const toData = (value: Value): Data => - isBytes(value) ? value.data : Data.fromUint(value.value); + export const toData = (value: Value): Raw => + isBytes(value) ? value.data : Raw.fromUint(value.value); } export interface EvaluateOptions { @@ -167,7 +165,7 @@ async function evaluateBytesOperands( operation: "~concat" | "~keccak256", operands: Pointer.Expression[], options: EvaluateOptions, -): Promise { +): Promise { return await Promise.all( operands.map(async (operand, index) => { const value = await evaluate(operand, options); @@ -199,7 +197,7 @@ async function evaluateLiteral( return Value.integer(BigInt(literal)); } - return Value.bytes(Data.fromHex(literal)); + return Value.bytes(Raw.fromHex(literal)); } case "number": return Value.integer(BigInt(literal)); @@ -276,9 +274,9 @@ async function evaluateKeccak256( options, ); - const preimage = Data.zero().concat(...operands); + const preimage = Raw.concat(...operands); - return Value.bytes(Data.fromBytes(keccak256(preimage))); + return Value.bytes(keccak256(preimage)); } async function evaluateConcat( @@ -291,7 +289,7 @@ async function evaluateConcat( options, ); - return Value.bytes(Data.zero().concat(...operands)); + return Value.bytes(Raw.concat(...operands)); } async function evaluateResize( @@ -306,7 +304,7 @@ async function evaluateResize( const value = await evaluate(subexpression, options); - return Value.bytes(Value.toData(value).resizeTo(newLength)); + return Value.bytes(Raw.resizeTo(Value.toData(value), newLength)); } async function evaluateLookup( @@ -324,7 +322,7 @@ async function evaluateLookup( const property = Pointer.Expression.Lookup.propertyFrom(operation); - const data = region[property as keyof typeof region] as Data | undefined; + const data = region[property as keyof typeof region] as Raw | undefined; if (typeof data === "undefined") { throw new Error( @@ -332,7 +330,7 @@ async function evaluateLookup( ); } - return Value.integer(data.asUint()); + return Value.integer(Raw.asUint(data)); } async function evaluateRead( diff --git a/packages/pointers/src/index.ts b/packages/pointers/src/index.ts index 5475fbbf88..3467053df6 100644 --- a/packages/pointers/src/index.ts +++ b/packages/pointers/src/index.ts @@ -1,5 +1,2 @@ export { dereference, DereferenceOptions } from "#dereference"; export { Cursor } from "#cursor"; - -export type { Machine } from "#machine"; -export { Data } from "#data"; diff --git a/packages/pointers/src/read.test.ts b/packages/pointers/src/read.test.ts index 467bfe5761..65506056c5 100644 --- a/packages/pointers/src/read.test.ts +++ b/packages/pointers/src/read.test.ts @@ -2,8 +2,7 @@ import { vitest, expect, describe, it, beforeEach } from "vitest"; import type { Pointer } from "@ethdebug/format"; -import { Machine } from "#machine"; -import { Data } from "#data"; +import { type Machine, Raw } from "@ethdebug/common"; import { read, type ReadOptions } from "./read.js"; import { Cursor } from "#cursor"; @@ -14,38 +13,41 @@ describe("read", () => { const state: Machine.State = { stack: { length: 50n, - peek: vitest.fn(async ({ depth: _depth, slice: _slice }) => - Data.fromBytes(new Uint8Array([0x11, 0x22, 0x33, 0x44])), + peek: vitest.fn( + async ({ depth: _depth, slice: _slice }) => + new Uint8Array([0x11, 0x22, 0x33, 0x44]), ), }, memory: { - read: vitest.fn(async ({ slice: _slice }) => - Data.fromBytes(new Uint8Array([0x55, 0x66, 0x77, 0x88])), + read: vitest.fn( + async ({ slice: _slice }) => new Uint8Array([0x55, 0x66, 0x77, 0x88]), ), }, storage: { - read: vitest.fn(async ({ slot: _slot, slice: _slice }) => - Data.fromBytes(new Uint8Array([0xaa, 0xbb, 0xcc, 0xdd])), + read: vitest.fn( + async ({ slot: _slot, slice: _slice }) => + new Uint8Array([0xaa, 0xbb, 0xcc, 0xdd]), ), }, calldata: { - read: vitest.fn(async ({ slice: _slice }) => - Data.fromBytes(new Uint8Array([0x11, 0x22, 0x33, 0x44])), + read: vitest.fn( + async ({ slice: _slice }) => new Uint8Array([0x11, 0x22, 0x33, 0x44]), ), }, returndata: { - read: vitest.fn(async ({ slice: _slice }) => - Data.fromBytes(new Uint8Array([0x55, 0x66, 0x77, 0x88])), + read: vitest.fn( + async ({ slice: _slice }) => new Uint8Array([0x55, 0x66, 0x77, 0x88]), ), }, transient: { - read: vitest.fn(async ({ slot: _slot, slice: _slice }) => - Data.fromBytes(new Uint8Array([0xaa, 0xbb, 0xcc, 0xdd])), + read: vitest.fn( + async ({ slot: _slot, slice: _slice }) => + new Uint8Array([0xaa, 0xbb, 0xcc, 0xdd]), ), }, code: { - read: vitest.fn(async ({ slice: _slice }) => - Data.fromBytes(new Uint8Array([0x11, 0x22, 0x33, 0x44])), + read: vitest.fn( + async ({ slice: _slice }) => new Uint8Array([0x11, 0x22, 0x33, 0x44]), ), }, } as unknown as Machine.State; @@ -58,9 +60,9 @@ describe("read", () => { it("reads data from stack", async () => { const region: Cursor.Region = { location: "stack", - slot: Data.fromNumber(42), - offset: Data.fromNumber(1), - length: Data.fromNumber(2), + slot: Raw.fromNumber(42), + offset: Raw.fromNumber(1), + length: Raw.fromNumber(2), }; const result = await read(region, options); @@ -69,16 +71,14 @@ describe("read", () => { depth: 42n, slice: { offset: 1n, length: 2n }, }); - expect(result).toEqual( - Data.fromBytes(new Uint8Array([0x11, 0x22, 0x33, 0x44])), - ); + expect(result).toEqual(new Uint8Array([0x11, 0x22, 0x33, 0x44])); }); it("reads data from memory", async () => { const region: Cursor.Region = { location: "memory", - offset: Data.fromNumber(0), - length: Data.fromNumber(4), + offset: Raw.fromNumber(0), + length: Raw.fromNumber(4), }; const result = await read(region, options); @@ -86,36 +86,32 @@ describe("read", () => { expect(options.state.memory.read).toHaveBeenCalledWith({ slice: { offset: 0n, length: 4n }, }); - expect(result).toEqual( - Data.fromBytes(new Uint8Array([0x55, 0x66, 0x77, 0x88])), - ); + expect(result).toEqual(new Uint8Array([0x55, 0x66, 0x77, 0x88])); }); it("reads data from storage", async () => { const region: Cursor.Region = { location: "storage", - slot: Data.fromNumber(0), - offset: Data.fromNumber(2), - length: Data.fromNumber(2), + slot: Raw.fromNumber(0), + offset: Raw.fromNumber(2), + length: Raw.fromNumber(2), }; const result = await read(region, options); expect(options.state.storage.read).toHaveBeenCalledWith({ - slot: Data.fromNumber(0), + slot: Raw.fromNumber(0), slice: { offset: 2n, length: 2n }, }); - expect(result).toEqual( - Data.fromBytes(new Uint8Array([0xaa, 0xbb, 0xcc, 0xdd])), - ); + expect(result).toEqual(new Uint8Array([0xaa, 0xbb, 0xcc, 0xdd])); }); it("reads data from calldata", async () => { const region: Cursor.Region = { location: "calldata", - offset: Data.fromNumber(0), - length: Data.fromNumber(4), + offset: Raw.fromNumber(0), + length: Raw.fromNumber(4), }; const result = await read(region, options); @@ -123,16 +119,14 @@ describe("read", () => { expect(options.state.calldata.read).toHaveBeenCalledWith({ slice: { offset: 0n, length: 4n }, }); - expect(result).toEqual( - Data.fromBytes(new Uint8Array([0x11, 0x22, 0x33, 0x44])), - ); + expect(result).toEqual(new Uint8Array([0x11, 0x22, 0x33, 0x44])); }); it("reads data from returndata", async () => { const region: Cursor.Region = { location: "returndata", - offset: Data.fromNumber(0), - length: Data.fromNumber(4), + offset: Raw.fromNumber(0), + length: Raw.fromNumber(4), }; const result = await read(region, options); @@ -140,36 +134,32 @@ describe("read", () => { expect(options.state.returndata.read).toHaveBeenCalledWith({ slice: { offset: 0n, length: 4n }, }); - expect(result).toEqual( - Data.fromBytes(new Uint8Array([0x55, 0x66, 0x77, 0x88])), - ); + expect(result).toEqual(new Uint8Array([0x55, 0x66, 0x77, 0x88])); }); it("reads data from transient", async () => { const region: Cursor.Region = { location: "transient", - slot: Data.fromNumber(42), - offset: Data.fromNumber(1), - length: Data.fromNumber(2), + slot: Raw.fromNumber(42), + offset: Raw.fromNumber(1), + length: Raw.fromNumber(2), }; const result = await read(region, options); expect(options.state.transient.read).toHaveBeenCalledWith({ - slot: Data.fromNumber(42), + slot: Raw.fromNumber(42), slice: { offset: 1n, length: 2n }, }); - expect(result).toEqual( - Data.fromBytes(new Uint8Array([0xaa, 0xbb, 0xcc, 0xdd])), - ); + expect(result).toEqual(new Uint8Array([0xaa, 0xbb, 0xcc, 0xdd])); }); it("reads data from code", async () => { const region: Cursor.Region = { location: "code", - offset: Data.fromNumber(0), - length: Data.fromNumber(4), + offset: Raw.fromNumber(0), + length: Raw.fromNumber(4), }; const result = await read(region, options); @@ -178,15 +168,13 @@ describe("read", () => { slice: { offset: 0n, length: 4n }, }); - expect(result).toEqual( - Data.fromBytes(new Uint8Array([0x11, 0x22, 0x33, 0x44])), - ); + expect(result).toEqual(new Uint8Array([0x11, 0x22, 0x33, 0x44])); }); it("uses default offset and length values for stack region", async () => { const region: Cursor.Region = { location: "stack", - slot: Data.fromNumber(42), + slot: Raw.fromNumber(42), }; const result = await read(region, options); @@ -196,45 +184,39 @@ describe("read", () => { slice: { offset: 0n, length: 32n }, }); - expect(result).toEqual( - Data.fromBytes(new Uint8Array([0x11, 0x22, 0x33, 0x44])), - ); + expect(result).toEqual(new Uint8Array([0x11, 0x22, 0x33, 0x44])); }); it("uses default offset and length values for storage region", async () => { const region: Cursor.Region = { location: "storage", - slot: Data.fromHex("0x1f"), + slot: Raw.fromHex("0x1f"), }; const result = await read(region, options); expect(options.state.storage.read).toHaveBeenCalledWith({ - slot: Data.fromHex("0x1f"), + slot: Raw.fromHex("0x1f"), slice: { offset: 0n, length: 32n }, }); - expect(result).toEqual( - Data.fromBytes(new Uint8Array([0xaa, 0xbb, 0xcc, 0xdd])), - ); + expect(result).toEqual(new Uint8Array([0xaa, 0xbb, 0xcc, 0xdd])); }); it("uses default offset and length values for transient region", async () => { const region: Cursor.Region = { location: "transient", - slot: Data.fromNumber(42), + slot: Raw.fromNumber(42), }; const result = await read(region, options); expect(options.state.transient.read).toHaveBeenCalledWith({ - slot: Data.fromNumber(42), + slot: Raw.fromNumber(42), slice: { offset: 0n, length: 32n }, }); - expect(result).toEqual( - Data.fromBytes(new Uint8Array([0xaa, 0xbb, 0xcc, 0xdd])), - ); + expect(result).toEqual(new Uint8Array([0xaa, 0xbb, 0xcc, 0xdd])); }); }); @@ -247,19 +229,17 @@ describe("read (segment carry)", () => { const sliced = ( word: Uint8Array, slice: Machine.State.Slice | undefined, - ): Data => - Data.fromBytes( - slice - ? word.slice(Number(slice.offset), Number(slice.offset + slice.length)) - : word, - ); + ): Raw => + slice + ? word.slice(Number(slice.offset), Number(slice.offset + slice.length)) + : word; let options: ReadOptions; beforeEach(() => { const words: Machine.State.Words = { read: vitest.fn(async ({ slot, slice }) => - sliced(wordFor(slot.asUint()), slice), + sliced(wordFor(Raw.asUint(slot)), slice), ), }; @@ -273,7 +253,7 @@ describe("read (segment carry)", () => { storage: words, transient: { read: vitest.fn(async ({ slot, slice }) => - sliced(wordFor(slot.asUint()), slice), + sliced(wordFor(Raw.asUint(slot)), slice), ), }, } as unknown as Machine.State; @@ -281,26 +261,24 @@ describe("read (segment carry)", () => { options = { state }; }); - const bytes = (...runs: [number, number][]): Data => - Data.fromBytes( - new Uint8Array( - runs.flatMap(([byte, count]) => new Array(count).fill(byte)), - ), + const bytes = (...runs: [number, number][]): Raw => + new Uint8Array( + runs.flatMap(([byte, count]) => new Array(count).fill(byte)), ); it("treats offset ~wordsize as byte 0 of the next slot", async () => { const region: Cursor.Region = { location: "storage", - slot: Data.fromNumber(0), - offset: Data.fromNumber(32), - length: Data.fromNumber(4), + slot: Raw.fromNumber(0), + offset: Raw.fromNumber(32), + length: Raw.fromNumber(4), }; const result = await read(region, options); expect(options.state.storage.read).toHaveBeenCalledTimes(1); expect(options.state.storage.read).toHaveBeenCalledWith({ - slot: Data.fromNumber(1), + slot: Raw.fromNumber(1), slice: { offset: 0n, length: 4n }, }); expect(result).toEqual(bytes([0xa1, 4])); @@ -309,16 +287,16 @@ describe("read (segment carry)", () => { it("carries an offset beyond ~wordsize into a later slot", async () => { const region: Cursor.Region = { location: "storage", - slot: Data.fromNumber(5), - offset: Data.fromNumber(40), - length: Data.fromNumber(8), + slot: Raw.fromNumber(5), + offset: Raw.fromNumber(40), + length: Raw.fromNumber(8), }; const result = await read(region, options); expect(options.state.storage.read).toHaveBeenCalledTimes(1); expect(options.state.storage.read).toHaveBeenCalledWith({ - slot: Data.fromNumber(6), + slot: Raw.fromNumber(6), slice: { offset: 8n, length: 8n }, }); expect(result).toEqual(bytes([0xa6, 8])); @@ -327,20 +305,20 @@ describe("read (segment carry)", () => { it("concatenates a range that spans a slot boundary", async () => { const region: Cursor.Region = { location: "storage", - slot: Data.fromNumber(0), - offset: Data.fromNumber(28), - length: Data.fromNumber(8), + slot: Raw.fromNumber(0), + offset: Raw.fromNumber(28), + length: Raw.fromNumber(8), }; const result = await read(region, options); expect(options.state.storage.read).toHaveBeenCalledTimes(2); expect(options.state.storage.read).toHaveBeenNthCalledWith(1, { - slot: Data.fromNumber(0), + slot: Raw.fromNumber(0), slice: { offset: 28n, length: 4n }, }); expect(options.state.storage.read).toHaveBeenNthCalledWith(2, { - slot: Data.fromNumber(1), + slot: Raw.fromNumber(1), slice: { offset: 0n, length: 4n }, }); expect(result).toEqual(bytes([0xa0, 4], [0xa1, 4])); @@ -349,24 +327,24 @@ describe("read (segment carry)", () => { it("concatenates a range that spans three slots", async () => { const region: Cursor.Region = { location: "storage", - slot: Data.fromNumber(0), - offset: Data.fromNumber(16), - length: Data.fromNumber(64), + slot: Raw.fromNumber(0), + offset: Raw.fromNumber(16), + length: Raw.fromNumber(64), }; const result = await read(region, options); expect(options.state.storage.read).toHaveBeenCalledTimes(3); expect(options.state.storage.read).toHaveBeenNthCalledWith(1, { - slot: Data.fromNumber(0), + slot: Raw.fromNumber(0), slice: { offset: 16n, length: 16n }, }); expect(options.state.storage.read).toHaveBeenNthCalledWith(2, { - slot: Data.fromNumber(1), + slot: Raw.fromNumber(1), slice: { offset: 0n, length: 32n }, }); expect(options.state.storage.read).toHaveBeenNthCalledWith(3, { - slot: Data.fromNumber(2), + slot: Raw.fromNumber(2), slice: { offset: 0n, length: 16n }, }); expect(result).toEqual(bytes([0xa0, 16], [0xa1, 32], [0xa2, 16])); @@ -375,15 +353,15 @@ describe("read (segment carry)", () => { it("defaults length to the end of the slot it begins in", async () => { const region: Cursor.Region = { location: "storage", - slot: Data.fromNumber(0), - offset: Data.fromNumber(40), + slot: Raw.fromNumber(0), + offset: Raw.fromNumber(40), }; const result = await read(region, options); expect(options.state.storage.read).toHaveBeenCalledTimes(1); expect(options.state.storage.read).toHaveBeenCalledWith({ - slot: Data.fromNumber(1), + slot: Raw.fromNumber(1), slice: { offset: 8n, length: 24n }, }); expect(result).toEqual(bytes([0xa1, 24])); @@ -392,30 +370,30 @@ describe("read (segment carry)", () => { it("reads nothing for a zero-length segment", async () => { const region: Cursor.Region = { location: "storage", - slot: Data.fromNumber(0), - offset: Data.fromNumber(0), - length: Data.fromNumber(0), + slot: Raw.fromNumber(0), + offset: Raw.fromNumber(0), + length: Raw.fromNumber(0), }; const result = await read(region, options); expect(options.state.storage.read).not.toHaveBeenCalled(); - expect(result).toEqual(Data.zero()); + expect(result).toEqual(Raw.zero()); }); it("preserves the width of the given slot", async () => { - const slot = Data.fromHex(`0x${"00".repeat(31)}07`); + const slot = Raw.fromHex(`0x${"00".repeat(31)}07`); const region: Cursor.Region = { location: "storage", slot, - offset: Data.fromNumber(32), - length: Data.fromNumber(1), + offset: Raw.fromNumber(32), + length: Raw.fromNumber(1), }; await read(region, options); expect(options.state.storage.read).toHaveBeenCalledWith({ - slot: Data.fromHex(`0x${"00".repeat(31)}08`), + slot: Raw.fromHex(`0x${"00".repeat(31)}08`), slice: { offset: 0n, length: 1n }, }); }); @@ -423,9 +401,9 @@ describe("read (segment carry)", () => { it("applies carry to transient storage", async () => { const region: Cursor.Region = { location: "transient", - slot: Data.fromNumber(0), - offset: Data.fromNumber(30), - length: Data.fromNumber(4), + slot: Raw.fromNumber(0), + offset: Raw.fromNumber(30), + length: Raw.fromNumber(4), }; const result = await read(region, options); @@ -437,9 +415,9 @@ describe("read (segment carry)", () => { it("applies carry to stack depth", async () => { const region: Cursor.Region = { location: "stack", - slot: Data.fromNumber(2), - offset: Data.fromNumber(30), - length: Data.fromNumber(4), + slot: Raw.fromNumber(2), + offset: Raw.fromNumber(30), + length: Raw.fromNumber(4), }; const result = await read(region, options); @@ -457,19 +435,19 @@ describe("read (segment carry)", () => { }); it("reads the fragment of a virtual region", async () => { - const expression = Data.fromHex("0xdeadbeef"); + const expression = Raw.fromHex("0xdeadbeef"); expect( await read( { location: "virtual", expression, - offset: Data.fromNumber(1), - length: Data.fromNumber(2), + offset: Raw.fromNumber(1), + length: Raw.fromNumber(2), }, options, ), - ).toEqual(Data.fromHex("0xadbe")); + ).toEqual(Raw.fromHex("0xadbe")); expect(await read({ location: "virtual", expression }, options)).toEqual( expression, ); diff --git a/packages/pointers/src/read.ts b/packages/pointers/src/read.ts index e38bb028c5..b737e31f5b 100644 --- a/packages/pointers/src/read.ts +++ b/packages/pointers/src/read.ts @@ -1,6 +1,5 @@ import { Pointer } from "@ethdebug/format"; -import type { Machine } from "#machine"; -import { Data } from "#data"; +import { type Machine, Raw } from "@ethdebug/common"; import type { Cursor } from "#cursor"; export interface ReadOptions { @@ -10,7 +9,7 @@ export interface ReadOptions { export async function read( region: Cursor.Region, options: ReadOptions, -): Promise { +): Promise { const { location } = region; const { state } = options; @@ -91,7 +90,7 @@ export async function read( ); const end = length === undefined ? undefined : Number(offset + length); - return Data.fromBytes(region.expression.subarray(Number(offset), end)); + return region.expression.slice(Number(offset), end); } } } @@ -113,20 +112,20 @@ const wordsize = 32n; */ async function readSegment( { offset = 0n, length }: { offset?: bigint; length?: bigint }, - readWord: (carry: bigint, slice: Machine.State.Slice) => Promise, -): Promise { + readWord: (carry: bigint, slice: Machine.State.Slice) => Promise, +): Promise { const startCarry = offset / wordsize; const startByte = offset % wordsize; const totalLength = length ?? wordsize - startByte; if (totalLength === 0n) { - return Data.zero(); + return Raw.zero(); } const endByte = startByte + totalLength; const wordCount = (endByte + wordsize - 1n) / wordsize; - const words: Data[] = []; + const words: Raw[] = []; for (let index = 0n; index < wordCount; index++) { const from = index === 0n ? startByte : 0n; const to = index === wordCount - 1n ? endByte - index * wordsize : wordsize; @@ -139,19 +138,22 @@ async function readSegment( ); } - return Data.zero().concat(...words); + return Raw.concat(...words); } /** * Compute the slot `carry` slots after `slot`, keeping at least the width * of the given slot data. */ -function slotAfter(slot: Data, carry: bigint): Data { +function slotAfter(slot: Raw, carry: bigint): Raw { if (carry === 0n) { return slot; } - return Data.fromUint(slot.asUint() + carry).padUntilAtLeast(slot.length); + return Raw.padUntilAtLeast( + Raw.fromUint(Raw.asUint(slot) + carry), + slot.length, + ); } type DataProperties = { @@ -172,9 +174,9 @@ function withPropertiesAsUints< >(uintKeys: U[], region: Cursor.Region): PickDataPropertiesAsUints { const result: Partial> = {}; for (const key of uintKeys) { - const data: Data | undefined = region[key] as Data | undefined; + const data: Raw | undefined = region[key] as Raw | undefined; if (typeof data !== "undefined") { - result[key] = data.asUint(); + result[key] = Raw.asUint(data); } } diff --git a/packages/pointers/src/segment.examples.test.ts b/packages/pointers/src/segment.examples.test.ts index 834b5f6a75..af166e6a88 100644 --- a/packages/pointers/src/segment.examples.test.ts +++ b/packages/pointers/src/segment.examples.test.ts @@ -3,8 +3,7 @@ import { expect, describe, it } from "vitest"; import type { Pointer } from "@ethdebug/format"; import { schemas } from "@ethdebug/format"; -import type { Machine } from "#machine"; -import { Data } from "#data"; +import { type Machine, Raw } from "@ethdebug/common"; import { dereference } from "./dereference/index.js"; const { examples } = schemas[ @@ -31,23 +30,18 @@ const state = { slot, slice, }: { - slot: Data; + slot: Raw; slice?: Machine.State.Slice; }) => { - expect(slot).toEqual(Data.fromNumber(2)); - return Data.fromBytes( - slice - ? word.slice( - Number(slice.offset), - Number(slice.offset + slice.length), - ) - : word, - ); + expect(slot).toEqual(Raw.fromNumber(2)); + return slice + ? word.slice(Number(slice.offset), Number(slice.offset + slice.length)) + : word; }, }, } as unknown as Machine.State; -async function resolve(example: Record): Promise { +async function resolve(example: Record): Promise { const pointer = { location: "storage", ...example } as Pointer; const cursor = await dereference(pointer); const { regions, read } = await cursor.view(state); @@ -71,10 +65,10 @@ describe("segment schema examples (packed)", () => { it("count offsets from the most significant byte", async () => { const [literalAddress, literalCount] = packed; - expect(await resolve(literalAddress)).toEqual(Data.fromBytes(address)); - expect(await resolve(literalCount)).toEqual(Data.fromBytes(count)); + expect(await resolve(literalAddress)).toEqual(address); + expect(await resolve(literalCount)).toEqual(count); expect(await resolve({ slot: 2, offset: 0, length: 1 })).toEqual( - Data.fromBytes(new Uint8Array([0x00])), + new Uint8Array([0x00]), ); }); diff --git a/packages/pointers/test/deploy.ts b/packages/pointers/test/deploy.ts index 854a1beba7..9f5e7152ae 100644 --- a/packages/pointers/test/deploy.ts +++ b/packages/pointers/test/deploy.ts @@ -1,13 +1,13 @@ import type { EthereumProvider } from "ganache"; -import { Data } from "../src/data.js"; +import { Raw } from "@ethdebug/common"; export async function deployContract( - createBytecode: Data, + createBytecode: Raw, provider: EthereumProvider, ): Promise<{ - transactionHash: Data; - contractAddress: Data; + transactionHash: Raw; + contractAddress: Raw; }> { // just use the first unlocked account const [account] = await provider.request({ @@ -16,25 +16,25 @@ export async function deployContract( }); // issue a transaction that will be mined immediately - const transactionHash = Data.fromHex( + const transactionHash = Raw.fromHex( await provider.request({ method: "eth_sendTransaction", params: [ { from: account, gas: "0x989680", - data: createBytecode.toHex(), + data: Raw.toHex(createBytecode), }, ], }), ); // read the receipt and extract the deployed contract address - const contractAddress = Data.fromHex( + const contractAddress = Raw.fromHex( ( await provider.request({ method: "eth_getTransactionReceipt", - params: [transactionHash.toHex()], + params: [Raw.toHex(transactionHash)], }) ).contractAddress, ); diff --git a/packages/pointers/test/ganache.ts b/packages/pointers/test/ganache.ts index 4fd9b9a685..ccc2b9dd06 100644 --- a/packages/pointers/test/ganache.ts +++ b/packages/pointers/test/ganache.ts @@ -1,7 +1,6 @@ import type { EthereumProvider } from "ganache"; -import { Machine } from "../src/machine.js"; -import { Data } from "../src/data.js"; +import { type Machine, Raw } from "@ethdebug/common"; export async function loadGanache() { const originalWarn = console.warn; @@ -25,14 +24,14 @@ export async function loadGanache() { export function machineForProvider( provider: EthereumProvider, - transactionHash: Data, + transactionHash: Raw, ): Machine { return { trace(): AsyncIterable { return { async *[Symbol.asyncIterator]() { const structLogs = await requestStructLogs( - transactionHash.toHex(), + Raw.toHex(transactionHash), provider, ); @@ -83,7 +82,7 @@ function toMachineState(step: StructLog, index: number): Machine.State { } function constantUint(value: number): Promise { - return Promise.resolve(Data.fromNumber(value).asUint()); + return Promise.resolve(Raw.asUint(Raw.fromNumber(value))); } function makeStack(stack: StructLog["stack"]): Machine.State.Stack { @@ -94,26 +93,28 @@ function makeStack(stack: StructLog["stack"]): Machine.State.Stack { async peek({ depth, slice: { offset = 0n, length = 32n } = {} }) { const entry = stack.at(-Number(depth)); - const data = Data.fromHex(`0x${entry || ""}`); + const data = Raw.fromHex(`0x${entry || ""}`); const sliced = new Uint8Array(data).slice( Number(offset), Number(offset + length), ); - return new Data(sliced); + return new Uint8Array(sliced); }, }; } function makeBytes(words: StructLog["memory"]): Machine.State.Bytes { - const data = Data.fromHex(`0x${words.join("")}`); + const data = Raw.fromHex(`0x${words.join("")}`); return { length: constantUint(data.length), async read({ slice: { offset, length } }) { - return new Data(data.slice(Number(offset), Number(offset + length))); + return new Uint8Array( + data.slice(Number(offset), Number(offset + length)), + ); }, }; } @@ -122,13 +123,15 @@ function makeWords(slots: StructLog["storage"]): Machine.State.Words { return { async read({ slot, slice: { offset = 0n, length = 32n } = {} }) { const rawHex = - slots[slot.resizeTo(32).toHex().slice(2) as keyof typeof slots]; + slots[Raw.toHex(Raw.resizeTo(slot, 32)).slice(2) as keyof typeof slots]; // slots untouched by the transaction so far are absent from the // struct log; treat them as zero - const data = Data.fromHex(`0x${rawHex ?? "00".repeat(32)}`); + const data = Raw.fromHex(`0x${rawHex ?? "00".repeat(32)}`); - return new Data(data.slice(Number(offset), Number(offset + length))); + return new Uint8Array( + data.slice(Number(offset), Number(offset + length)), + ); }, }; } diff --git a/packages/pointers/test/observe.ts b/packages/pointers/test/observe.ts index bf85493154..7366862463 100644 --- a/packages/pointers/test/observe.ts +++ b/packages/pointers/test/observe.ts @@ -1,6 +1,7 @@ import type { Pointer } from "@ethdebug/format"; -import { type Machine, type Cursor, dereference } from "../src/index.js"; +import type { Machine } from "@ethdebug/common"; +import { type Cursor, dereference } from "../src/index.js"; import { loadGanache, machineForProvider } from "./ganache.js"; import { compileCreateBytecode, type CompileOptions } from "./solc.js"; diff --git a/packages/pointers/test/solc.ts b/packages/pointers/test/solc.ts index 824a8c2ee0..06584b78df 100644 --- a/packages/pointers/test/solc.ts +++ b/packages/pointers/test/solc.ts @@ -1,4 +1,4 @@ -import { Data } from "../src/data.js"; +import { Raw } from "@ethdebug/common"; import type * as Solc from "solc"; let solc: typeof Solc | undefined; @@ -32,7 +32,7 @@ export interface CompileOptions { export async function compileCreateBytecode({ sources, target, -}: CompileOptions): Promise { +}: CompileOptions): Promise { if (!solc) { throw new Error("Unable to load solc"); } @@ -67,7 +67,7 @@ export async function compileCreateBytecode({ evm: { bytecode: createBytecode }, } = output.contracts[target.path][target.contractName]; - return Data.fromHex(`0x${createBytecode.object}`); + return Raw.fromHex(`0x${createBytecode.object}`); } /** diff --git a/packages/pointers/test/test-cases.ts b/packages/pointers/test/test-cases.ts index 32d439286a..34c011bc22 100644 --- a/packages/pointers/test/test-cases.ts +++ b/packages/pointers/test/test-cases.ts @@ -3,7 +3,8 @@ import { findExamplePointer, type ObserveTraceOptions, } from "./index.js"; -import { type Cursor, Data } from "../src/index.js"; +import { Raw } from "@ethdebug/common"; +import type { Cursor } from "../src/index.js"; export interface ObserveTraceTest extends ObserveTraceOptions { expectedValues: V[]; @@ -61,11 +62,11 @@ const structStorageTest: ObserveTraceTest<{ ], async observe({ regions, read }) { - const x = Number((await read(regions.lookup["x"])).asUint()); + const x = Number(Raw.asUint(await read(regions.lookup["x"]))); - const y = Number((await read(regions.lookup["y"])).asUint()); + const y = Number(Raw.asUint(await read(regions.lookup["y"]))); - const salt = (await read(regions.lookup["salt"])).toHex(); + const salt = Raw.toHex(await read(regions.lookup["salt"])); return { x, y, salt }; }, @@ -110,7 +111,7 @@ const stringStorageTest: ObserveTraceTest = { const strings = regions.named("string"); // read each region and concatenate all the bytes - const stringData: Data = Data.zero().concat( + const stringData: Raw = Raw.concat( ...(await Promise.all(strings.map(read))), ); @@ -141,8 +142,8 @@ const multiSlotStringStorageTest: ObserveTraceTest = { // solc marks long strings by an odd length word; the example does not // model the short form, whose length word would decode as a huge length async shouldObserve(state) { - const lengthData = await state.storage.read({ slot: Data.zero() }); - const lengthWord = lengthData.asUint(); + const lengthData = await state.storage.read({ slot: Raw.zero() }); + const lengthWord = Raw.asUint(lengthData); return lengthWord === 0n || lengthWord % 2n === 1n; }, @@ -191,7 +192,7 @@ const uint256ArrayMemoryTest: ObserveTraceTest = { items.map(async (item) => { const data = await read(item); - return Number(data.asUint()); + return Number(Raw.asUint(data)); }), ); }, @@ -227,13 +228,13 @@ const uint256ArrayMemoryTest: ObserveTraceTest = { const arrayCount = await state.memory.read({ slice: { - offset: arrayOffset.asUint(), + offset: Raw.asUint(arrayOffset), length: 32n, }, }); // the example code only appends three times - return arrayCount.asUint() < 4n; + return Raw.asUint(arrayCount) < 4n; }, }; @@ -262,9 +263,9 @@ const virtualRegionsTest: ObserveTraceTest<{ x: number; tag: string }> = { ], async observe({ regions, read }) { - const x = Number((await read(regions.lookup["x"])).asUint()); + const x = Number(Raw.asUint(await read(regions.lookup["x"]))); - const tag = (await read(regions.lookup["tag"])).toHex(); + const tag = Raw.toHex(await read(regions.lookup["tag"])); return { x, tag }; }, diff --git a/packages/pointers/tsconfig.build.json b/packages/pointers/tsconfig.build.json index c40749e2a8..24cce8b490 100644 --- a/packages/pointers/tsconfig.build.json +++ b/packages/pointers/tsconfig.build.json @@ -10,5 +10,8 @@ "test/**", "bin/**" ], - "references": [{ "path": "../format/tsconfig.build.json" }] + "references": [ + { "path": "../common/tsconfig.build.json" }, + { "path": "../format/tsconfig.build.json" } + ] } diff --git a/packages/pointers/tsconfig.json b/packages/pointers/tsconfig.json index 367a372642..10fbc34366 100644 --- a/packages/pointers/tsconfig.json +++ b/packages/pointers/tsconfig.json @@ -6,9 +6,7 @@ "baseUrl": "./", "paths": { "#cursor": ["./src/cursor"], - "#data": ["./src/data"], "#evaluate": ["./src/evaluate"], - "#machine": ["./src/machine"], "#read": ["./src/read"], "#dereference": ["./src/dereference/index"], "#dereference/*": ["./src/dereference/*"], @@ -16,5 +14,5 @@ } }, "exclude": ["node_modules", "dist"], - "references": [{ "path": "../format" }] + "references": [{ "path": "../common" }, { "path": "../format" }] } diff --git a/packages/pointers/tsconfig.typecheck.json b/packages/pointers/tsconfig.typecheck.json index afe77567d1..d9f16c0882 100644 --- a/packages/pointers/tsconfig.typecheck.json +++ b/packages/pointers/tsconfig.typecheck.json @@ -6,6 +6,7 @@ "incremental": false, "rootDir": "../..", "paths": { + "@ethdebug/common": ["../common/src/index.ts"], "@ethdebug/format": ["../format/src/index.ts"] } } diff --git a/packages/programs-react/CHANGELOG.md b/packages/programs-react/CHANGELOG.md index 2e762fc2fa..b0178be5d8 100644 --- a/packages/programs-react/CHANGELOG.md +++ b/packages/programs-react/CHANGELOG.md @@ -9,6 +9,8 @@ root [`CHANGELOG.md`](../../CHANGELOG.md). ### Changed +- Trace state and region values are `Raw` values (a `Uint8Array`) from + `@ethdebug/common` in place of `Data` from `@ethdebug/pointers`. - The `react` and `react-dom` peer ranges now include React 19 (`^18.0.0 || ^19.0.0`) ([#374]). The components' return types now read `React.JSX.Element`, which both React 18 and 19 types define; diff --git a/packages/programs-react/package.json b/packages/programs-react/package.json index 61c0cfb630..4bfa1225da 100644 --- a/packages/programs-react/package.json +++ b/packages/programs-react/package.json @@ -50,6 +50,7 @@ "test": "vitest run" }, "dependencies": { + "@ethdebug/common": "^0.1.0-preview.2", "@ethdebug/format": "^0.1.0-draft.2", "@ethdebug/pointers": "^0.1.0-preview.2", "@shikijs/langs": "^2.5.0 || ^3.0.0", diff --git a/packages/programs-react/src/components/TraceContext.tsx b/packages/programs-react/src/components/TraceContext.tsx index 0f9aad8731..b72a7b91c6 100644 --- a/packages/programs-react/src/components/TraceContext.tsx +++ b/packages/programs-react/src/components/TraceContext.tsx @@ -12,7 +12,8 @@ import React, { useRef, } from "react"; import type { Pointer, Program } from "@ethdebug/format"; -import { dereference, Data } from "@ethdebug/pointers"; +import { Raw } from "@ethdebug/common"; +import { dereference } from "@ethdebug/pointers"; import { type TraceStep, type CallInfo, @@ -239,7 +240,7 @@ async function resolveVariableValue( const view = await cursor.view(state); // Collect values from all regions - const values: Data[] = []; + const values: Raw[] = []; for (const region of view.regions) { const data = await view.read(region); values.push(data); @@ -251,11 +252,11 @@ async function resolveVariableValue( // Single region: return its hex value if (values.length === 1) { - return values[0].toHex(); + return Raw.toHex(values[0]); } // Multiple regions: concatenate hex values - return values.map((d) => d.toHex()).join(", "); + return values.map((d) => Raw.toHex(d)).join(", "); } /** diff --git a/packages/programs-react/src/utils/traceState.ts b/packages/programs-react/src/utils/traceState.ts index a621413834..7511878535 100644 --- a/packages/programs-react/src/utils/traceState.ts +++ b/packages/programs-react/src/utils/traceState.ts @@ -6,7 +6,7 @@ * for pointer dereferencing. */ -import { type Machine, Data } from "@ethdebug/pointers"; +import { type Machine, Raw } from "@ethdebug/common"; import type { TraceStep } from "./mockTrace.js"; /** @@ -17,21 +17,21 @@ import type { TraceStep } from "./mockTrace.js"; * @returns A Machine.State backed by the step's data */ export function traceStepToMachineState(step: TraceStep): Machine.State { - // Build stack entries (Data objects, 32-byte padded) + // Build stack entries (Raw objects, 32-byte padded) const stackEntries = (step.stack || []).map((entry) => typeof entry === "string" - ? Data.fromHex(entry).padUntilAtLeast(32) - : Data.fromUint(entry).padUntilAtLeast(32), + ? Raw.padUntilAtLeast(Raw.fromHex(entry), 32) + : Raw.padUntilAtLeast(Raw.fromUint(entry), 32), ); // Parse memory from hex string - const memoryData = step.memory ? Data.fromHex(step.memory) : Data.zero(); + const memoryData = step.memory ? Raw.fromHex(step.memory) : Raw.zero(); // Build storage map (normalized 32-byte keys) - const storageMap = new Map(); + const storageMap = new Map(); for (const [slot, value] of Object.entries(step.storage || {})) { - const key = Data.fromHex(slot).padUntilAtLeast(32).toHex(); - storageMap.set(key, Data.fromHex(value).padUntilAtLeast(32)); + const key = Raw.toHex(Raw.padUntilAtLeast(Raw.fromHex(slot), 32)); + storageMap.set(key, Raw.padUntilAtLeast(Raw.fromHex(value), 32)); } const stack: Machine.State.Stack = { @@ -51,9 +51,7 @@ export function traceStepToMachineState(step: TraceStep): Machine.State { return entry; } const { offset, length } = slice; - return Data.fromBytes( - entry.slice(Number(offset), Number(offset + length)), - ); + return entry.slice(Number(offset), Number(offset + length)); }, }; @@ -61,22 +59,20 @@ export function traceStepToMachineState(step: TraceStep): Machine.State { const storage: Machine.State.Words = { async read({ slot, slice }) { - const key = slot.padUntilAtLeast(32).toHex(); - const value = storageMap.get(key) || Data.zero().padUntilAtLeast(32); + const key = Raw.toHex(Raw.padUntilAtLeast(slot, 32)); + const value = storageMap.get(key) || Raw.padUntilAtLeast(Raw.zero(), 32); if (!slice) { return value; } const { offset, length } = slice; - return Data.fromBytes( - value.slice(Number(offset), Number(offset + length)), - ); + return value.slice(Number(offset), Number(offset + length)); }, }; // Returndata from the step, if available const returndataData = step.returndata - ? Data.fromHex(step.returndata) - : Data.zero(); + ? Raw.fromHex(step.returndata) + : Raw.zero(); return { get traceIndex() { @@ -91,17 +87,17 @@ export function traceStepToMachineState(step: TraceStep): Machine.State { stack, memory, storage, - calldata: makeBytesReader(Data.zero()), + calldata: makeBytesReader(Raw.zero()), returndata: makeBytesReader(returndataData), - code: makeBytesReader(Data.zero()), + code: makeBytesReader(Raw.zero()), transient: makeEmptyWordsReader(), }; } /** - * Create a Machine.State.Bytes reader from a Data buffer. + * Create a Machine.State.Bytes reader from a Raw buffer. */ -function makeBytesReader(data: Data): Machine.State.Bytes { +function makeBytesReader(data: Raw): Machine.State.Bytes { return { get length() { return Promise.resolve(BigInt(data.length)); @@ -117,9 +113,9 @@ function makeBytesReader(data: Data): Machine.State.Bytes { if (available > 0 && start < data.length) { result.set(data.slice(start, start + available), 0); } - return Data.fromBytes(result); + return result; } - return Data.fromBytes(data.slice(start, end)); + return data.slice(start, end); }, }; } @@ -131,14 +127,12 @@ function makeBytesReader(data: Data): Machine.State.Bytes { function makeEmptyWordsReader(): Machine.State.Words { return { async read({ slice }) { - const value = Data.zero().padUntilAtLeast(32); + const value = Raw.padUntilAtLeast(Raw.zero(), 32); if (!slice) { return value; } const { offset, length } = slice; - return Data.fromBytes( - value.slice(Number(offset), Number(offset + length)), - ); + return value.slice(Number(offset), Number(offset + length)); }, }; } diff --git a/packages/programs-react/tsconfig.typecheck.json b/packages/programs-react/tsconfig.typecheck.json index 6e118cf769..36bfa2a097 100644 --- a/packages/programs-react/tsconfig.typecheck.json +++ b/packages/programs-react/tsconfig.typecheck.json @@ -6,6 +6,7 @@ "incremental": false, "rootDir": "../..", "paths": { + "@ethdebug/common": ["../common/src/index.ts"], "@ethdebug/format": ["../format/src/index.ts"], "@ethdebug/pointers": ["../pointers/src/index.ts"] } diff --git a/packages/web/docs/implementation-guides/building-a-trace-viewer.mdx b/packages/web/docs/implementation-guides/building-a-trace-viewer.mdx index 5359c0292b..4a3a944d34 100644 --- a/packages/web/docs/implementation-guides/building-a-trace-viewer.mdx +++ b/packages/web/docs/implementation-guides/building-a-trace-viewer.mdx @@ -52,14 +52,16 @@ const value = await view.read(view.regions[0]); Interpret raw bytes according to type: ```typescript -function decodeValue(bytes: Data, type: Type): string { +import { Raw } from "@ethdebug/common"; + +function decodeValue(bytes: Raw, type: Type): string { switch (type.kind) { case "uint": - return bytes.asUint().toString(); + return Raw.asUint(bytes).toString(); case "bool": - return bytes.asUint() !== 0n ? "true" : "false"; + return Raw.asUint(bytes) !== 0n ? "true" : "false"; case "address": - return "0x" + bytes.toHex().slice(-40); + return "0x" + Raw.toHex(bytes).slice(-40); // ... other types } } diff --git a/packages/web/docs/implementation-guides/pointers/dereference-logic/making-regions-concrete.mdx b/packages/web/docs/implementation-guides/pointers/dereference-logic/making-regions-concrete.mdx index eebe0dfcfb..3d50d27342 100644 --- a/packages/web/docs/implementation-guides/pointers/dereference-logic/making-regions-concrete.mdx +++ b/packages/web/docs/implementation-guides/pointers/dereference-logic/making-regions-concrete.mdx @@ -10,7 +10,7 @@ import SchemaExample from "@site/src/components/SchemaExample"; There are two main aspects involved when converting from a `Pointer.Region`, which is full of properties whose values are the dynamic `Pointer.Expression` objects, into a `Cursor.Region`, whose expression properties have been replaced -with actual bytes `Data`: +with actual bytes (`Raw` values): ## Fixing stack-located regions' `slot` offset @@ -30,7 +30,7 @@ This behavior is encapsulated by the `adjustStackLength` function: The more substantial aspect of making a region concrete, however, is the process by which this implementation evaluates each of the `Pointer.Region`'s -expression properties and converts them into their `Data` values. +expression properties and converts them into their `Raw` byte values. This process would be very straightforward, except that pointer expressions may reference the region in which they are specified by use of the special diff --git a/packages/web/docs/implementation-guides/pointers/evaluating-expressions.mdx b/packages/web/docs/implementation-guides/pointers/evaluating-expressions.mdx index cd639362c0..f237209bf8 100644 --- a/packages/web/docs/implementation-guides/pointers/evaluating-expressions.mdx +++ b/packages/web/docs/implementation-guides/pointers/evaluating-expressions.mdx @@ -137,8 +137,8 @@ This schema provides the `{ "~sized": }` and subexpression. A resize always produces bytes of the requested width, and so is the way to give an integer a width; this implementation encodes an integer as its minimal big-endian bytes and then uses the -[`Data.prototype.resizeTo()`](/docs/implementation-guides/pointers/types/data-and-machines) -method for both sorts. +[`Raw.resizeTo()`](/docs/implementation-guides/pointers/types/data-and-machines) +function for both sorts. ` method for reading +- A `read(region: Cursor.Region): Promise` method for reading bytes from the machine **Importantly**, a `Cursor.Region` is a fully-evaluated diff --git a/packages/web/docs/implementation-guides/pointers/types/data-and-machines.mdx b/packages/web/docs/implementation-guides/pointers/types/data-and-machines.mdx index 4f0c12bb85..264d93812d 100644 --- a/packages/web/docs/implementation-guides/pointers/types/data-and-machines.mdx +++ b/packages/web/docs/implementation-guides/pointers/types/data-and-machines.mdx @@ -4,20 +4,23 @@ sidebar_position: 3 import CodeListing from "@site/src/components/CodeListing"; -# Data and machines +# Raw bytes and machines -The **@ethdebug/pointers** package includes two abstractions that it uses for -representing low-level concerns: +The **@ethdebug/pointers** package uses two abstractions for low-level +concerns. Both come from the **@ethdebug/common** package, which holds the +runtime code that the ethdebug packages share: -- `class Data` extends JavaScript's `Uint8Array` to represent sequences of - bytes and allow conversion to/from different formats (like hex strings) +- `Raw` represents a sequence of bytes. It is a plain `Uint8Array` type, + together with a namespace of functions that convert to/from other formats + (like hex strings and `bigint`s), for example `Raw.toHex(raw)` and + `Raw.fromUint(value)`. - `interface Machine` defines an asynchronous API to model a running EVM. It includes the sole method `trace(): AsyncIterable`, where the `Machine.State` type represents point-in-time access to a running EVM at a particular program counter in a particular execution context, etc. -## Data +## Raw :::tip Note how this implementation handles the conversion to/from JavaScript's @@ -29,9 +32,9 @@ When implementing this functionality, be careful not to get this wrong. :::
-Code listing for `src/data.ts` +Code listing for `src/raw.ts` - +
@@ -40,6 +43,6 @@ When implementing this functionality, be careful not to get this wrong.
Code listing for `src/machine.ts` - +
diff --git a/packages/web/docs/implementation-guides/pointers/types/types.mdx b/packages/web/docs/implementation-guides/pointers/types/types.mdx index d71b1c5d6d..fa5500480c 100644 --- a/packages/web/docs/implementation-guides/pointers/types/types.mdx +++ b/packages/web/docs/implementation-guides/pointers/types/types.mdx @@ -12,9 +12,9 @@ the rest of the implementation makes heavy use of them: model the **ethdebug/format/pointer** JSON Schema as TypeScript types (including corresponding type guards) -- The [Data and machines](/docs/implementation-guides/pointers/types/data-and-machines) page - covers low-level concerns of handling raw bytes and interfacing with - running EVMs. +- The [Raw bytes and machines](/docs/implementation-guides/pointers/types/data-and-machines) + page covers low-level concerns of handling raw bytes and interfacing with + running EVMs, using code from the **@ethdebug/common** package. - [Cursors](/docs/implementation-guides/pointers/types/cursors) are the result of dereferencing a pointer; they accept a machine state and produce diff --git a/packages/web/docusaurus.config.ts b/packages/web/docusaurus.config.ts index 7218db98cd..0f11245403 100644 --- a/packages/web/docusaurus.config.ts +++ b/packages/web/docusaurus.config.ts @@ -90,6 +90,12 @@ const config: Config = { "../format/tsconfig.json", ), }, + "@ethdebug/common": { + tsConfigFilePath: path.resolve( + __dirname, + "../common/tsconfig.json", + ), + }, "@ethdebug/pointers": { tsConfigFilePath: path.resolve( __dirname, diff --git a/packages/web/package.json b/packages/web/package.json index 495fc04294..a30f45705b 100644 --- a/packages/web/package.json +++ b/packages/web/package.json @@ -22,6 +22,7 @@ "@docusaurus/types": "^3.9.2", "@ethdebug/bugc": "^0.1.0-preview.2", "@ethdebug/bugc-react": "^0.1.0-preview.2", + "@ethdebug/common": "^0.1.0-preview.2", "@ethdebug/evm": "^0.1.0-preview.2", "@ethdebug/format": "^0.1.0-draft.2", "@ethdebug/pointers": "^0.1.0-preview.2", diff --git a/packages/web/src/theme/ProgramExample/TraceDrawer.tsx b/packages/web/src/theme/ProgramExample/TraceDrawer.tsx index 5b537b2b76..affcd27777 100644 --- a/packages/web/src/theme/ProgramExample/TraceDrawer.tsx +++ b/packages/web/src/theme/ProgramExample/TraceDrawer.tsx @@ -29,7 +29,8 @@ import { type TraceStep as EvmStep, } from "@ethdebug/evm"; import type { Pointer } from "@ethdebug/format"; -import { dereference, Data, type Machine } from "@ethdebug/pointers"; +import { type Machine, Raw } from "@ethdebug/common"; +import { dereference } from "@ethdebug/pointers"; import { storageByStep } from "./storageByStep"; import { buildCallStack, @@ -1348,15 +1349,15 @@ function traceStepToState( storage: Record, ): Machine.State { const stackEntries = step.stack.map((v) => - Data.fromUint(v).padUntilAtLeast(32), + Raw.padUntilAtLeast(Raw.fromUint(v), 32), ); - const memoryData = Data.fromBytes(step.memory); + const memoryData = step.memory; - const storageMap = new Map(); + const storageMap = new Map(); for (const [slot, value] of Object.entries(storage)) { - const key = Data.fromHex(slot).padUntilAtLeast(32).toHex(); - storageMap.set(key, Data.fromHex(value).padUntilAtLeast(32)); + const key = Raw.toHex(Raw.padUntilAtLeast(Raw.fromHex(slot), 32)); + storageMap.set(key, Raw.padUntilAtLeast(Raw.fromHex(value), 32)); } const stack: Machine.State.Stack = { @@ -1371,13 +1372,11 @@ function traceStepToState( const entry = stackEntries[index]; if (!slice) return entry; const { offset, length } = slice; - return Data.fromBytes( - entry.slice(Number(offset), Number(offset + length)), - ); + return entry.slice(Number(offset), Number(offset + length)); }, }; - const makeBytesReader = (data: Data): Machine.State.Bytes => ({ + const makeBytesReader = (data: Raw): Machine.State.Bytes => ({ get length() { return Promise.resolve(BigInt(data.length)); }, @@ -1391,32 +1390,28 @@ function traceStepToState( if (available > 0 && start < data.length) { result.set(data.slice(start, start + available), 0); } - return Data.fromBytes(result); + return result; } - return Data.fromBytes(data.slice(start, end)); + return data.slice(start, end); }, }); const storageReader: Machine.State.Words = { async read({ slot, slice }) { - const key = slot.padUntilAtLeast(32).toHex(); - const value = storageMap.get(key) || Data.zero().padUntilAtLeast(32); + const key = Raw.toHex(Raw.padUntilAtLeast(slot, 32)); + const value = storageMap.get(key) || Raw.padUntilAtLeast(Raw.zero(), 32); if (!slice) return value; const { offset, length } = slice; - return Data.fromBytes( - value.slice(Number(offset), Number(offset + length)), - ); + return value.slice(Number(offset), Number(offset + length)); }, }; const emptyWords: Machine.State.Words = { async read({ slice }) { - const value = Data.zero().padUntilAtLeast(32); + const value = Raw.padUntilAtLeast(Raw.zero(), 32); if (!slice) return value; const { offset, length } = slice; - return Data.fromBytes( - value.slice(Number(offset), Number(offset + length)), - ); + return value.slice(Number(offset), Number(offset + length)); }, }; @@ -1433,9 +1428,9 @@ function traceStepToState( stack, memory: makeBytesReader(memoryData), storage: storageReader, - calldata: makeBytesReader(Data.zero()), - returndata: makeBytesReader(Data.zero()), - code: makeBytesReader(Data.zero()), + calldata: makeBytesReader(Raw.zero()), + returndata: makeBytesReader(Raw.zero()), + code: makeBytesReader(Raw.zero()), transient: emptyWords, }; } @@ -1454,14 +1449,14 @@ async function resolvePointer( ); const view = await cursor.view(state); - const values: Data[] = []; + const values: Raw[] = []; for (const region of view.regions) { values.push(await view.read(region)); } if (values.length === 0) return "0x"; - if (values.length === 1) return values[0].toHex(); - return values.map((d) => d.toHex()).join(", "); + if (values.length === 1) return Raw.toHex(values[0]); + return values.map((d) => Raw.toHex(d)).join(", "); } interface ResolvedArg { diff --git a/schemas/type/elementary/fixed.schema.yaml b/schemas/type/elementary/fixed.schema.yaml index 5792600312..0fe866a2b3 100644 --- a/schemas/type/elementary/fixed.schema.yaml +++ b/schemas/type/elementary/fixed.schema.yaml @@ -18,8 +18,8 @@ properties: places: type: integer description: - How many decimal places, implying that a raw value `v` of this type - should be interpreted as `v / (10**places)` + How many decimal places, implying that an unscaled value `v` of this + type should be interpreted as `v / (10**places)` minimum: 0 maximum: 80 required: diff --git a/schemas/type/elementary/ufixed.schema.yaml b/schemas/type/elementary/ufixed.schema.yaml index f433214101..3bfb36af30 100644 --- a/schemas/type/elementary/ufixed.schema.yaml +++ b/schemas/type/elementary/ufixed.schema.yaml @@ -18,8 +18,8 @@ properties: places: type: integer description: - How many decimal places, implying that a raw value `v` of this type - should be interpreted as `v / (10**places)` + How many decimal places, implying that an unscaled value `v` of this + type should be interpreted as `v / (10**places)` minimum: 0 maximum: 80 required: