@apibara/evm 2.0.0

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@apibara/evm",
+  "version": "2.0.0",
+  "type": "module",
+  "source": "./src/index.ts",
+  "main": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "files": [
+      "dist",
+      "src",
+      "README.md"
+    ]
+  },
+  "devDependencies": {
+    "@bufbuild/buf": "^1.32.1",
+    "@types/long": "^5.0.0",
+    "@types/node": "^20.12.12",
+    "unbuild": "^2.0.0",
+    "vitest": "^1.6.0"
+  },
+  "dependencies": {
+    "@effect/schema": "^0.67.15",
+    "effect": "^3.2.6",
+    "long": "^5.2.1",
+    "nice-grpc-common": "^2.0.2",
+    "protobufjs": "^7.1.2",
+    "viem": "^2.12.4",
+    "@apibara/protocol": "2.0.0-beta.1"
+  },
+  "scripts": {
+    "build": "pnpm build:proto && unbuild",
+    "build:proto": "buf generate proto",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "test:ci": "vitest run",
+    "lint": "biome check .",
+    "lint:fix": "pnpm lint --write",
+    "format": "biome format . --write"
+  },
+  "types": "./dist/index.d.ts"
+}

package/proto/common.proto

@@ -0,0 +1,37 @@
+syntax = "proto3";
+
+package evm.v2;
+
+// An address of 160 bits.
+//
+// As a separate type so that the API is clearer.
+message Address {
+  fixed64 x0 = 1;
+  fixed64 x1 = 2;
+  fixed32 x2 = 3;
+}
+
+// A bloom filter of 256 bytes.
+message Bloom { bytes value = 1; }
+
+// Unsigned integer of 128 bits.
+message U128 {
+  fixed64 x0 = 1;
+  fixed64 x1 = 2;
+}
+
+// Unsigned integer of 256 bits.
+message U256 {
+  fixed64 x0 = 1;
+  fixed64 x1 = 2;
+  fixed64 x2 = 3;
+  fixed64 x3 = 4;
+}
+
+// Byte array of 256 bits.
+message B256 {
+  fixed64 x0 = 1;
+  fixed64 x1 = 2;
+  fixed64 x2 = 3;
+  fixed64 x3 = 4;
+}

package/proto/data.proto

