@apibara/beaconchain 2.0.0-beta.3

package/README.md

@@ -0,0 +1,25 @@
+# `@apibara/starknet`
+
+This package provides types for the Starknet streams on Apibara.
+
+## Installation
+
+```bash
+npm add @apibara/starknet
+```
+
+## 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,49 @@
+{
+  "name": "@apibara/beaconchain",
+  "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/evm": "2.0.0-beta.3",
+    "@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.13.8"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "types": "./dist/index.d.ts"
+}

package/src/block.ts

@@ -0,0 +1,114 @@
+import { AccessListItem, Signature } from "@apibara/evm";
+import { BytesFromUint8Array } from "@apibara/protocol";
+import { Schema } from "@effect/schema";
+
+import { Address, B256, B384, U128, U256, ValidatorStatus } from "./common";
+import * as proto from "./proto";
+
+export const ExecutionPayload = Schema.Struct({
+  parentHash: Schema.optional(B256),
+  feeRecipient: Schema.optional(Address),
+  stateRoot: Schema.optional(B256),
+  receiptsRoot: Schema.optional(B256),
+  logsBloom: BytesFromUint8Array,
+  prevRandao: Schema.optional(B256),
+  blockNumber: Schema.optional(Schema.BigIntFromSelf),
+  timestamp: Schema.optional(Schema.DateFromSelf),
+});
+
+export type ExecutionPayload = typeof ExecutionPayload.Type;
+
+export const BlockHeader = Schema.Struct({
+  slot: Schema.BigIntFromSelf,
+  proposerIndex: Schema.Number,
+  parentRoot: Schema.optional(B256),
+  stateRoot: Schema.optional(B256),
+  randaoReveal: BytesFromUint8Array,
+  depositCount: Schema.optional(Schema.BigIntFromSelf),
+  depositRoot: Schema.optional(B256),
+  blockHash: Schema.optional(B256),
+  graffiti: Schema.optional(B256),
+  executionPayload: Schema.optional(ExecutionPayload),
+  blobKzgCommitments: Schema.optional(Schema.Array(B384)),
+});
+
+export type BlockHeader = typeof BlockHeader.Type;
+
+export const Validator = Schema.Struct({
+  filterIds: Schema.optional(Schema.Array(Schema.Number)),
+  validatorIndex: Schema.optional(Schema.Number),
+  balance: Schema.optional(Schema.BigIntFromSelf),
+  status: Schema.optional(ValidatorStatus),
+  pubkey: Schema.optional(B384),
+  withdrawalCredentials: Schema.optional(B256),
+  effectiveBalance: Schema.optional(Schema.BigIntFromSelf),
+  slashed: Schema.optional(Schema.Boolean),
+  activationEligibilityEpoch: Schema.optional(Schema.BigIntFromSelf),
+  activationEpoch: Schema.optional(Schema.BigIntFromSelf),
+  exitEpoch: Schema.optional(Schema.BigIntFromSelf),
+  withdrawableEpoch: Schema.optional(Schema.BigIntFromSelf),
+});
+
+export const Blob = Schema.Struct({
+  filterIds: Schema.optional(Schema.Array(Schema.Number)),
+  blobIndex: Schema.optional(Schema.Number),
+  blob: Schema.optional(Schema.Uint8ArrayFromSelf),
+  kzgCommitment: Schema.optional(B384),
+  kzgProof: Schema.optional(B384),
+  kzgCommitmentInclusionProof: Schema.optional(Schema.Array(B256)),
+  blobHash: Schema.optional(B256),
+  transactionIndex: Schema.optional(Schema.Number),
+  transactionHash: Schema.optional(B256),
+});
+
+export const Transaction = Schema.Struct({
+  filterIds: Schema.optional(Schema.Array(Schema.Number)),
+  transactionHash: Schema.optional(B256),
+  nonce: Schema.optional(Schema.BigIntFromSelf),
+  transactionIndex: Schema.optional(Schema.Number),
+  from: Schema.optional(Address),
+  to: Schema.optional(Address),
+  value: Schema.optional(U256),
+  gasPrice: Schema.optional(U128),
+  gasLimit: Schema.optional(U128),
+  maxFeePerGas: Schema.optional(U128),
+  maxPriorityFeePerGas: Schema.optional(U128),
+  input: Schema.optional(Schema.Uint8ArrayFromSelf),
+  signature: Schema.optional(Signature),
+  chainId: Schema.optional(Schema.BigIntFromSelf),
+  accessList: Schema.optional(Schema.Array(AccessListItem)),
+  transactionType: Schema.optional(Schema.BigIntFromSelf),
+  maxFeePerBlobGas: Schema.optional(U128),
+  blobVersionedHashes: Schema.optional(Schema.Array(B256)),
+});
+
+export type Transaction = typeof Transaction.Type;
+
+export const Block = Schema.Struct({
+  header: Schema.optional(BlockHeader),
+  validators: Schema.Array(Validator),
+  blobs: Schema.Array(Blob),
+  transactions: Schema.Array(Transaction),
+});
+
+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,21 @@
+import { describe, expect, it } from "vitest";
+
+import { Schema } from "@effect/schema";
+import { pad } from "viem";
+
+import { B384 } from "./common";
+
+describe("B384", () => {
+  const encode = Schema.encodeSync(B384);
+  const decode = Schema.decodeSync(B384);
+
+  it("should convert from and to proto", () => {
+    const value =
+      "0x9df92d765b5aa041fd4bbe8d5878eb89290efa78e444c1a603eecfae2ea05fa4";
+
+    const message = encode(value);
+
+    const back = decode(message);
+    expect(back).toEqual(pad(value, { size: 48 }));
+  });
+});

