@quentinadam/evm-base 0.1.0

package/src/ABI.ts

@@ -0,0 +1,434 @@
+import assert from '@quentinadam/assert';
+import * as Uint8ArrayExtension from '@quentinadam/uint8array-extension';
+import keccak256 from '@quentinadam/hash/keccak256';
+import ensure from '@quentinadam/ensure';
+
+abstract class Element {
+  readonly encodedLength: number | undefined;
+
+  constructor(encodedLength: number | undefined) {
+    this.encodedLength = encodedLength;
+  }
+
+  get dynamic(): boolean {
+    return this.encodedLength === undefined;
+  }
+
+  abstract encode(value: unknown): Uint8Array<ArrayBuffer>;
+
+  abstract decode(bytes: Uint8Array<ArrayBuffer>): unknown;
+}
+
+class IntElement extends Element {
+  readonly bits;
+
+  constructor(bits: number) {
+    super(32);
+    assert(Number.isSafeInteger(bits), 'Bits must be an integer');
+    assert(bits % 8 === 0, 'Bits must be a multiple of 8');
+    assert(bits >= 8 && bits <= 256, 'Bits must be between 8 and 256');
+    this.bits = bits;
+  }
+
+  override encode(value: unknown) {
+    assert(typeof value === 'number' || typeof value === 'bigint', 'Value must be a number or a bigint');
+    return ((value) => {
+      if (typeof value === 'number') {
+        assert(Number.isSafeInteger(value), 'Value must be a safe integer');
+        value = BigInt(value);
+      }
+      return Uint8ArrayExtension.fromIntBE(value, 32);
+    })(value);
+  }
+
+  override decode(bytes: Uint8Array<ArrayBuffer>) {
+    assert(bytes.length >= 32);
+    const value = Uint8ArrayExtension.toBigUintBE(bytes.slice(0, 32));
+    return (value >= (1n << 255n)) ? value - (1n << 256n) : value;
+  }
+}
+
+class UintElement extends Element {
+  readonly bits;
+
+  constructor(bits: number) {
+    super(32);
+    assert(Number.isSafeInteger(bits), 'Bits must be an integer');
+    assert(bits % 8 === 0, 'Bits must be a multiple of 8');
+    assert(bits >= 8 && bits <= 256, 'Bits must be between 8 and 256');
+    this.bits = bits;
+  }
+
+  override encode(value: unknown) {
+    assert(typeof value === 'number' || typeof value === 'bigint', 'Value must be a number or a bigint');
+    return ((value) => {
+      if (typeof value === 'number') {
+        assert(Number.isSafeInteger(value), 'Value must be a safe integer');
+        value = BigInt(value);
+      }
+      return Uint8ArrayExtension.fromUintBE(value, 32);
+    })(value);
+  }
+
+  override decode(bytes: Uint8Array<ArrayBuffer>) {
+    assert(bytes.length >= 32);
+    return Uint8ArrayExtension.toBigUintBE(bytes.slice(0, 32));
+  }
+}
+
+class BoolElement extends Element {
+  constructor() {
+    super(32);
+  }
+
+  override encode(value: unknown) {
+    assert(typeof value === 'boolean', 'Value must be a boolean');
+    return ((value) => {
+      return Uint8ArrayExtension.fromUintBE(value ? 1 : 0, 32);
+    })(value);
+  }
+
+  override decode(bytes: Uint8Array<ArrayBuffer>) {
+    assert(bytes.length >= 32);
+    const value = Uint8ArrayExtension.toBigUintBE(bytes.slice(0, 32));
+    if (value === 0n) {
+      return false;
+    } else {
+      assert(value === 1n);
+      return true;
+    }
+  }
+}
+
+abstract class AddressElement extends Element {
+  abstract bytesFromAddress(address: string): Uint8Array<ArrayBuffer>;
+  abstract addressFromBytes(bytes: Uint8Array<ArrayBuffer>): string;
+
+  constructor() {
+    super(32);
+  }
+
+  override encode(value: unknown) {
+    assert(typeof value === 'string', 'Value must be a string');
+    const bytes = this.bytesFromAddress(value);
+    assert(bytes.length === 20, 'Buffer must be 20 bytes long');
+    return Uint8ArrayExtension.padStart(bytes, 32);
+  }
+
+  override decode(bytes: Uint8Array<ArrayBuffer>) {
+    assert(bytes.length >= 32);
+    assert(bytes.slice(0, 12).every((byte) => byte === 0), 'First 12 bytes must be zero');
+    return this.addressFromBytes(bytes.slice(12, 32));
+  }
+}
+
+class StringElement extends Element {
+  constructor() {
+    super(undefined);
+  }
+
+  override encode(value: unknown) {
+    assert(typeof value === 'string', 'Value must be a string');
+    let bytes = new TextEncoder().encode(value);
+    const length = bytes.length;
+    bytes = padEnd(bytes);
+    return Uint8ArrayExtension.concat([Uint8ArrayExtension.fromUintBE(length, 32), bytes]);
+  }
+
+  override decode(bytes: Uint8Array<ArrayBuffer>) {
+    assert(bytes.length >= 32);
+    const length = Number(Uint8ArrayExtension.toBigUintBE(bytes.slice(0, 32)));
+    assert(bytes.length >= 32 + padLength(length));
+    return new TextDecoder().decode(bytes.slice(32, 32 + length));
+  }
+}
+
+class BytesElement extends Element {
+  readonly length;
+
+  constructor(length?: number) {
+    super(length === undefined ? undefined : 32);
+    if (length !== undefined) {
+      assert(Number.isSafeInteger(length), 'Length must be an integer');
+      assert(length >= 1 && length <= 32, 'Length must be between 1 and 32');
+    }
+    this.length = length;
+  }
+
+  #encode(bytes: Uint8Array<ArrayBuffer>) {
+    const length = bytes.length;
+    bytes = padEnd(bytes);
+    if (this.length !== undefined) {
+      return bytes;
+    } else {
+      return Uint8ArrayExtension.concat([Uint8ArrayExtension.fromUintBE(length, 32), bytes]);
+    }
+  }
+
+  override encode(value: unknown) {
+    if (typeof value === 'string') {
+      const match = value.match(/^(?:0x)?(?<hex>(?:[0-9a-f][0-9a-f])*)$/i);
+      if (match !== null) {
+        return this.#encode(Uint8Array.fromHex(ensure(ensure(match.groups).hex)));
+      }
+    }
+    if (value instanceof Uint8Array && Uint8ArrayExtension.isArrayBufferBacked(value)) {
+      return this.#encode(value);
+    }
+    throw new Error('Value must be a hex string or a Uint8Array<ArrayBuffer>');
+  }
+
+  override decode(bytes: Uint8Array<ArrayBuffer>) {
+    assert(bytes.length >= 32);
+    if (this.length !== undefined) {
+      return bytes.slice(0, this.length);
+    } else {
+      const length = Number(Uint8ArrayExtension.toBigUintBE(bytes.slice(0, 32)));
+      assert(bytes.length >= 32 + padLength(length));
+      return bytes.slice(32, 32 + length);
+    }
+  }
+}
+
+function padLength(length: number) {
+  return length + (32 - length % 32) % 32;
+}
+
+function padEnd(bytes: Uint8Array<ArrayBuffer>) {
+  return Uint8ArrayExtension.padEnd(bytes, padLength(bytes.length));
+}
+
+class StructElement extends Element {
+  readonly elements;
+
+  constructor(elements: Element[]) {
+    super((() => {
+      let encodedLength = 0;
+      for (const element of elements) {
+        if (element.encodedLength === undefined) {
+          return undefined;
+        }
+        encodedLength += element.encodedLength;
+      }
+      return encodedLength;
+    })());
+    this.elements = elements;
+  }
+
+  override encode(value: unknown) {
+    assert(Array.isArray(value), 'Value must be an array');
+    return encode({ elements: this.elements, values: value });
+  }
+
+  override decode(bytes: Uint8Array<ArrayBuffer>) {
+    let offset = 0;
+    return this.elements.map((element) => {
+      const encodedLength = element.encodedLength;
+      if (encodedLength === undefined) {
+        const _offset = Number(Uint8ArrayExtension.toBigUintBE(bytes.slice(offset, offset + 32)));
+        const value = element.decode(bytes.slice(_offset));
+        offset += 32;
+        return value;
+      } else {
+        const value = element.decode(bytes.slice(offset));
+        offset += encodedLength;
+        return value;
+      }
+    });
+  }
+}
+
+function encode({ elements, values }: { elements: Element[]; values: unknown[] }) {
+  assert(values.length === elements.length, 'Array length must match');
+  return ((elements) => {
+    let offset = 0;
+    for (const { dynamic, encodedValue } of elements) {
+      if (dynamic) {
+        offset += 32;
+      } else {
+        offset += encodedValue.length;
+      }
+    }
+    const heads = new Array<Uint8Array<ArrayBuffer>>();
+    const tails = new Array<Uint8Array<ArrayBuffer>>();
+    for (const { dynamic, encodedValue } of elements) {
+      if (dynamic) {
+        heads.push(Uint8ArrayExtension.fromUintBE(offset, 32));
+        tails.push(encodedValue);
+        offset += encodedValue.length;
+      } else {
+        heads.push(encodedValue);
+      }
+    }
+    return Uint8ArrayExtension.concat([...heads, ...tails]);
+  })(elements.map((element, index) => {
+    const value = values[index];
+    const encodedValue = element.encode(value);
+    return { dynamic: element.dynamic, encodedValue };
+  }));
+}
+
+class ArrayElement extends Element {
+  readonly element;
+  readonly length;
+
+  constructor(element: Element, length?: number) {
+    super(length === undefined || element.encodedLength === undefined ? undefined : element.encodedLength * length);
+    this.element = element;
+    this.length = length;
+  }
+
+  override encode(values: unknown) {
+    assert(Array.isArray(values), 'Value must be an array');
+    const encodedValue = encode({ elements: new Array(values.length).fill(this.element), values });
+    if (this.length !== undefined) {
+      assert(values.length === this.length, 'Array length must match');
+      return encodedValue;
+    } else {
+      return Uint8ArrayExtension.concat([Uint8ArrayExtension.fromUintBE(values.length, 32), encodedValue]);
+    }
+  }
+
+  override decode(bytes: Uint8Array<ArrayBuffer>) {
+    const { length, dataOffset } = (() => {
+      if (this.length === undefined) {
+        // Dynamic array: read length from first 32 bytes
+        assert(bytes.length >= 32);
+        return { length: Number(Uint8ArrayExtension.toBigUintBE(bytes.slice(0, 32))), dataOffset: 32 };
+      } else {
+        // Fixed array: use predefined length, no length prefix
+        return { length: this.length, dataOffset: 0 };
+      }
+    })();
+    const encodedElementLength = this.element.encodedLength;
+    if (encodedElementLength === undefined) {
+      // Dynamic elements: use offsets
+      assert(bytes.length >= dataOffset + length * 32);
+      return Array.from({ length }, (_, index) => {
+        const offset = Number(
+          Uint8ArrayExtension.toBigUintBE(bytes.slice(dataOffset + index * 32, dataOffset + (index + 1) * 32)),
+        );
+        return this.element.decode(bytes.slice(dataOffset + offset));
+      });
+    } else {
+      // Static elements: decode sequentially
+      assert(bytes.length >= dataOffset + length * encodedElementLength);
+      return Array.from({ length }, (_, index) => {
+        const offset = dataOffset + index * encodedElementLength;
+        return this.element.decode(bytes.slice(offset, offset + encodedElementLength));
+      });
+    }
+  }
+}
+
+export default class ABI {
+  readonly #addressFromBytes: (bytes: Uint8Array<ArrayBuffer>) => string;
+  readonly #bytesFromAddress: (address: string) => Uint8Array<ArrayBuffer>;
+
+  readonly selector?: Uint8Array<ArrayBuffer>;
+  readonly type: string;
+  readonly element: Element;
+
+  constructor(type: string, { addressFromBytes, bytesFromAddress }: {
+    addressFromBytes: (bytes: Uint8Array<ArrayBuffer>) => string;
+    bytesFromAddress: (address: string) => Uint8Array<ArrayBuffer>;
+  }) {
+    this.type = type;
+    this.#addressFromBytes = addressFromBytes;
+    this.#bytesFromAddress = bytesFromAddress;
+    const match = type.match(/^([^\(\)]+)(\(.*\))$/);
+    if (match !== null) {
+      const method = ensure(match[1]);
+      type = ensure(match[2]);
+      this.selector = keccak256(new TextEncoder().encode(`${method}${type}`)).slice(0, 4);
+    }
+    this.element = this.#parse(type);
+  }
+
+  decode(bytes: Uint8Array<ArrayBuffer>): unknown {
+    if (this.selector !== undefined) {
+      assert(bytes.length >= 4);
+      assert(Uint8ArrayExtension.equals(bytes.slice(0, 4), this.selector));
+      bytes = bytes.slice(4);
+    }
+    return this.element.decode(bytes);
+  }
+
+  encode(value: unknown): Uint8Array<ArrayBuffer> {
+    let bytes = this.element.encode(value);
+    if (this.selector !== undefined) {
+      bytes = Uint8ArrayExtension.concat([this.selector, bytes]);
+    }
+    return bytes;
+  }
+
+  #parse(type: string): Element {
+    const parsers: { regex: RegExp; fn: (match: RegExpMatchArray) => Element }[] = [
+      {
+        regex: /^(.+)\[(\d+)\]$/,
+        fn: (match) => new ArrayElement(this.#parse(ensure(match[1])), Number(ensure(match[2]))),
+      },
+      { regex: /^(.+)\[\]$/, fn: (match) => new ArrayElement(this.#parse(ensure(match[1]))) },
+      {
+        regex: /^\((.*)\)$/,
+        fn: (match) => {
+          const inner = ensure(match[1]);
+          const elements = new Array<Element>();
+          let element = '';
+          let depth = 0;
+          for (let i = 0; i < inner.length; i++) {
+            const char = inner[i];
+            if (char === ',' && depth === 0) {
+              elements.push(this.#parse(element));
+              element = '';
+            } else {
+              if (char === '(') {
+                depth++;
+              } else if (char === ')') {
+                depth--;
+              }
+              element += char;
+            }
+          }
+          assert(depth === 0, 'Unbalanced parentheses');
+          if (element !== '') {
+            elements.push(this.#parse(element));
+          }
+          return new StructElement(elements);
+        },
+      },
+      { regex: /^uint(\d+)$/, fn: (match) => new UintElement(Number(ensure(match[1]))) },
+      { regex: /^int(\d+)$/, fn: (match) => new IntElement(Number(ensure(match[1]))) },
+      { regex: /^bytes(\d+)$/, fn: (match) => new BytesElement(Number(ensure(match[1]))) },
+      { regex: /^bytes$/, fn: () => new BytesElement() },
+      { regex: /^string$/, fn: () => new StringElement() },
+      { regex: /^bool$/, fn: () => new BoolElement() },
+      {
+        regex: /^address$/,
+        fn: () => {
+          const bytesFromAddress = this.#bytesFromAddress.bind(this);
+          const addressFromBytes = this.#addressFromBytes.bind(this);
+          return new class extends AddressElement {
+            bytesFromAddress(address: string) {
+              return bytesFromAddress(address);
+            }
+            addressFromBytes(bytes: Uint8Array<ArrayBuffer>) {
+              return addressFromBytes(bytes);
+            }
+          }();
+        },
+      },
+    ];
+    try {
+      for (const { regex, fn } of parsers) {
+        const match = type.match(regex);
+        if (match) {
+          return fn(match);
+        }
+      }
+      throw new Error('No match');
+    } catch (_) {
+      throw new Error(`Failed to parse "${type}"`);
+    }
+  }
+}

package/src/Block.ts

@@ -0,0 +1,9 @@
+type Block = {
+  hash: string;
+  parentHash: string;
+  number: number;
+  transactions: string[];
+  timestamp: Date;
+};
+
+export default Block;

package/src/Client.ts

@@ -0,0 +1,152 @@
+import * as z from '@quentinadam/zod';
+import type ABI from './ABI.ts';
+import type Block from './Block.ts';
+import ClientError from './ClientError.ts';
+import type ClientHelper from './ClientHelper.ts';
+import type Log from './Log.ts';
+import type Transaction from './Transaction.ts';
+import type TransactionReceipt from './TransactionReceipt.ts';
+
+export default class Client {
+  readonly #url: string;
+  readonly #helper: ClientHelper;
+  #id = 0;
+
+  constructor(url: string, helper: ClientHelper) {
+    this.#url = url;
+    this.#helper = helper;
+  }
+
+  createABI(type: string): ABI {
+    return this.#helper.createABI(type);
+  }
+
+  async request({ method, params }: { method: string; params?: unknown }): Promise<unknown> {
+    const body = JSON.stringify({ method, params, id: this.#id++, jsonrpc: '2.0' });
+    const response = await fetch(this.#url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body,
+    });
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${await response.text()}`);
+    }
+    const result = z.union([
+      z.object({
+        error: z.object({ code: z.number(), message: z.string(), data: z.unknown() }),
+      }).transform(({ error }) => {
+        return { success: false as const, code: error.code, message: error.message, data: error.data };
+      }),
+      z.object({ result: z.unknown() }).transform(({ result }) => ({ success: true as const, value: result })),
+    ]).parse(await response.json());
+    if (!result.success) {
+      throw new ClientError({ message: result.message, code: result.code, data: result.data });
+    }
+    return result.value;
+  }
+
+  async call({ contract, data }: {
+    contract: string;
+    data: Uint8Array<ArrayBuffer> | { method: string; parameters: Uint8Array<ArrayBuffer> | unknown[] };
+  }): Promise<Uint8Array<ArrayBuffer>> {
+    data = this.#helper.normalizeData(data);
+    return this.#helper.BytesSchema.parse(
+      await this.request({
+        method: 'eth_call',
+        params: [{ to: this.#helper.serializeAddress(contract), data: '0x' + data.toHex() }, 'latest'],
+      }),
+    );
+  }
+
+  async getBlockNumber(): Promise<number> {
+    const response = await this.request({ method: 'eth_blockNumber' });
+    return this.#helper.HexNumberSchema.parse(response);
+  }
+
+  async getBlockByNumber(blockNumber: number): Promise<Block | undefined> {
+    const response = await this.request({
+      method: 'eth_getBlockByNumber',
+      params: [`0x${blockNumber.toString(16)}`, false],
+    });
+    return z.union([
+      z.null().transform(() => undefined),
+      z.object({
+        hash: z.string(),
+        parentHash: z.string(),
+        number: this.#helper.HexNumberSchema,
+        transactions: z.array(z.string()),
+        timestamp: this.#helper.HexNumberSchema.transform((value) => new Date(value * 1000)),
+      }),
+    ]).parse(response);
+  }
+
+  async getLogs({ address, fromBlock, toBlock, topics }: {
+    fromBlock?: number;
+    toBlock?: number;
+    address?: string | string[];
+    topics?: (null | Uint8Array | Uint8Array[])[];
+  }): Promise<Log[]> {
+    const response = await this.request({
+      method: 'eth_getLogs',
+      params: [{
+        fromBlock: fromBlock !== undefined ? `0x${fromBlock.toString(16)}` : undefined,
+        toBlock: toBlock !== undefined ? `0x${toBlock.toString(16)}` : undefined,
+        address: address === undefined
+          ? undefined
+          : typeof address === 'string'
+          ? this.#helper.serializeAddress(address)
+          : address.map((address) => this.#helper.serializeAddress(address)),
+        topics: topics?.map((topic) => {
+          return topic !== null
+            ? topic instanceof Uint8Array ? '0x' + topic.toHex() : topic.map((topic) => '0x' + topic.toHex())
+            : null;
+        }),
+      }],
+    });
+    return z.array(this.#helper.LogSchema).parse(response);
+  }
+
+  async getTransaction(hash: string): Promise<Transaction | undefined> {
+    return this.#helper.TransactionSchema.parse(
+      await this.request({
+        method: 'eth_getTransactionByHash',
+        params: [this.#helper.serializeHash(hash)],
+      }),
+    );
+  }
+
+  async getTransactionReceipt(hash: string): Promise<TransactionReceipt | undefined> {
+    return this.#helper.TransactionReceiptSchema.parse(
+      await this.request({
+        method: 'eth_getTransactionReceipt',
+        params: [this.#helper.serializeHash(hash)],
+      }),
+    );
+  }
+
+  async estimateGas({ from, to, value, data }: {
+    from: string;
+    to?: string;
+    value?: bigint;
+    data?: Uint8Array<ArrayBuffer> | { method: string; parameters: Uint8Array<ArrayBuffer> | unknown[] };
+  }): Promise<number> {
+    if (data !== undefined) {
+      data = this.#helper.normalizeData(data);
+    }
+    const result = await this.request({
+      method: 'eth_estimateGas',
+      params: [{
+        from,
+        value: `0x${(value ?? 0n).toString(16)}`,
+        to,
+        data: '0x' + (data ?? new Uint8Array(0)).toHex(),
+      }],
+    });
+    return this.#helper.HexNumberSchema.parse(result);
+  }
+
+  async getChainId(): Promise<number> {
+    const result = await this.request({ method: 'eth_chainId', params: [] });
+    return this.#helper.HexNumberSchema.parse(result);
+  }
+}

package/src/ClientError.ts

@@ -0,0 +1,10 @@
+export default class ClientError extends Error {
+  readonly code: number;
+  readonly data: unknown;
+
+  constructor({ message, code, data }: { message: string; code: number; data: unknown }) {
+    super(data === undefined ? message : `${message} (${JSON.stringify(data)})`);
+    this.code = code;
+    this.data = data;
+  }
+}