@@ -0,0 +1,192 @@
+// EVM DNA definitions (data).
+syntax = "proto3";
+
+package evm.v2;
+
+import "google/protobuf/timestamp.proto";
+import "common.proto";
+
+// Requested data, grouped by block.
+message Block {
+  // The header.
+  BlockHeader header = 1;
+  // List of withdrawals.
+  repeated Withdrawal withdrawals = 2;
+  // List of transactions.
+  repeated Transaction transactions = 3;
+  // List of receipts.
+  repeated TransactionReceipt receipts = 4;
+  // List of logs.
+  repeated Log logs = 5;
+}
+
+// Block header.
+message BlockHeader {
+  // Block number.
+  uint64 number = 1;
+  // Hash of the block.
+  B256 hash = 2;
+  // Hash of the parent block.
+  B256 parent_hash = 3;
+  // Hash of the uncles.
+  B256 uncles_hash = 4;
+  // Author of the block.
+  Address miner = 5;
+  // State root hash.
+  B256 state_root = 6;
+  // Transactions root hash.
+  B256 transactions_root = 7;
+  // Receipts root hash.
+  B256 receipts_root = 8;
+  // Logs bloom.
+  Bloom logs_bloom = 9;
+  // Difficulty.
+  U256 difficulty = 10;
+  // Gas limit.
+  U256 gas_limit = 11;
+  // Gas used.
+  U256 gas_used = 12;
+  // Timestamp.
+  google.protobuf.Timestamp timestamp = 13;
+  // Extra data.
+  bytes extra_data = 14;
+  // Mix hash.
+  B256 mix_hash = 15;
+  // Nonce.
+  uint64 nonce = 16;
+  // Base fee per unit of gas.
+  U256 base_fee_per_gas = 17;
+  // Withdrawals root hash.
+  B256 withdrawals_root = 18;
+
+  // Additional fields.
+
+  // Total difficulty.
+  U256 total_difficulty = 19;
+  // Uncles' hashes.
+  repeated B256 uncles = 20;
+  // The size of this block in bytes.
+  U256 size = 21;
+
+  // SKIPPED: withdrawals - included at top level.
+
+  // Blob gas used.
+  uint64 blob_gas_used = 22;
+  // Excess blob gas.
+  uint64 excess_blob_gas = 23;
+  // Parent beacon block root.
+  B256 parent_beacon_block_root = 24;
+}
+
+// A validator's withdrawal from the consensus layer.
+message Withdrawal {
+  // Increasing index of the withdrawal.
+  uint64 index = 1;
+  // Index of the validator.
+  uint64 validator_index = 2;
+  // Withdrawal index in the block.
+  uint64 withdrawal_index = 3;
+  // Target address of the withdrawal.
+  Address address = 4;
+  // Value of the withdrawal, in gwei.
+  U256 amount = 5;
+}
+
+message Transaction {
+  // Transaction hash.
+  B256 hash = 1;
+  // Nonce.
+  uint64 nonce = 2;
+  // Transaction index in the block.
+  uint64 transaction_index = 3;
+  // Sender.
+  Address from = 4;
+  // Recipient.
+  Address to = 5;
+  // Amount of wei transferred.
+  U256 value = 6;
+  // Gas price.
+  U128 gas_price = 7;
+  // Gas amount.
+  U256 gas = 8;
+  // Max base fee per gas the sender is willing to pay.
+  U128 max_fee_per_gas = 9;
+  // Miner's tip.
+  U128 max_priority_fee_per_gas = 10;
+  // Data.
+  bytes input = 11;
+  // The signature's r,s,v,yParity values.
+  Signature signature = 12;
+  // Chain ID.
+  uint64 chain_id = 13;
+  // EIP-2930 access list.
+  repeated AccessListItem access_list = 14;
+  // EIP-2718 transaction type.
+  uint64 transaction_type = 15;
+  // EIP-4844 max gas fee per blob.
+  U128 max_fee_per_blob_gas = 16;
+  // EIP-4844 blob hashes.
+  repeated B256 blob_versioned_hashes = 17;
+}
+
+message TransactionReceipt {
+  // Transaction hash.
+  B256 transaction_hash = 1;
+  // Index of the transaction in the block.
+  uint64 transaction_index = 2;
+  // Cumulative gas used in the block after this transaction has been executed.
+  U256 cumulative_gas_used = 3;
+  // Gas used by this transaction.
+  U256 gas_used = 4;
+  // The price paid by the transaction.
+  U128 effective_gas_price = 5;
+  // Sender.
+  Address from = 6;
+  // Recipient, if any.
+  Address to = 7;
+  // Contract address created, if any.
+  Address contract_address = 8;
+  // Logs bloom.
+  Bloom logs_bloom = 9;
+  // Either 1 (success) or 0 (failure).
+  uint64 status_code = 10;
+  // EIP-2718 transaction type.
+  uint64 transaction_type = 11;
+  // EIP-4844 blob gas used.
+  U128 blob_gas_used = 12;
+  // EIP-4844 blob gas paid by the transaction.
+  U128 blob_gas_price = 13;
+}
+
+message Log {
+  // Address of the contract that emitted the log.
+  Address address = 1;
+  // Log topics.
+  repeated B256 topics = 2;
+  // Additional data.
+  bytes data = 3;
+  // Index of the log in the block.
+  uint64 log_index = 4;
+  // Index of the transaction that emitted the log.
+  uint64 transaction_index = 5;
+  // Hash of the transaction that emitted the log.
+  B256 transaction_hash = 6;
+}
+
+message Signature {
+  // The signature's r value.
+  U256 r = 1;
+  // The signature's s value.
+  U256 s = 2;
+  // The signature's v value.
+  U256 v = 3;
+  // The signature's parity byte.
+  bool y_parity = 4;
+}
+
+message AccessListItem {
+  // Account address to be loaded at the start of the transaction.
+  Address address = 1;
+  // Storage keys to be loaded at the start of the transaction.
+  repeated B256 storage_keys = 2;
+}