package/src/common.ts

@@ -0,0 +1,95 @@
+import { Schema } from "@effect/schema";
+import { hexToBytes, pad } from "viem";
+
+import * as proto from "./proto";
+
+// Re-export common types
+export { Address, U128, U256, B256 } from "@apibara/evm";
+
+export const ValidatorStatus = Schema.transform(
+  Schema.Enums(proto.common.ValidatorStatus),
+  Schema.Literal(
+    "pending_initialized",
+    "pending_queued",
+    "active_ongoing",
+    "active_exiting",
+    "active_slashed",
+    "exited_unslashed",
+    "exited_slashed",
+    "withdrawal_possible",
+    "withdrawal_done",
+    "unknown",
+  ),
+  {
+    decode(value) {
+      const enumMap = {
+        [proto.common.ValidatorStatus.PENDING_INITIALIZED]:
+          "pending_initialized",
+        [proto.common.ValidatorStatus.PENDING_QUEUED]: "pending_queued",
+        [proto.common.ValidatorStatus.ACTIVE_ONGOING]: "active_ongoing",
+        [proto.common.ValidatorStatus.ACTIVE_EXITING]: "active_exiting",
+        [proto.common.ValidatorStatus.ACTIVE_SLASHED]: "active_slashed",
+        [proto.common.ValidatorStatus.EXITED_UNSLASHED]: "exited_unslashed",
+        [proto.common.ValidatorStatus.EXITED_SLASHED]: "exited_slashed",
+        [proto.common.ValidatorStatus.WITHDRAWAL_POSSIBLE]:
+          "withdrawal_possible",
+        [proto.common.ValidatorStatus.WITHDRAWAL_DONE]: "withdrawal_done",
+        [proto.common.ValidatorStatus.UNKNOWN]: "unknown",
+        [proto.common.ValidatorStatus.UNRECOGNIZED]: "unknown",
+      } as const;
+
+      return enumMap[value] ?? "unknown";
+    },
+    encode(value) {
+      const enumMap = {
+        pending_initialized: proto.common.ValidatorStatus.PENDING_INITIALIZED,
+        pending_queued: proto.common.ValidatorStatus.PENDING_QUEUED,
+        active_ongoing: proto.common.ValidatorStatus.ACTIVE_ONGOING,
+        active_exiting: proto.common.ValidatorStatus.ACTIVE_EXITING,
+        active_slashed: proto.common.ValidatorStatus.ACTIVE_SLASHED,
+        exited_unslashed: proto.common.ValidatorStatus.EXITED_UNSLASHED,
+        exited_slashed: proto.common.ValidatorStatus.EXITED_SLASHED,
+        withdrawal_possible: proto.common.ValidatorStatus.WITHDRAWAL_POSSIBLE,
+        withdrawal_done: proto.common.ValidatorStatus.WITHDRAWAL_DONE,
+        unknown: proto.common.ValidatorStatus.UNKNOWN,
+      } as const;
+
+      return enumMap[value] ?? proto.common.ValidatorStatus.UNKNOWN;
+    },
+  },
+);
+
+const _B384 = Schema.TemplateLiteral(Schema.Literal("0x"), Schema.String);
+const B384Proto = Schema.Struct({
+  x0: Schema.BigIntFromSelf,
+  x1: Schema.BigIntFromSelf,
+  x2: Schema.BigIntFromSelf,
+  x3: Schema.BigIntFromSelf,
+  x4: Schema.BigIntFromSelf,
+  x5: Schema.BigIntFromSelf,
+});
+
+export const B384 = Schema.transform(B384Proto, _B384, {
+  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");
+    const x4 = value.x4.toString(16).padStart(16, "0");
+    const x5 = value.x5.toString(16).padStart(16, "0");
+    return `0x${x0}${x1}${x2}${x3}${x4}${x5}` as `0x${string}`;
+  },
+  encode(value) {
+    const bytes = hexToBytes(pad(value, { size: 48, 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);
+    const x4 = dv.getBigUint64(32);
+    const x5 = dv.getBigUint64(40);
+    return { x0, x1, x2, x3, x4, x5 };
+  },
+});
+
+export type B384 = typeof B384.Type;

package/src/filter.ts

@@ -0,0 +1,113 @@
+import { Schema } from "@effect/schema";
+
+import { Address, ValidatorStatus } from "./common";
+import * as proto from "./proto";
+
+/** Header options.
+ *
+ * Change `always` to `true` to receive headers even if no other data matches.
+ */
+export const HeaderFilter = Schema.Struct({
+  always: Schema.optional(Schema.Boolean),
+});
+
+export type HeaderFilter = typeof HeaderFilter.Type;
+
+/** Filter transactions.
+ *
+ * @prop from Filter transactions by the sender address.
+ * @prop to Filter transactions by the target address.
+ * @prop includeBlob Include any blob posted by the transaction..
+ */
+export const TransactionFilter = Schema.Struct({
+  id: Schema.optional(Schema.Number),
+  from: Schema.optional(Address),
+  to: Schema.optional(Address),
+  create: Schema.optional(Schema.Boolean),
+  includeBlob: Schema.optional(Schema.Boolean),
+});
+
+export type TransactionFilter = typeof TransactionFilter.Type;
+
+/** Filter validators.
+ *
+ * @prop validatorIndex Filter validators by their index.
+ * @prop status Filter validators by their status.
+ */
+export const ValidatorFilter = Schema.Struct({
+  id: Schema.optional(Schema.Number),
+  validatorIndex: Schema.optional(Schema.Number),
+  status: Schema.optional(ValidatorStatus),
+});
+
+export type ValidatorFilter = typeof ValidatorFilter.Type;
+
+/** Filter blobs.
+ *
+ * @prop includeTransaction Include the transaction that posted the blob.
+ */
+export const BlobFilter = Schema.Struct({
+  id: Schema.optional(Schema.Number),
+  includeTransaction: Schema.optional(Schema.Boolean),
+});
+
+export type BlobFilter = typeof BlobFilter.Type;
+
+/** Filter block data.
+ *
+ * @prop header Change how block headers are returned.
+ * @prop validators Filter validators.
+ */
+export const Filter = Schema.Struct({
+  header: Schema.optional(HeaderFilter),
+  transactions: Schema.optional(Schema.Array(TransactionFilter)),
+  validators: Schema.optional(Schema.Array(ValidatorFilter)),
+  blobs: Schema.optional(Schema.Array(BlobFilter)),
+});
+
+export type Filter = typeof Filter.Type;
+
+export const filterToProto = Schema.encodeSync(Filter);
+export const filterFromProto = Schema.decodeSync(Filter);
+
+export const FilterFromBytes = Schema.transform(
+  Schema.Uint8ArrayFromSelf,
+  Filter,
+  {
+    strict: false,
+    decode(value) {
+      return proto.filter.Filter.decode(value);
+    },
+    encode(value) {
+      return proto.filter.Filter.encode(value).finish();
+    },
+  },
+);
+
+export const filterToBytes = Schema.encodeSync(FilterFromBytes);
+export const filterFromBytes = Schema.decodeSync(FilterFromBytes);
+
+export function mergeFilter(a: Filter, b: Filter): Filter {
+  const header = mergeHeaderFilter(a.header, b.header);
+  return {
+    header,
+    transactions: [...(a.transactions ?? []), ...(b.transactions ?? [])],
+    validators: [...(a.validators ?? []), ...(b.validators ?? [])],
+    blobs: [...(a.blobs ?? []), ...(b.blobs ?? [])],
+  };
+}
+
+function mergeHeaderFilter(
+  a?: HeaderFilter,
+  b?: HeaderFilter,
+): HeaderFilter | undefined {
+  if (a === undefined) {
+    return b;
+  }
+  if (b === undefined) {
+    return a;
+  }
+  return {
+    always: a.always || b.always,
+  };
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+import { StreamConfig } from "@apibara/protocol";
+import { BlockFromBytes } from "./block";
+import { FilterFromBytes, mergeFilter } from "./filter";
+
+export * as proto from "./proto";
+
+export * from "./common";
+export * from "./filter";
+export * from "./block";
+
+export const BeaconChainStream = new StreamConfig(
+  FilterFromBytes,
+  BlockFromBytes,
+  mergeFilter,
+);