envio 3.0.1 → 3.0.2-svm-alpha.1

package/evm.schema.json

@@ -4,6 +4,10 @@
   "description": "Schema for a YAML config for an envio indexer",
   "type": "object",
   "properties": {
+    "name": {
+      "description": "Name of the project",
+      "type": "string"
+    },
     "description": {
       "description": "Description of the project",
       "type": [
@@ -11,10 +15,6 @@
         "null"
       ]
     },
-    "name": {
-      "description": "Name of the project",
-      "type": "string"
-    },
     "schema": {
       "description": "Custom path to schema.graphql file",
       "type": [
@@ -67,7 +67,7 @@
         "null"
       ],
       "items": {
-        "$ref": "#/$defs/GlobalContract_for_ContractConfig"
+        "$ref": "#/$defs/GlobalContract"
       }
     },
     "chains": {
@@ -189,7 +189,7 @@
         "evm"
       ]
     },
-    "GlobalContract_for_ContractConfig": {
+    "GlobalContract": {
       "type": "object",
       "properties": {
         "name": {
@@ -418,7 +418,7 @@
             "null"
           ],
           "items": {
-            "$ref": "#/$defs/ChainContract_for_ContractConfig"
+            "$ref": "#/$defs/ChainContract"
           }
         }
       },
@@ -578,7 +578,7 @@
         "url"
       ]
     },