package/proto/filter.proto

@@ -0,0 +1,61 @@
+// EVM DNA definitions (filter).
+syntax = "proto3";
+
+package evm.v2;
+
+import "common.proto";
+
+message Filter {
+  // Include header.
+  HeaderFilter header = 1;
+  // Filter withdrawals.
+  repeated WithdrawalFilter withdrawals = 2;
+  // Filter transactions.
+  repeated TransactionFilter transactions = 3;
+  // Filter logs.
+  repeated LogFilter logs = 4;
+}
+
+message HeaderFilter {
+  // Always include header data. Defaults to `false`.
+  optional bool always = 1;
+}
+
+message WithdrawalFilter {
+  // Filter based on the validator index.
+  optional uint64 validator_index = 1;
+  // Filter based on the withdrawal's target address.
+  Address address = 2;
+}
+
+message TransactionFilter {
+  // Filter based on the transaction's sender address.
+  Address from = 1;
+  // Filter based on the transaction's recipient address.
+  Address to = 2;
+  // Flag to request the transaction's receipt. Defaults to `false`.
+  optional bool include_receipt = 3;
+  // Flag to request the transaction's logs. Defaults to `false`.
+  optional bool include_logs = 4;
+}
+
+message LogFilter {
+  // Filter based on the log's contract address.
+  Address address = 1;
+  // Filter based on the log's topics.
+  repeated Topic topics = 2;
+  // Only returns logs with topics of exactly the same length as the filter.
+  //
+  // Defaults to `false`.
+  optional bool strict = 3;
+  // Flag to request the log's transaction. Defaults to `false`.
+  optional bool include_transaction = 4;
+  // Flag to request the log's receipt. Defaults to `false`.
+  optional bool include_receipt = 5;
+}
+
+// Topic filter.
+message Topic {
+  // Topic value. Leave empty to match any topic.
+  B256 value = 1;
+}

package/src/block.ts

