@apibara/evm 2.0.0-beta.3

package/README.md

@@ -0,0 +1,27 @@
+# `@apibara/evm`
+
+This package provides a gRPC client to interact with an [Apibara streaming server](https://www.apibara.com/docs/streaming-protocol).
+
+## Installation
+
+```bash
+npm add @apibara/evm
+```
+
+## Usage
+
+## License
+
+Copyright 2024 GNC Labs Limited
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@apibara/evm",
+  "version": "2.0.0-beta.3",
+  "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": {},
+  "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"
+  },
+  "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": {
+    "@apibara/protocol": "2.0.0-beta.3",
+    "@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"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "types": "./dist/index.d.ts"
+}

package/src/block.ts

@@ -0,0 +1,173 @@
+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 Bloom = Schema.transform(
+  Schema.Struct({
+    value: BytesFromUint8Array,
+  }),
+  Bytes,
+  {
+    strict: false,
+    encode(value) {
+      throw new Error("Not implemented");
+    },
+    decode({ value }) {
+      return value;
+    },
+  },
+);
+
+export const TransactionStatus = Schema.transform(
+  Schema.Enums(proto.data.TransactionStatus),
+  Schema.Literal("unknown", "succeeded", "reverted"),
+  {
+    decode(value) {
+      const enumMap = {
+        [proto.data.TransactionStatus.SUCCEEDED]: "succeeded",
+        [proto.data.TransactionStatus.REVERTED]: "reverted",
+        [proto.data.TransactionStatus.UNSPECIFIED]: "unknown",
+        [proto.data.TransactionStatus.UNRECOGNIZED]: "unknown",
+      } as const;
+
+      return enumMap[value] ?? "unknown";
+    },
+    encode(value) {
+      throw new Error("encode: not implemented");
+    },
+  },
+);
+
+export type TransactionStatus = typeof TransactionStatus.Type;
+
+export const BlockHeader = Schema.Struct({
+  blockNumber: Schema.BigIntFromSelf,
+  blockHash: Schema.optional(B256),
+  parentBlockHash: Schema.optional(B256),
+  unclesHash: Schema.optional(B256),
+  miner: Schema.optional(Address),
+  stateRoot: Schema.optional(B256),
+  transactionsRoot: Schema.optional(B256),
+  receiptsRoot: Schema.optional(B256),
+  logsBloom: Schema.optional(Bloom),
+  difficulty: Schema.optional(U256),
+  gasLimit: Schema.optional(U128),
+  gasUsed: Schema.optional(U128),
+  timestamp: Schema.optional(Schema.DateFromSelf),
+  extraData: BytesFromUint8Array,
+  mixHash: Schema.optional(B256),
+  nonce: Schema.optional(Schema.BigIntFromSelf),
+  baseFeePerGas: Schema.optional(U128),
+  withdrawalsRoot: Schema.optional(B256),
+  totalDifficulty: Schema.optional(U256),
+  blobGasUsed: Schema.optional(U128),
+  excessBlobGas: Schema.optional(U128),
+  parentBeaconBlockRoot: Schema.optional(B256),
+});
+
+export type BlockHeader = typeof BlockHeader.Type;
+
+export const Withdrawal = Schema.Struct({
+  filterIds: Schema.optional(Schema.Array(Schema.Number)),
+  withdrawalIndex: Schema.Number,
+  index: Schema.BigIntFromSelf,
+  validatorIndex: Schema.Number,
+  address: Schema.optional(Address),
+  amount: Schema.optional(Schema.BigIntFromSelf),
+});
+
+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({
+  filterIds: Schema.optional(Schema.Array(Schema.Number)),
+  transactionIndex: Schema.Number,
+  transactionHash: Schema.optional(B256),
+  nonce: Schema.optional(Schema.BigIntFromSelf),
+  from: Schema.optional(Address),
+  to: Schema.optional(Address),
+  value: Schema.optional(U256),
+  gasPrice: Schema.optional(U128),
+  gas: Schema.optional(U128),
+  maxFeePerGas: Schema.optional(U128),
+  maxPriorityFeePerGas: Schema.optional(U128),
+  input: BytesFromUint8Array,
+  signature: Schema.optional(Signature),
+  chainId: Schema.optional(Schema.BigIntFromSelf),
+  accessList: Schema.Array(AccessListItem),
+  transactionType: Schema.optional(Schema.BigIntFromSelf),
+  maxFeePerBlobGas: Schema.optional(U128),
+  blobVersionedHashes: Schema.Array(B256),
+  transactionStatus: Schema.optional(TransactionStatus),
+});
+
+export const TransactionReceipt = Schema.Struct({
+  filterIds: Schema.optional(Schema.Array(Schema.Number)),
+  transactionIndex: Schema.optional(Schema.Number),
+  transactionHash: Schema.optional(B256),
+  cumulativeGasUsed: Schema.optional(U128),
+  gasUsed: Schema.optional(U128),
+  effectiveGasPrice: Schema.optional(U128),
+  from: Schema.optional(Address),
+  to: Schema.optional(Address),
+  contractAddress: Schema.optional(Address),
+  logsBloom: Schema.optional(Bloom),
+  transactionType: Schema.optional(Schema.BigIntFromSelf),
+  blobGasUsed: Schema.optional(U128),
+  blobGasPrice: Schema.optional(U128),
+  transactionStatus: Schema.optional(TransactionStatus),
+});
+
+export const Log = Schema.Struct({
+  filterIds: Schema.optional(Schema.Array(Schema.Number)),
+  address: Schema.optional(Address),
+  topics: Schema.Array(B256),
+  data: BytesFromUint8Array,
+  logIndex: Schema.Number,
+  transactionIndex: Schema.Number,
+  transactionHash: Schema.optional(B256),
+  transactionStatus: Schema.optional(TransactionStatus),
+});
+
+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`. */
+export 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);

package/src/filter.test.ts

@@ -0,0 +1,191 @@
+import { encodeEventTopics, pad, parseAbi } from "viem";
+import { describe, expect, it } from "vitest";
+
+import { Schema } from "@effect/schema";
+import {
+  Filter,
+  LogFilter,
+  filterFromProto,
+  filterToProto,
+  mergeFilter,
+} from "./filter";
+
+const abi = parseAbi([
+  "event Transfer(address indexed from, address indexed to, uint256 value)",
+]);
+
+describe("Filter", () => {
+  it("all filters are optional", () => {
+    const filter = Filter.make({});
+
+    const proto = filterToProto(filter);
+    const back = filterFromProto(proto);
+    expect(back).toEqual(filter);
+  });
+
+  it("accepts logs filter", () => {
+    const filter = Filter.make({
+      logs: [
+        {
+          address: "0x123456789012",
+          strict: true,
+          topics: encodeEventTopics({
+            abi,
+            eventName: "Transfer",
+            args: { from: null, to: null },
+          }) as `0x${string}`[],
+        },
+      ],
+    });
+
+    expect(filter.logs).toHaveLength(1);
+
+    const proto = filterToProto(filter);
+    const back = filterFromProto(proto);
+
+    expect(back).toBeDefined();
+    expect(back.logs).toHaveLength(1);
+  });
+});
+
+describe("LogFilter", () => {
+  const encode = Schema.encodeSync(LogFilter);
+  const decode = Schema.decodeSync(LogFilter);
+
+  it("can be empty", () => {
+    const filter = LogFilter.make({});
+
+    const proto = encode(filter);
+    const back = decode(proto);
+    expect(back).toEqual(filter);
+  });
+
+  it("can have null topics", () => {
+    const filter = LogFilter.make({
+      topics: [null, pad("0x1"), null, pad("0x3")],
+    });
+
+    const proto = encode(filter);
+    const back = decode(proto);
+    expect(back).toEqual(filter);
+  });
+
+  it("can have all optional fields", () => {
+    const filter = LogFilter.make({
+      address: pad("0xa", { size: 20 }),
+      topics: [null, pad("0x1"), null, pad("0x3")],
+      includeTransaction: true,
+      includeReceipt: true,
+      strict: true,
+    });
+
+    const proto = encode(filter);
+    const back = decode(proto);
+    expect(back).toEqual(filter);
+  });
+});
+
+describe("mergeFilter", () => {
+  it("returns header.always if any has it", () => {
+    const fa = mergeFilter({}, { header: { always: true } });
+    expect(fa).toMatchInlineSnapshot(`
+      {
+        "header": {
+          "always": true,
+        },
+        "logs": [],
+        "transactions": [],
+        "withdrawals": [],
+      }
+    `);
+    const fb = mergeFilter({ header: { always: true } }, {});
+    expect(fb).toMatchInlineSnapshot(`
+      {
+        "header": {
+          "always": true,
+        },
+        "logs": [],
+        "transactions": [],
+        "withdrawals": [],
+      }
+    `);
+  });
+
+  it("returns an empty header by default", () => {
+    const f = mergeFilter({}, {});
+    expect(f).toMatchInlineSnapshot(`
+      {
+        "header": undefined,
+        "logs": [],
+        "transactions": [],
+        "withdrawals": [],
+      }
+    `);
+  });
+
+  it("concatenates logs", () => {
+    const f = mergeFilter(
+      { logs: [{ address: "0xAAAAAAAAAAAAAAAAAAAAAA" }] },
+      { logs: [{ address: "0xBBBBBBBBBBBBBBBBBBBBBB" }] },
+    );
+    expect(f).toMatchInlineSnapshot(`
+      {
+        "header": undefined,
+        "logs": [
+          {
+            "address": "0xAAAAAAAAAAAAAAAAAAAAAA",
+          },
+          {
+            "address": "0xBBBBBBBBBBBBBBBBBBBBBB",
+          },
+        ],
+        "transactions": [],
+        "withdrawals": [],
+      }
+    `);
+  });
+
+  it("concatenates transactions", () => {
+    const f = mergeFilter(
+      { transactions: [{ from: "0xAAAAAAAAAAAAAAAAAAAAAA" }] },
+      { transactions: [{ from: "0xBBBBBBBBBBBBBBBBBBBBBB" }] },
+    );
+    expect(f).toMatchInlineSnapshot(`
+      {
+        "header": undefined,
+        "logs": [],
+        "transactions": [
+          {
+            "from": "0xAAAAAAAAAAAAAAAAAAAAAA",
+          },
+          {
+            "from": "0xBBBBBBBBBBBBBBBBBBBBBB",
+          },
+        ],
+        "withdrawals": [],
+      }
+    `);
+  });
+
+  it("concatenates withdrawals", () => {
+    const f = mergeFilter(
+      { withdrawals: [{ validatorIndex: 1 }] },
+      { withdrawals: [{ validatorIndex: 100 }] },
+    );
+    expect(f).toMatchInlineSnapshot(`
+      {
+        "header": undefined,
+        "logs": [],
+        "transactions": [],
+        "withdrawals": [
+          {
+            "validatorIndex": 1,
+          },
+          {
+            "validatorIndex": 100,
+          },
+        ],
+      }
+    `);
+  });
+});