Implement @ethdebug/pointers TypeScript package to serve as debugger-side reference implementation of ethdebug/format pointers

bin/start

@@ -8,8 +8,9 @@ else
 fi
 
 # Run the commands with concurrently
-concurrently --names=format,web,jest \
+concurrently --names=format,pointers,web,jest \
  "cd ./packages/format && yarn watch" \
+ "cd ./packages/pointers && yarn watch" \
  "cd ./packages/web && yarn start $NO_OPEN_FLAG" \
  "yarn test --watchAll"
 

packages/pointers/.gitignore

@@ -0,0 +1,2 @@
+node_modules
+dist

packages/pointers/README.md

@@ -0,0 +1,7 @@
+# @ethdebug/pointers
+
+_This NPM package contains a reference implementation for dereferencing
+**ethdebug/format** [pointers](https://ethdebug.github.io/format/spec/pointer/overview)._
+
+:warning: This package is currently unpublished until ethdebug/format is more
+complete.

packages/pointers/jest.config.cjs

@@ -0,0 +1,21 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+ preset: "ts-jest",
+ testEnvironment: "node",
+ extensionsToTreatAsEsm: [".ts"],
+ moduleFileExtensions: ["ts", "js"],
+ moduleNameMapper: {
+ '^(\\.{1,2}/.*)\\.js$': '$1',
+ },
+ modulePathIgnorePatterns: ["<rootDir>/dist/"],
+ transform: {
+ // '^.+\\.[tj]sx?$' to process js/ts with `ts-jest`
+ // '^.+\\.m?[tj]sx?$' to process js/ts/mjs/mts with `ts-jest`
+ '^.+\\.tsx?$': [
+ 'ts-jest',
+ {
+ useESM: true,
+ },
+ ],
+ },
+};

packages/pointers/package.json

@@ -0,0 +1,28 @@
+{
+ "name": "@ethdebug/pointers",
+ "version": "0.1.0-0",
+ "description": "Reference implementation for ethdebug/format pointers",
+ "main": "dist/src/index.js",
+ "type": "module",
+ "license": "MIT",
+ "scripts": {
+ "prepare": "tsc",
+ "watch": "yarn prepare --watch",
+ "test": "node --experimental-vm-modules $(yarn bin jest)"
+ },
+ "devDependencies": {
+ "@ethdebug/format": "^0.1.0-0",
+ "@jest/globals": "^29.7.0",
+ "chalk": "^5.3.0",
+ "cli-highlight": "^2.1.11",
+ "ganache": "7.9.x",
+ "jest": "^29.7.0",
+ "solc": "^0.8.26",
+ "ts-jest": "^29.1.1",
+ "ts-node": "^10.9.2",
+ "typescript": "^5.3.3"
+ },
+ "dependencies": {
+ "ethereum-cryptography": "^2.1.3"
+ }
+}

packages/pointers/src/cursor.ts

@@ -0,0 +1,71 @@
+import type { Machine } from "./machine.js";
+import type { Pointer } from "./pointer.js";
+import type { Data } from "./data.js";
+
+/**
+ * The result of dereferencing a pointer
+ */
+export interface Cursor {
+ view(state: Machine.State): Promise<Cursor.View>;
+}
+
+export namespace Cursor {
+ /**
+ * The result of viewing a Cursor with a given Machine.State
+ */
+ export interface View {
+ /**
+ * A collection of concrete Cursor.Regions; this is a plain array of
+ * regions and also provides filtering/lookup of regions by name
+ * (according to the scoping rules outlined in the specification)
+ */
+ regions: Cursor.Regions;
+
+ /**
+ * Read bytes from the machine state corresponding to the bytes range
+ * for a particular concrete Cursor.Region
+ */
+ read(region: Cursor.Region): Promise<Data>;
+ }
+
+ /**
+ * A Pointer region where all dynamic expressions have been replaced with
+ * concrete bytes values.
+ */
+ export type Region<R extends Pointer.Region = Pointer.Region> = {
+ [K in keyof R]: K extends "slot" | "offset" | "length"
+ ? R[K] extends Pointer.Expression
+ ? Data
+ : R[K] extends Pointer.Expression | undefined
+ ? Data | undefined
+ : R[K]
+ : R[K];
+ }
+
+ /**
+ * A collection of concrete regions.
+ *
+ * This collection serves as a plain array of regions, for simple iteration
+ * and whatever filtering.
+ *
+ * It also provides a couple interfaces of its own for accessing regions by
+ * name.
+ */
+ export type Regions =
+ & Cursor.Region[]
+ & {
+ /**
+ * Obtain an ordered list of all regions with a particular name.
+ *
+ * This is useful, e.g., when looking to concatenate a series of
+ * sequential regions that were generated by index from a list
+ * collection
+ */
+ named(name: string): Cursor.Region[];
+
+ /**
+ * Retrieve the last concrete region generated with a particular name
+ */
+ lookup: { [name: string]: Cursor.Region };
+ };
+}

packages/pointers/src/data.test.ts

@@ -0,0 +1,62 @@
+import { expect, describe, it } from "@jest/globals";
+
+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.");
+ });
+ });
+});

packages/pointers/src/data.ts

@@ -0,0 +1,61 @@
+import { toHex } from "ethereum-cryptography/utils";
+
+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 - 1);
+ 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)}`;
+ }
+}

packages/pointers/src/dereference/cursor.ts

@@ -0,0 +1,75 @@
+import type { Machine } from "../machine.js";
+import type { Cursor } from "../cursor.js";
+import { read } from "../read.js";
+
+export function createCursor(
+ simpleCursor: (state: Machine.State) => AsyncIterable<Cursor.Region>
+): Cursor {
+ return {
+ async view(state: Machine.State) {
+ const list = [];
+ for await (const region of simpleCursor(state)) {
+ list.push(region);
+ }
+
+ const named: { [name: string]: Cursor.Region[] } = {};
+ const current: { [name: string]: Cursor.Region } = {};
+
+ const propertyFlags = {
+ writable: false,
+ enumerable: false,
+ configurable: false
+ } as const;
+
+ const regions: Cursor.Regions = Object.create(Array.prototype, {
+ length: {
+ value: list.length,
+ ...propertyFlags
+ }
+ });
+
+ for (const [index, region] of list.entries()) {
+ Object.defineProperty(regions, index, {
+ value: region,
+ ...propertyFlags,
+ enumerable: true,
+ });
+
+ if (typeof region.name === "string") {
+ if (!(region.name in named)) {
+ named[region.name] = [];
+ }
+ named[region.name].push(region);
+ current[region.name] = region;
+ }
+ }
+
+ for (const [name, region] of Object.entries(current)) {
+ Object.defineProperty(regions, name, {
+ value: region,
+ ...propertyFlags
+ });
+ }
+
+ Object.defineProperties(regions, {
+ named: {
+ value: (name: string) => named[name] || [],
+ ...propertyFlags
+ },
+ lookup: {
+ value: {
+ ...current
+ },
+ ...propertyFlags
+ }
+ });
+
+ return {
+ regions,
+ async read(region: Cursor.Region) {
+ return await read(region, { state });
+ }
+ };
+ }
+ };
+}