@@ -0,0 +1,167 @@
+import { Bytes, BytesFromUint8Array } from "@apibara/protocol";
+import { Schema } from "@effect/schema";
+
+import { Address, B256, U128, U256 } from "./common";
+import * as proto from "./proto";
+
+export const HexData = Schema.transform(
+  Schema.Struct({
+    value: BytesFromUint8Array,
+  }),
+  Bytes,
+  {
+    strict: false,
+    encode(value) {
+      throw new Error("Not implemented");
+    },
+    decode({ value }) {
+      // return value;
+      throw new Error("Not implemented");
+    },
+  },
+);
+
+export const Bloom = Schema.transform(
+  Schema.Struct({
+    value: BytesFromUint8Array,
+  }),
+  Bytes,
+  {
+    strict: false,
+    encode(value) {
+      throw new Error("Not implemented");
+    },
+    decode({ value }) {
+      throw new Error("Not implemented");
+      // return value;
+    },
+  },
+);
+
+export const BlockHeader = Schema.Struct({
+  number: Schema.BigIntFromSelf,
+  hash: Schema.optional(B256),
+  parentHash: Schema.optional(B256),
+  uncleHash: Schema.optional(B256),
+  miner: Schema.optional(Address),
+  stateRoot: Schema.optional(B256),
+  transactionRoot: Schema.optional(B256),
+  receiptRoot: Schema.optional(B256),
+  logsBloom: Schema.optional(Bloom),
+  difficulty: Schema.optional(U256),
+  gasLimit: Schema.optional(U256),
+  gasUsed: Schema.optional(U256),
+  timestamp: Schema.optional(Schema.DateFromSelf),
+  // extraData: Schema.optional(HexData),
+  mixHash: Schema.optional(B256),
+  nonce: Schema.BigIntFromSelf,
+  baseFeePerGas: Schema.optional(U256),
+  withdrawalsRoot: Schema.optional(B256),
+  totalDifficulty: Schema.optional(U256),
+  uncles: Schema.Array(B256),
+  size: Schema.optional(U256),
+  blobGasUsed: Schema.BigIntFromSelf,
+  excessBlobGas: Schema.BigIntFromSelf,
+  parentBeaconBlockRoot: Schema.optional(B256),
+});
+
+export type BlockHeader = typeof BlockHeader.Type;
+
+export const Withdrawal = Schema.Struct({
+  index: Schema.BigIntFromSelf,
+  validatorIndex: Schema.BigIntFromSelf,
+  withdrawalIndex: Schema.BigIntFromSelf,
+  address: Schema.optional(Address),
+  amount: Schema.optional(U256),
+});
+
+export const AccessListItem = Schema.Struct({
+  address: Schema.optional(Address),
+  storageKeys: Schema.Array(B256),
+});
+
+export const Signature = Schema.Struct({
+  r: Schema.optional(U256),
+  s: Schema.optional(U256),
+  v: Schema.optional(U256),
+  YParity: Schema.optional(Schema.Boolean),
+});
+
+export const Transaction = Schema.Struct({
+  hash: Schema.optional(B256),
+  nonce: Schema.BigIntFromSelf,
+  transactionIndex: Schema.BigIntFromSelf,
+  from: Schema.optional(Address),
+  to: Schema.optional(Address),
+  value: Schema.optional(U256),
+  gasPrice: Schema.optional(U128),
+  gas: Schema.optional(U256),
+  maxFeePerGas: Schema.optional(U128),
+  maxPriorityFeePerGas: Schema.optional(U128),
+  // TODO
+  // input: Schema.optional(HexData),
+  signature: Schema.optional(Signature),
+  chainId: Schema.BigIntFromSelf,
+  accessList: Schema.Array(AccessListItem),
+  transactionType: Schema.BigIntFromSelf,
+  maxFeePerBlobGas: Schema.optional(U128),
+  blobVersionedHashes: Schema.Array(B256),
+});
+
+export const TransactionReceipt = Schema.Struct({
+  transactionHash: Schema.optional(B256),
+  transactionIndex: Schema.BigIntFromSelf,
+  cumulativeGasUsed: Schema.optional(U256),
+  gasUsed: Schema.optional(U256),
+  effectiveGasPrice: Schema.optional(U128),
+  from: Schema.optional(Address),
+  to: Schema.optional(Address),
+  contractAddress: Schema.optional(Address),
+  logsBloom: Schema.optional(Bloom),
+  statusCode: Schema.BigIntFromSelf,
+  transactionType: Schema.BigIntFromSelf,
+  blobGasUsed: Schema.optional(U128),
+  blobGasPrice: Schema.optional(U128),
+});
+
+export const Log = Schema.Struct({
+  address: Schema.optional(Address),
+  topics: Schema.Array(B256),
+  // TODO
+  // data: Bytes,
+  logIndex: Schema.BigIntFromSelf,
+  transactionIndex: Schema.BigIntFromSelf,
+  transactionHash: Schema.optional(B256),
+});
+
+export type Log = typeof Log.Type;
+
+export const Block = Schema.Struct({
+  header: Schema.optional(BlockHeader),
+  withdrawals: Schema.Array(Withdrawal),
+  transactions: Schema.Array(Transaction),
+  receipts: Schema.Array(TransactionReceipt),
+  logs: Schema.Array(Log),
+});
+
+export type Block = typeof Block.Type;
+
+export const BlockFromBytes = Schema.transform(
+  Schema.Uint8ArrayFromSelf,
+  Schema.NullOr(Block),
+  {
+    strict: false,
+    decode(value) {
+      if (value.length === 0) {
+        return null;
+      }
+      return proto.data.Block.decode(value);
+    },
+    encode(value) {
+      if (value === null) {
+        return new Uint8Array();
+      }
+      return proto.data.Block.encode(value).finish();
+    },
+  },
+);

