@apibara/starknet 2.1.0-beta.2 → 2.1.0-beta.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apibara/starknet",
-  "version": "2.1.0-beta.2",
+  "version": "2.1.0-beta.20",
   "type": "module",
   "files": [
     "dist",
@@ -42,7 +42,7 @@
     "vitest": "^1.6.0"
   },
   "dependencies": {
-    "@apibara/protocol": "2.1.0-beta.2",
+    "@apibara/protocol": "2.1.0-beta.20",
     "@effect/schema": "^0.67.15",
     "@scure/starknet": "^1.1.0",
     "abi-wan-kanabi": "^2.2.4",

package/src/block.ts

@@ -14,6 +14,8 @@ export const ResourcePrice = Schema.Struct({
   priceInWei: Schema.optional(FieldElement),
 });
 
+export type ResourcePrice = typeof ResourcePrice.Type;
+
 /** How data is posted to L1. */
 export const L1DataAvailabilityMode = Schema.transform(
   Schema.Enums(proto.data.L1DataAvailabilityMode),
@@ -35,6 +37,8 @@ export const L1DataAvailabilityMode = Schema.transform(
   },
 );
 
+export type L1DataAvailabilityMode = typeof L1DataAvailabilityMode.Type;
+
 export const TransactionStatus = Schema.transform(
   Schema.Enums(proto.data.TransactionStatus),
   Schema.Literal("unknown", "succeeded", "reverted"),
@@ -75,16 +79,22 @@ export const U128 = Schema.transform(
   },
 );
 
+export type U128 = typeof U128.Type;
+
 export const ResourceBounds = Schema.Struct({
   maxAmount: Schema.BigIntFromSelf,
   maxPricePerUnit: U128,
 });
 
+export type ResourceBounds = typeof ResourceBounds.Type;
+
 export const ResourceBoundsMapping = Schema.Struct({
   l1Gas: ResourceBounds,
   l2Gas: ResourceBounds,
 });
 
+export type ResourceBoundsMapping = typeof ResourceBoundsMapping.Type;
+
 export const DataAvailabilityMode = Schema.transform(
   Schema.Enums(proto.data.DataAvailabilityMode),
   Schema.Literal("l1", "l2", "unknown"),
@@ -105,6 +115,8 @@ export const DataAvailabilityMode = Schema.transform(
   },
 );
 
+export type DataAvailabilityMode = typeof DataAvailabilityMode.Type;
+
 /** Starknet block header.
  *
  * @prop blockHash The hash of the block.
@@ -160,6 +172,8 @@ export const InvokeTransactionV0 = Schema.Struct({
   }),
 });
 
+export type InvokeTransactionV0 = typeof InvokeTransactionV0.Type;
+
 export const InvokeTransactionV1 = Schema.Struct({
   _tag: tag("invokeV1"),
   invokeV1: Schema.Struct({
@@ -171,6 +185,8 @@ export const InvokeTransactionV1 = Schema.Struct({
   }),
 });
 
+export type InvokeTransactionV1 = typeof InvokeTransactionV1.Type;
+
 export const InvokeTransactionV3 = Schema.Struct({
   _tag: tag("invokeV3"),
   invokeV3: Schema.Struct({
@@ -187,6 +203,8 @@ export const InvokeTransactionV3 = Schema.Struct({
   }),
 });
 
+export type InvokeTransactionV3 = typeof InvokeTransactionV3.Type;
+
 export const L1HandlerTransaction = Schema.Struct({
   _tag: tag("l1Handler"),
   l1Handler: Schema.Struct({
@@ -197,6 +215,8 @@ export const L1HandlerTransaction = Schema.Struct({
   }),
 });
 
+export type L1HandlerTransaction = typeof L1HandlerTransaction.Type;
+
 export const DeployTransaction = Schema.Struct({
   _tag: tag("deploy"),
   deploy: Schema.Struct({
@@ -206,6 +226,8 @@ export const DeployTransaction = Schema.Struct({
   }),
 });
 
+export type DeployTransaction = typeof DeployTransaction.Type;
+
 export const DeclareTransactionV0 = Schema.Struct({
   _tag: tag("declareV0"),
   declareV0: Schema.Struct({
@@ -216,6 +238,8 @@ export const DeclareTransactionV0 = Schema.Struct({
   }),
 });
 
+export type DeclareTransactionV0 = typeof DeclareTransactionV0.Type;
+
 export const DeclareTransactionV1 = Schema.Struct({
   _tag: tag("declareV1"),
   declareV1: Schema.Struct({
@@ -227,6 +251,8 @@ export const DeclareTransactionV1 = Schema.Struct({
   }),
 });
 
+export type DeclareTransactionV1 = typeof DeclareTransactionV1.Type;
+
 export const DeclareTransactionV2 = Schema.Struct({
   _tag: tag("declareV2"),
   declareV2: Schema.Struct({
@@ -239,6 +265,8 @@ export const DeclareTransactionV2 = Schema.Struct({
   }),
 });
 
+export type DeclareTransactionV2 = typeof DeclareTransactionV2.Type;
+
 export const DeclareTransactionV3 = Schema.Struct({
   _tag: tag("declareV3"),
   declareV3: Schema.Struct({
@@ -256,6 +284,8 @@ export const DeclareTransactionV3 = Schema.Struct({
   }),
 });
 
+export type DeclareTransactionV3 = typeof DeclareTransactionV3.Type;
+
 export const DeployAccountTransactionV1 = Schema.Struct({
   _tag: tag("deployAccountV1"),
   deployAccountV1: Schema.Struct({
@@ -268,6 +298,8 @@ export const DeployAccountTransactionV1 = Schema.Struct({
   }),
 });
 
+export type DeployAccountTransactionV1 = typeof DeployAccountTransactionV1.Type;
+
 export const DeployAccountTransactionV3 = Schema.Struct({
   _tag: tag("deployAccountV3"),
   deployAccountV3: Schema.Struct({
@@ -284,6 +316,8 @@ export const DeployAccountTransactionV3 = Schema.Struct({
   }),
 });
 
+export type DeployAccountTransactionV3 = typeof DeployAccountTransactionV3.Type;
+
 /** A transaction.
  *
  * @prop meta Transaction metadata.
@@ -328,11 +362,15 @@ export const PriceUnit = Schema.transform(
   },
 );
 
+export type PriceUnit = typeof PriceUnit.Type;
+
 export const FeePayment = Schema.Struct({
   amount: FieldElement,
   unit: PriceUnit,
 });
 
+export type FeePayment = typeof FeePayment.Type;
+
 export const ComputationResources = Schema.Struct({
   steps: Schema.BigIntFromSelf,
   memoryHoles: Schema.optional(Schema.BigIntFromSelf),
@@ -346,21 +384,29 @@ export const ComputationResources = Schema.Struct({
   segmentArenaBuiltin: Schema.optional(Schema.BigIntFromSelf),
 });
 
+export type ComputationResources = typeof ComputationResources.Type;
+
 export const DataAvailabilityResources = Schema.Struct({
   l1Gas: Schema.BigIntFromSelf,
   l1DataGas: Schema.BigIntFromSelf,
 });
 
+export type DataAvailabilityResources = typeof DataAvailabilityResources.Type;
+
 export const ExecutionResources = Schema.Struct({
   computation: ComputationResources,
   dataAvailability: DataAvailabilityResources,
 });
 
+export type ExecutionResources = typeof ExecutionResources.Type;
+
 export const ExecutionSucceeded = Schema.Struct({
   _tag: tag("succeeded"),
   succeeded: Schema.Struct({}),
 });
 
+export type ExecutionSucceeded = typeof ExecutionSucceeded.Type;
+
 export const ExecutionReverted = Schema.Struct({
   _tag: tag("reverted"),
   reverted: Schema.Struct({
@@ -368,6 +414,8 @@ export const ExecutionReverted = Schema.Struct({
   }),
 });
 
+export type ExecutionReverted = typeof ExecutionReverted.Type;
+
 /** Common fields for all transaction receipts. */
 export const TransactionReceiptMeta = Schema.Struct({
   transactionIndex: Schema.Number,
@@ -377,11 +425,15 @@ export const TransactionReceiptMeta = Schema.Struct({
   executionResult: Schema.Union(ExecutionSucceeded, ExecutionReverted),
 });
 
+export type TransactionReceiptMeta = typeof TransactionReceiptMeta.Type;
+
 export const InvokeTransactionReceipt = Schema.Struct({
   _tag: tag("invoke"),
   invoke: Schema.Struct({}),
 });
 
+export type InvokeTransactionReceipt = typeof InvokeTransactionReceipt.Type;
+
 export const L1HandlerTransactionReceipt = Schema.Struct({
   _tag: tag("l1Handler"),
   l1Handler: Schema.Struct({
@@ -389,11 +441,16 @@ export const L1HandlerTransactionReceipt = Schema.Struct({
   }),
 });
 
+export type L1HandlerTransactionReceipt =
+  typeof L1HandlerTransactionReceipt.Type;
+
 export const DeclareTransactionReceipt = Schema.Struct({
   _tag: tag("declare"),
   declare: Schema.Struct({}),
 });
 
+export type DeclareTransactionReceipt = typeof DeclareTransactionReceipt.Type;
+
 export const DeployTransactionReceipt = Schema.Struct({
   _tag: tag("deploy"),
   deploy: Schema.Struct({
@@ -401,6 +458,8 @@ export const DeployTransactionReceipt = Schema.Struct({
   }),
 });
 
+export type DeployTransactionReceipt = typeof DeployTransactionReceipt.Type;
+
 export const DeployAccountTransactionReceipt = Schema.Struct({
   _tag: tag("deployAccount"),
   deployAccount: Schema.Struct({
@@ -408,6 +467,9 @@ export const DeployAccountTransactionReceipt = Schema.Struct({
   }),
 });
 
+export type DeployAccountTransactionReceipt =
+  typeof DeployAccountTransactionReceipt.Type;
+
 /** A transaction receipt.
  *
  * @prop meta Transaction receipt metadata.
@@ -572,6 +634,162 @@ export const NonceUpdate = Schema.Struct({
 
 export type NonceUpdate = typeof NonceUpdate.Type;
 
+/** Trace call type. */
+export const CallType = Schema.transform(
+  Schema.Enums(proto.data.CallType),
+  Schema.Literal("libraryCall", "call", "delegate", "unknown"),
+  {
+    decode(value) {
+      const enumMap = {
+        [proto.data.CallType.LIBRARY_CALL]: "libraryCall",
+        [proto.data.CallType.CALL]: "call",
+        [proto.data.CallType.DELEGATE]: "delegate",
+        [proto.data.CallType.UNSPECIFIED]: "unknown",
+        [proto.data.CallType.UNRECOGNIZED]: "unknown",
+      } as const;
+
+      return enumMap[value] ?? "unknown";
+    },
+    encode(value) {
+      throw new Error("encode: not implemented");
+    },
+  },
+);
+
+/** A function invocation.
+ *
+ * @prop contractAddress The contract address.
+ * @prop entryPointSelector The entry point selector.
+ * @prop calldata The calldata.
+ * @prop callerAddress The caller address.
+ * @prop classHash The class hash.
+ * @prop callType The call type.
+ * @prop result The function invocation result.
+ * @prop calls The nested function invocations.
+ * @prop events The events index in the current transaction.
+ * @prop messages The messages index in the current transaction.
+ */
+export class FunctionInvocation extends Schema.Class<FunctionInvocation>(
+  "FunctionInvocation",
+)({
+  contractAddress: FieldElement,
+  entryPointSelector: FieldElement,
+  calldata: Schema.Array(FieldElement),
+  callerAddress: FieldElement,
+  classHash: FieldElement,
+  callType: CallType,
+  result: Schema.Array(FieldElement),
+  calls: Schema.suspend(
+    // biome-ignore lint/suspicious/noExplicitAny: not possible otherwise
+    (): Schema.Schema<any> => Schema.Array(FunctionInvocation),
+  ),
+  events: Schema.Array(Schema.Number),
+  messages: Schema.Array(Schema.Number),
+}) {}
+
+/** A successful invocation of the __execute__ call.
+ *
+ * @prop success The call.
+ */
+export const ExecuteInvocationSuccess = Schema.Struct({
+  _tag: tag("success"),
+  success: FunctionInvocation,
+});
+
+/** A failed invocation of the __execute__ call.
+ *
+ * @prop reason The reason for the failure.
+ */
+export const ExecuteInvocationReverted = Schema.Struct({
+  _tag: tag("reverted"),
+  reverted: Schema.Struct({
+    reason: Schema.optional(Schema.String),
+  }),
+});
+
+/** Trace for invoke transactions.
+ *
+ * @prop validateInvocation The __validate__ call.
+ * @prop executeInvocation The __execute__ call.
+ * @prop feeTransferInvocation The __fee_transfer__ call.
+ */
+export const InvokeTransactionTrace = Schema.Struct({
+  _tag: tag("invoke"),
+  invoke: Schema.Struct({
+    validateInvocation: Schema.optional(FunctionInvocation),
+    executeInvocation: Schema.Union(
+      ExecuteInvocationReverted,
+      ExecuteInvocationSuccess,
+    ),
+    feeTransferInvocation: Schema.optional(FunctionInvocation),
+  }),
+});
+
+export type InvokeTransactionTrace = typeof InvokeTransactionTrace.Type;
+
+/** Trace for declare transactions.
+ *
+ * @prop validateInvocation The __validate__ call.
+ * @prop feeTransferInvocation The __fee_transfer__ call.
+ */
+export const DeclareTransactionTrace = Schema.Struct({
+  _tag: tag("declare"),
+  declare: Schema.Struct({
+    validateInvocation: Schema.optional(FunctionInvocation),
+    feeTransferInvocation: Schema.optional(FunctionInvocation),
+  }),
+});
+
+export type DeclareTransactionTrace = typeof DeclareTransactionTrace.Type;
+
+/** Trace for deploy account transactions.
+ *
+ * @prop validateInvocation The __validate__ call.
+ * @prop constructorInvocation The __constructor__ call.
+ * @prop feeTransferInvocation The __fee_transfer__ call.
+ */
+export const DeployAccountTransactionTrace = Schema.Struct({
+  _tag: tag("deployAccount"),
+  deployAccount: Schema.Struct({
+    validateInvocation: Schema.optional(FunctionInvocation),
+    constructorInvocation: Schema.optional(FunctionInvocation),
+    feeTransferInvocation: Schema.optional(FunctionInvocation),
+  }),
+});
+
+export type DeployAccountTransactionTrace =
+  typeof DeployAccountTransactionTrace.Type;
+
+/** Trace for L1 handler transactions.
+ *
+ * @prop functionInvocation The L1 handler function invocation.
+ */
+export const L1HandlerTransactionTrace = Schema.Struct({
+  _tag: tag("l1Handler"),
+  l1Handler: Schema.Struct({
+    functionInvocation: Schema.optional(FunctionInvocation),
+  }),
+});
+
+/** A transaction trace.
+ *
+ * @prop transactionHash The hash of the trace's transaction.
+ * @prp traceRoot the trace root entry.
+ */
+export const TransactionTrace = Schema.Struct({
+  filterIds: Schema.Array(Schema.Number),
+  transactionIndex: Schema.Number,
+  transactionHash: FieldElement,
+  traceRoot: Schema.Union(
+    InvokeTransactionTrace,
+    DeclareTransactionTrace,
+    DeployAccountTransactionTrace,
+    L1HandlerTransactionTrace,
+  ),
+});
+
+export type TransactionTrace = typeof TransactionTrace.Type;
+
 /** A block.
  *
  * @prop header The block header.
@@ -579,6 +797,7 @@ export type NonceUpdate = typeof NonceUpdate.Type;
  * @prop receipts The receipts of the transactions.
  * @prop events The events emitted by the transactions.
  * @prop messages The messages sent to L1 by the transactions.
+ * @prop traces The transaction traces.
  * @prop storageDiffs The changes to the storage.
  * @prop contractChanges The changes to contracts and classes.
  */
@@ -588,6 +807,7 @@ export const Block = Schema.Struct({
   receipts: Schema.Array(TransactionReceipt),
   events: Schema.Array(Event),
   messages: Schema.Array(MessageToL1),
+  traces: Schema.Array(TransactionTrace),
   storageDiffs: Schema.Array(StorageDiff),
   contractChanges: Schema.Array(ContractChange),
   nonceUpdates: Schema.Array(NonceUpdate),

package/src/filter.ts

@@ -106,6 +106,7 @@ export type TransactionStatusFilter = typeof TransactionStatusFilter.Type;
  * @prop includeReceipt Include the transaction receipt.
  * @prop includeMessages Include the messages that were sent to L1 in the same transaction.
  * @prop includeSiblings Include the sibling events of the matched events.
+ * @prop includeTransactionTrace Include the trace of the transaction that emitted the event.
  */
 export const EventFilter = Schema.Struct({
   id: Schema.optional(Schema.Number),
@@ -117,6 +118,7 @@ export const EventFilter = Schema.Struct({
   includeReceipt: Schema.optional(Schema.Boolean),
   includeMessages: Schema.optional(Schema.Boolean),
   includeSiblings: Schema.optional(Schema.Boolean),
+  includeTransactionTrace: Schema.optional(Schema.Boolean),
 });
 
 export type EventFilter = typeof EventFilter.Type;
@@ -129,6 +131,7 @@ export type EventFilter = typeof EventFilter.Type;
  * @prop includeTransaction Include the transaction that sent the message.
  * @prop includeReceipt Include the transaction receipt.
  * @prop includeEvents Include events from the same transaction.
+ * @prop includeTransactionTrace Include the trace of the transaction that sent the message.
  */
 export const MessageToL1Filter = Schema.Struct({
   id: Schema.optional(Schema.Number),
@@ -138,6 +141,7 @@ export const MessageToL1Filter = Schema.Struct({
   includeTransaction: Schema.optional(Schema.Boolean),
   includeReceipt: Schema.optional(Schema.Boolean),
   includeEvents: Schema.optional(Schema.Boolean),
+  includeTransactionTrace: Schema.optional(Schema.Boolean),
 });
 
 export type MessageToL1Filter = typeof MessageToL1Filter.Type;
@@ -147,62 +151,87 @@ export const InvokeTransactionV0Filter = Schema.Struct({
   invokeV0: Schema.Struct({}),
 });
 
+export type InvokeTransactionV0Filter = typeof InvokeTransactionV0Filter.Type;
+
 export const InvokeTransactionV1Filter = Schema.Struct({
   _tag: tag("invokeV1"),
   invokeV1: Schema.Struct({}),
 });
 
+export type InvokeTransactionV1Filter = typeof InvokeTransactionV1Filter.Type;
+
 export const InvokeTransactionV3Filter = Schema.Struct({
   _tag: tag("invokeV3"),
   invokeV3: Schema.Struct({}),
 });
 
+export type InvokeTransactionV3Filter = typeof InvokeTransactionV3Filter.Type;
+
 export const DeployTransactionFilter = Schema.Struct({
   _tag: tag("deploy"),
   deploy: Schema.Struct({}),
 });
 
+export type DeployTransactionFilter = typeof DeployTransactionFilter.Type;
+
 export const DeclareV0TransactionFilter = Schema.Struct({
   _tag: tag("declareV0"),
   declareV0: Schema.Struct({}),
 });
 
+export type DeclareV0TransactionFilter = typeof DeclareV0TransactionFilter.Type;
+
 export const DeclareV1TransactionFilter = Schema.Struct({
   _tag: tag("declareV1"),
   declareV1: Schema.Struct({}),
 });
 
+export type DeclareV1TransactionFilter = typeof DeclareV1TransactionFilter.Type;
+
 export const DeclareV2TransactionFilter = Schema.Struct({
   _tag: tag("declareV2"),
   declareV2: Schema.Struct({}),
 });
 
+export type DeclareV2TransactionFilter = typeof DeclareV2TransactionFilter.Type;
+
 export const DeclareV3TransactionFilter = Schema.Struct({
   _tag: tag("declareV3"),
   declareV3: Schema.Struct({}),
 });
 
+export type DeclareV3TransactionFilter = typeof DeclareV3TransactionFilter.Type;
+
 export const L1HandlerTransactionFilter = Schema.Struct({
   _tag: tag("l1Handler"),
   l1Handler: Schema.Struct({}),
 });
 
+export type L1HandlerTransactionFilter = typeof L1HandlerTransactionFilter.Type;
+
 export const DeployAccountV1TransactionFilter = Schema.Struct({
   _tag: tag("deployAccountV1"),
   deployAccountV1: Schema.Struct({}),
 });
 
+export type DeployAccountV1TransactionFilter =
+  typeof DeployAccountV1TransactionFilter.Type;
+
 export const DeployAccountV3TransactionFilter = Schema.Struct({
   _tag: tag("deployAccountV3"),
   deployAccountV3: Schema.Struct({}),
 });
 
+export type DeployAccountV3TransactionFilter =
+  typeof DeployAccountV3TransactionFilter.Type;
+
 /** Filter transactions.
  *
  * @prop transactionStatus Filter based on the transaction status.
  * @prop includeReceipt Include the transaction receipt.
  * @prop includeEvents Include events from the same transaction.
  * @prop includeMessages Include messages sent in the transaction.
+ * @prop includeTrace Include the transaction's trace.
  */
 export const TransactionFilter = Schema.Struct({
   id: Schema.optional(Schema.Number),
@@ -210,6 +239,7 @@ export const TransactionFilter = Schema.Struct({
   includeReceipt: Schema.optional(Schema.Boolean),
   includeMessages: Schema.optional(Schema.Boolean),
   includeEvents: Schema.optional(Schema.Boolean),
+  includeTrace: Schema.optional(Schema.Boolean),
   transactionType: Schema.optional(
     Schema.Union(
       InvokeTransactionV0Filter,
@@ -275,6 +305,8 @@ export const ContractChangeFilter = Schema.Struct({
   ),
 });
 
+export type ContractChangeFilter = typeof ContractChangeFilter.Type;
+
 /** Filter updates to nonces.
  *
  * @prop contractAddress Filter by contract address.
@@ -284,6 +316,8 @@ export const NonceUpdateFilter = Schema.Struct({
   contractAddress: Schema.optional(FieldElement),
 });
 
+export type NonceUpdateFilter = typeof NonceUpdateFilter.Type;
+
 export const Filter = Schema.Struct({
   header: Schema.optional(HeaderFilter),
   transactions: Schema.optional(Schema.Array(TransactionFilter)),