-    "ChainContract_for_ContractConfig": {
+    "ChainContract": {
       "type": "object",
       "properties": {
         "name": {

package/fuel.schema.json

@@ -4,6 +4,10 @@
   "description": "Schema for a YAML config for an envio indexer",
   "type": "object",
   "properties": {
+    "name": {
+      "description": "Name of the project",
+      "type": "string"
+    },
     "description": {
       "description": "Description of the project",
       "type": [
@@ -11,10 +15,6 @@
         "null"
       ]
     },
-    "name": {
-      "description": "Name of the project",
-      "type": "string"
-    },
     "schema": {
       "description": "Custom path to schema.graphql file",
       "type": [
@@ -60,7 +60,7 @@
         "null"
       ],
       "items": {
-        "$ref": "#/$defs/GlobalContract_for_ContractConfig"
+        "$ref": "#/$defs/GlobalContract"
       }
     },
     "chains": {
@@ -147,7 +147,7 @@
         "fuel"
       ]
     },
-    "GlobalContract_for_ContractConfig": {
+    "GlobalContract": {
       "type": "object",
       "properties": {
         "name": {
@@ -183,6 +183,10 @@
     "EventConfig": {
       "type": "object",
       "properties": {
+        "name": {
+          "description": "Name of the event in the HyperIndex generated code",
+          "type": "string"
+        },
         "type": {
           "description": "Explicitly set the event type you want to index. It's derived from the event name and fallbacks to LogData.",
           "anyOf": [
@@ -194,10 +198,6 @@
             }
           ]
         },
-        "name": {
-          "description": "Name of the event in the HyperIndex generated code",
-          "type": "string"
-        },
         "logId": {
           "description": "An identifier of a logged type from ABI. Used for indexing LogData receipts. The option can be omitted when the event name matches the logged struct/enum name.",
           "type": [
@@ -281,7 +281,7 @@
             "null"
           ],
           "items": {
-            "$ref": "#/$defs/ChainContract_for_ContractConfig"
+            "$ref": "#/$defs/ChainContract"
           }
         }
       },
@@ -304,7 +304,7 @@
         "url"
       ]
     },
-    "ChainContract_for_ContractConfig": {
+    "ChainContract": {
       "type": "object",
       "properties": {
         "name": {

package/index.d.ts

@@ -961,6 +961,137 @@ export type SvmOnSlotOptions<Config extends IndexerConfigTypes = GlobalConfig> =
   readonly where?: (args: SvmOnSlotWhereArgs<Config>) => SvmOnSlotWhereResult;
 };
 
+// ============== SVM onInstruction types ==============
+
+/** Borsh-decoded view of an instruction. Present whenever a `ProgramSchema`
+ * was attached to the program (bundled, Anchor IDL, or hand-written
+ * `accounts`/`args` in YAML). Absent when no schema applies or the
+ * discriminator didn't match any registered instruction. */
+export type SvmDecodedInstruction = {
+  /** Schema-declared instruction name. */
+  readonly name: string;
+  /** Borsh-decoded args object. POC types this as `unknown`; narrow with a
+   * locally-declared type until the typed-args codegen lands. */
+  readonly args: unknown;
+  /** Named accounts in schema order. Keys are exactly the schema-declared
+   * names; values are base58 pubkeys. */
+  readonly accounts: Readonly<Record<string, string>>;
+  /** Accounts beyond the schema's named list (Anchor `remaining_accounts`,
+   * IDL drift). Empty when counts match the schema. */
+  readonly extraAccounts: readonly string[];
+};
+
+/** A single Solana instruction matched by the indexer.
+ *
+ * `data` and discriminator prefixes are `0x`-prefixed hex strings; accounts
+ * are base58 strings. When a Borsh schema is configured (bundled, Anchor
+ * IDL, or hand-written YAML), `decoded` carries the named-accounts +
+ * decoded-args view. */
+export type SvmInstruction = {
+  readonly programId: string;
+  readonly data: string;
+  readonly accounts: readonly string[];
+  readonly instructionAddress: readonly number[];
+  readonly isInner: boolean;
+  readonly d1?: string;
+  readonly d2?: string;
+  readonly d4?: string;
+  readonly d8?: string;
+  readonly decoded?: SvmDecodedInstruction;
+};
+
+export type SvmTokenBalance = {
+  readonly account?: string;
+  readonly mint?: string;
+  readonly owner?: string;
+  /** u64 decimal string. Cast with BigInt(...) for arithmetic. */
+  readonly preAmount?: string;
+  readonly postAmount?: string;
+};
+
+/** Parent transaction surfaced when an instruction's
+ * `include_transaction` flag is `true`. */
+export type SvmTransaction = {
+  readonly signatures: readonly string[];
+  readonly feePayer?: string;
+  readonly success?: boolean;
+  readonly err?: string;
+  /** Lamports. */
+  readonly fee?: bigint;
+  readonly computeUnitsConsumed?: bigint;
+  readonly accountKeys: readonly string[];
+  readonly recentBlockhash?: string;
+  readonly version?: string;
+  /** SPL Token / Token-2022 balance snapshots for this transaction.
+   * Present when `include_token_balances` is `true`. */
+  readonly tokenBalances?: readonly SvmTokenBalance[];
+};
+
+export type SvmLog = {
+  readonly kind: string;
+  readonly message: string;
+};
+
+/** A single Solana instruction event delivered to a handler. Parameterised
+ * over `Decoded` so the per-(program, instruction) overload of
+ * `onInstruction` can narrow `event.instruction.decoded` to the
+ * codegen-generated `{ args, accounts }` shape. */
+export type SvmInstructionEvent<
+  Decoded extends SvmDecodedInstruction = SvmDecodedInstruction,
+> = {
+  readonly contractName: string;
+  readonly eventName: string;
+  readonly instruction: Omit<SvmInstruction, "decoded"> & {
+    readonly decoded?: Decoded;
+  };
+  /** Present when the instruction's `include_transaction` is `true`. */
+  readonly transaction?: SvmTransaction;
+  /** Present when the instruction's `include_logs` is `true`; only logs
+   * scoped to this exact instruction (matching `instruction_address`). */
+  readonly logs?: readonly SvmLog[];
+  readonly slot: number;
+  readonly blockTime?: number;
+};
+
+/** Arguments passed to handlers registered via `indexer.onInstruction`. */
+export type SvmOnInstructionHandlerArgs<
+  Config extends IndexerConfigTypes = GlobalConfig,
+  Event extends SvmInstructionEvent = SvmInstructionEvent,
+> = {
+  readonly event: Event;
+  readonly context: SvmOnSlotContext<Config>;
+};
+
+/** Shape extracted from `Global.config.svm.programs[P][I]`. The codegen
+ * emits `{ args: ...; accounts: ... }` per (program, instruction); this
+ * helper turns that into a `SvmDecodedInstruction`-compatible record. */
+type SvmDecodedFromProgramTable<TInstr> = TInstr extends {
+  args: infer A;
+  accounts: infer Acc extends Readonly<Record<string, string>>;
+}
+  ? {
+      readonly name: string;
+      readonly args: A;
+      readonly accounts: Acc;
+      readonly extraAccounts: readonly string[];
+    }
+  : SvmDecodedInstruction;
+
+/** Options for an SVM `indexer.onInstruction` registration. */
+export type SvmOnInstructionOptions<P extends string = string, I extends string = string> = {
+  /** Program name as declared under `chains[].programs[].name` in
+   * `config.yaml`. */
+  readonly program: P;
+  /** Instruction name as declared under
+   * `chains[].programs[].instructions[].name` in `config.yaml`. */
+  readonly instruction: I;
+};
+
+/** Handler function for an SVM `indexer.onInstruction` registration. */
+export type SvmOnInstructionHandler<
+  Config extends IndexerConfigTypes = GlobalConfig,
+> = (args: SvmOnInstructionHandlerArgs<Config>) => Promise<void>;
+
 // ============== Indexer Types ==============
 
 // Helper: Check if an ecosystem is configured. Single-ecosystem indexers only
@@ -1138,7 +1269,7 @@ type FuelEcosystem<Config extends IndexerConfigTypes = GlobalConfig> =
       : never
     : never;
 
-// SVM ecosystem type — chains plus onSlot handler method. SVM has no onEvent yet.
+// SVM ecosystem type — chains plus instruction + slot handler methods.
 type SvmEcosystem<Config extends IndexerConfigTypes = GlobalConfig> =
   "svm" extends keyof Config
     ? Config["svm"] extends { chains: infer Chains }
@@ -1162,7 +1293,41 @@ type SvmEcosystem<Config extends IndexerConfigTypes = GlobalConfig> =
               options: SvmOnSlotOptions<Config>,
               handler: SvmOnSlotHandler<Config>,
             ) => void;
+          } & (Config["svm"] extends {
+            programs: infer Programs extends Record<string, Record<string, any>>;
           }
+            ? {
+                /**
+                 * Register an instruction handler. Dispatch matches on
+                 * `(programId, discriminator)` from the YAML config.
+                 * `event.instruction.decoded.args` and
+                 * `event.instruction.decoded.accounts` are typed from the
+                 * program's Borsh schema (Anchor IDL, bundled, or
+                 * hand-written `accounts`/`args` in YAML). `decoded` stays
+                 * optional at runtime because schema-matching can fail on
+                 * IDL drift or unknown discriminators.
+                 */
+                readonly onInstruction: <
+                  P extends keyof Programs & string,
+                  I extends keyof Programs[P] & string,
+                >(
+                  options: SvmOnInstructionOptions<P, I>,
+                  handler: (
+                    args: SvmOnInstructionHandlerArgs<
+                      Config,
+                      SvmInstructionEvent<SvmDecodedFromProgramTable<Programs[P][I]>>
+                    >,
+                  ) => Promise<void>,
+                ) => void;
+              }
+            : {
+                /** Untyped fallback for indexers with no `programs` in
+                 * config. `decoded` stays the generic shape. */
+                readonly onInstruction: (
+                  options: SvmOnInstructionOptions,
+                  handler: SvmOnInstructionHandler<Config>,
+                ) => void;
+              })
         : never
       : never
     : never;
@@ -1178,6 +1343,7 @@ type CodegenRequiredHint =
   "Run 'envio codegen' to generate handler types from config.yaml. Without codegen, the indexer has no contracts, chains, or events to register handlers for.";
 type CodegenRequiredFallback = {
   readonly onEvent: (...hint: CodegenRequiredHint[]) => void;
+  readonly onInstruction: (...hint: CodegenRequiredHint[]) => void;
   readonly onBlock: (...hint: CodegenRequiredHint[]) => void;
   readonly onSlot: (...hint: CodegenRequiredHint[]) => void;
   readonly contractRegister: (...hint: CodegenRequiredHint[]) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envio",
-  "version": "3.0.1",
+  "version": "3.0.2-svm-alpha.1",
   "type": "module",
   "description": "A latency and sync speed optimized, developer friendly blockchain data indexer.",
   "bin": "./bin.mjs",
@@ -43,7 +43,6 @@
     "@clickhouse/client": "1.17.0",
     "@elastic/ecs-pino-format": "1.4.0",
     "@envio-dev/hyperfuel-client": "1.2.2",
-    "@envio-dev/hypersync-client": "1.3.0",
     "@fuel-ts/crypto": "0.96.1",
     "@fuel-ts/errors": "0.96.1",
     "@fuel-ts/hasher": "0.96.1",
@@ -71,10 +70,10 @@
     "tsx": "4.21.0"
   },
   "optionalDependencies": {
-    "envio-linux-x64": "3.0.1",
-    "envio-linux-x64-musl": "3.0.1",
-    "envio-linux-arm64": "3.0.1",
-    "envio-darwin-x64": "3.0.1",
-    "envio-darwin-arm64": "3.0.1"
+    "envio-linux-x64": "3.0.2-svm-alpha.1",
+    "envio-linux-x64-musl": "3.0.2-svm-alpha.1",
+    "envio-linux-arm64": "3.0.2-svm-alpha.1",
+    "envio-darwin-x64": "3.0.2-svm-alpha.1",
+    "envio-darwin-arm64": "3.0.2-svm-alpha.1"
   }
 }

package/src/ChainFetcher.res

@@ -233,7 +233,31 @@ let make = (
       ~lowercaseAddresses,
     )
   | Config.FuelSourceConfig({hypersync}) => [HyperFuelSource.make({chain, endpointUrl: hypersync})]
-  | Config.SvmSourceConfig({rpc}) => [Svm.makeRPCSource(~chain, ~rpc)]
+  | Config.SvmSourceConfig({hypersync, rpc}) =>
+    switch hypersync {
+    | None => [Svm.makeRPCSource(~chain, ~rpc)]
+    | Some(hypersyncUrl) =>
+      // HyperSync drives instruction sync; RPC remains the height oracle
+      // (Svm.makeRPCSource's `getFinalizedSlot` route) and the fallback.
+      let svmEventConfigs =
+        chainConfig.contracts
+        ->Array.flatMap(contract => contract.events)
+        ->(
+          Utils.magic: array<Internal.eventConfig> => array<Internal.svmInstructionEventConfig>
+        )
+      let apiToken = Env.envioApiToken
+      [
+        HyperSyncSolanaSource.make({
+          chain,
+          endpointUrl: hypersyncUrl,
+          apiToken,
+          eventConfigs: svmEventConfigs,
+          clientMaxRetries: Env.hyperSyncClientMaxRetries,
+          clientTimeoutMillis: Env.hyperSyncClientTimeoutMillis,
+        }),
+        Svm.makeRPCSource(~chain, ~rpc, ~sourceFor=Fallback),
+      ]
+    }
   // For tests: use ready-to-use sources directly
   | Config.CustomSources(sources) => sources
   }

package/src/ChainFetcher.res.mjs

@@ -21,6 +21,7 @@ import * as Stdlib_Promise from "@rescript/runtime/lib/es6/Stdlib_Promise.js";
 import * as HyperFuelSource from "./sources/HyperFuelSource.res.mjs";
 import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
 import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
+import * as HyperSyncSolanaSource from "./sources/HyperSyncSolanaSource.res.mjs";
 import * as SafeCheckpointTracking from "./SafeCheckpointTracking.res.mjs";
 
 function configAddresses(chainConfig) {
@@ -133,7 +134,24 @@ function make(chainConfig, indexingAddresses, startBlock, endBlock, firstEventBl
         })];
       break;
     case "SvmSourceConfig" :
-      sources$1 = [Svm.makeRPCSource(chain, sources.rpc)];
+      let rpc = sources.rpc;
+      let hypersync = sources.hypersync;
+      if (hypersync !== undefined) {
+        let svmEventConfigs = chainConfig.contracts.flatMap(contract => contract.events);
+        sources$1 = [
+          HyperSyncSolanaSource.make({
+            chain: chain,
+            endpointUrl: hypersync,
+            apiToken: Env.envioApiToken,
+            eventConfigs: svmEventConfigs,
+            clientMaxRetries: Env.hyperSyncClientMaxRetries,
+            clientTimeoutMillis: Env.hyperSyncClientTimeoutMillis
+          }),
+          Svm.makeRPCSource(chain, rpc, "Fallback")
+        ];
+      } else {
+        sources$1 = [Svm.makeRPCSource(chain, rpc, undefined)];
+      }
       break;
     case "CustomSources" :
       sources$1 = sources._0;