package/src/common.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+
+import { Schema } from "@effect/schema";
+import { pad } from "viem";
+
+import { Address, B256, U128, U256 } from "./common";
+
+describe("Address", () => {
+  const encode = Schema.encodeSync(Address);
+  const decode = Schema.decodeSync(Address);
+
+  it("should convert to and from proto", () => {
+    const address = "0x27504265a9bc4330e3fe82061a60cd8b6369b4dc";
+
+    const message = encode(address);
+
+    expect(message.x0).toBeDefined();
+    expect(message.x1).toBeDefined();
+    expect(message.x2).toBeDefined();
+
+    const back = decode(message);
+    expect(back).toEqual(pad(address, { size: 20 }));
+  });
+});
+
+describe("B256", () => {
+  const encode = Schema.encodeSync(B256);
+  const decode = Schema.decodeSync(B256);
+
+  it("should convert to and from proto", () => {
+    const value =
+      "0x9df92d765b5aa041fd4bbe8d5878eb89290efa78e444c1a603eecfae2ea05fa4";
+    const message = encode(value);
+
+    expect(message.x0).toBeDefined();
+    expect(message.x1).toBeDefined();
+    expect(message.x2).toBeDefined();
+    expect(message.x3).toBeDefined();
+
+    const back = decode(message);
+    expect(back).toEqual(pad(value, { size: 32 }));
+  });
+});
+
+describe("U256", () => {
+  const encode = Schema.encodeSync(U256);
+  const decode = Schema.decodeSync(U256);
+
+  it("should convert to and from proto", () => {
+    const value = BigInt(
+      "0x9df92d765b5aa041fd4bbe8d5878eb89290efa78e444c1a603eecfae2ea05fa4",
+    );
+    const message = encode(value);
+
+    expect(message.x0).toBeDefined();
+    expect(message.x1).toBeDefined();
+    expect(message.x2).toBeDefined();
+    expect(message.x3).toBeDefined();
+
+    const back = decode(message);
+    expect(back).toEqual(value);
+  });
+});
+
+describe("U128", () => {
+  const encode = Schema.encodeSync(U128);
+  const decode = Schema.decodeSync(U128);
+
+  it("should convert to and from proto", () => {
+    const value = BigInt("0x090efa78e444c1a603eecfae2ea05fa4");
+    const message = encode(value);
+
+    expect(message.x0).toBeDefined();
+    expect(message.x1).toBeDefined();
+
+    const back = decode(message);
+    expect(back).toEqual(value);
+  });
+});

package/src/common.ts

@@ -0,0 +1,117 @@
+import { Schema } from "@effect/schema";
+import { hexToBytes, pad } from "viem";
+
+const MAX_U64 = 0xffffffffffffffffn;
+
+const _Address = Schema.TemplateLiteral(Schema.Literal("0x"), Schema.String);
+
+/** Wire representation of `Address`. */
+const AddressProto = Schema.Struct({
+  x0: Schema.BigIntFromSelf,
+  x1: Schema.BigIntFromSelf,
+  x2: Schema.Number,
+});
+
+/** An Ethereum address. */
+export const Address = Schema.transform(AddressProto, _Address, {
+  decode(value) {
+    const x0 = value.x0.toString(16).padStart(16, "0");
+    const x1 = value.x1.toString(16).padStart(16, "0");
+    const x2 = value.x2.toString(16).padStart(8, "0");
+    return `0x${x0}${x1}${x2}` as `0x${string}`;
+  },
+  encode(value) {
+    const bytes = hexToBytes(pad(value, { size: 20, dir: "left" }));
+    const dv = new DataView(bytes.buffer);
+    const x0 = dv.getBigUint64(0);
+    const x1 = dv.getBigUint64(8);
+    const x2 = dv.getUint32(16);
+    return { x0, x1, x2 };
+  },
+});
+
+export type Address = typeof Address.Type;
+
+const _B256 = Schema.TemplateLiteral(Schema.Literal("0x"), Schema.String);
+
+/** Wire representation of `B256`. */
+const B256Proto = Schema.Struct({
+  x0: Schema.BigIntFromSelf,
+  x1: Schema.BigIntFromSelf,
+  x2: Schema.BigIntFromSelf,
+  x3: Schema.BigIntFromSelf,
+});
+
+/** Data with length 256 bits. */
+export const B256 = Schema.transform(B256Proto, _B256, {
+  decode(value) {
+    const x0 = value.x0.toString(16).padStart(16, "0");
+    const x1 = value.x1.toString(16).padStart(16, "0");
+    const x2 = value.x2.toString(16).padStart(16, "0");
+    const x3 = value.x3.toString(16).padStart(16, "0");
+    return `0x${x0}${x1}${x2}${x3}` as `0x${string}`;
+  },
+  encode(value) {
+    const bytes = hexToBytes(pad(value, { size: 32, dir: "left" }));
+    const dv = new DataView(bytes.buffer);
+    const x0 = dv.getBigUint64(0);
+    const x1 = dv.getBigUint64(8);
+    const x2 = dv.getBigUint64(16);
+    const x3 = dv.getBigUint64(24);
+    return { x0, x1, x2, x3 };
+  },
+});
+
+export const b256ToProto = Schema.encodeSync(B256);
+export const b256FromProto = Schema.decodeSync(B256);
+
+/** Wire representation of `U256`. */
+const U256Proto = Schema.Struct({
+  x0: Schema.BigIntFromSelf,
+  x1: Schema.BigIntFromSelf,
+  x2: Schema.BigIntFromSelf,
+  x3: Schema.BigIntFromSelf,
+});
+
+/** Data with length 256 bits. */
+export const U256 = Schema.transform(U256Proto, Schema.BigIntFromSelf, {
+  decode(value) {
+    return (
+      (value.x0 << (8n * 24n)) +
+      (value.x1 << (8n * 16n)) +
+      (value.x2 << (8n * 8n)) +
+      value.x3
+    );
+  },
+  encode(value) {
+    const x0 = (value >> (8n * 24n)) & MAX_U64;
+    const x1 = (value >> (8n * 16n)) & MAX_U64;
+    const x2 = (value >> (8n * 8n)) & MAX_U64;
+    const x3 = value & MAX_U64;
+    return { x0, x1, x2, x3 };
+  },
+});
+
+export const u256ToProto = Schema.encodeSync(U256);
+export const u256FromProto = Schema.decodeSync(U256);
+
+/** Wire representation of `U128`. */
+const U128Proto = Schema.Struct({
+  x0: Schema.BigIntFromSelf,
+  x1: Schema.BigIntFromSelf,
+});
+
+/** Data with length 128 bits. */
+export const U128 = Schema.transform(U128Proto, Schema.BigIntFromSelf, {
+  decode(value) {
+    return (value.x0 << (8n * 8n)) + value.x1;
+  },
+  encode(value) {
+    const x0 = (value >> (8n * 8n)) & MAX_U64;
+    const x1 = value & MAX_U64;
+    return { x0, x1 };
+  },
+});
+
+export const u128ToProto = Schema.encodeSync(U128);
+export const u128FromProto = Schema.decodeSync(U128);