envio 3.1.2 → 3.2.0

package/evm.schema.json

@@ -39,7 +39,7 @@
       "minimum": 0
     },
     "storage": {
-      "description": "Configuration for the storage backends the indexer writes to. Defaults to `postgres: true` when omitted. ClickHouse requires Postgres to be enabled (it is not supported as a single storage yet), and at least one backend must be enabled.",
+      "description": "Storage backends the indexer writes data to. Defaults to Postgres when omitted. Set `clickhouse: true` to additionally sync the indexed data to ClickHouse. Mark a backend with `default: true` to store entities that don't have an @storage directive in the schema, e.g. `clickhouse: {default: true}`.",
       "anyOf": [
         {
           "$ref": "#/$defs/StorageConfig"
@@ -131,17 +131,75 @@
       "type": "object",
       "properties": {
         "postgres": {
-          "description": "Whether to use Postgres as a storage backend (default: true).",
-          "type": [
-            "boolean",
-            "null"
+          "description": "Whether to use Postgres as a storage backend (default: true). Accepts a boolean or an options object (the object form implies the backend is enabled).",
+          "anyOf": [
+            {
+              "type": [
+                "boolean",
+                "null"
+              ]
+            },
+            {
+              "type": "object",
+              "properties": {
+                "default": {
+                  "description": "Whether entities without an @storage directive are stored in this backend (default: true when Postgres is the only enabled backend, false otherwise).",
+                  "type": [
+                    "boolean",
+                    "null"
+                  ]
+                },
+                "column_name_format": {
+                  "description": "How entity fields are reflected in the storage column names. `original` keeps the schema.graphql field names as is, `snake_case` converts them to snake_case in the database while keeping the original casing in the exposed APIs. (default: original)",
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "enum": [
+                    "original",
+                    "snake_case",
+                    null
+                  ]
+                }
+              },
+              "additionalProperties": false
+            }
           ]
         },
         "clickhouse": {
-          "description": "Whether to additionally sync the indexed data to ClickHouse. Requires Postgres to be enabled (default: false).",
-          "type": [
-            "boolean",
-            "null"
+          "description": "Whether to additionally sync the indexed data to ClickHouse. Requires Postgres to be enabled (default: false). Accepts a boolean or an options object (the object form implies the backend is enabled).",
+          "anyOf": [
+            {
+              "type": [
+                "boolean",
+                "null"
+              ]
+            },
+            {
+              "type": "object",
+              "properties": {
+                "default": {
+                  "description": "Whether entities without an @storage directive are stored in this backend (default: false).",
+                  "type": [
+                    "boolean",
+                    "null"
+                  ]
+                },
+                "column_name_format": {
+                  "description": "How entity fields are reflected in the storage column names. `original` keeps the schema.graphql field names as is, `snake_case` converts them to snake_case in the database while keeping the original casing in the exposed APIs. (default: original)",
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "enum": [
+                    "original",
+                    "snake_case",
+                    null
+                  ]
+                }
+              },
+              "additionalProperties": false
+            }
           ]
         }
       },
@@ -163,7 +221,14 @@
           "if": {
             "properties": {
               "clickhouse": {
-                "const": true
+                "anyOf": [
+                  {
+                    "const": true
+                  },
+                  {
+                    "type": "object"
+                  }
+                ]
               }
             },
             "required": [
@@ -173,7 +238,14 @@
           "then": {
             "properties": {
               "postgres": {
-                "const": true
+                "anyOf": [
+                  {
+                    "const": true
+                  },
+                  {
+                    "type": "object"
+                  }
+                ]
               }
             },
             "required": [

package/fuel.schema.json

@@ -39,7 +39,7 @@
       "minimum": 0
     },
     "storage": {
-      "description": "Configuration for the storage backends the indexer writes to. Defaults to `postgres: true` when omitted. ClickHouse requires Postgres to be enabled (it is not supported as a single storage yet), and at least one backend must be enabled.",
+      "description": "Storage backends the indexer writes data to. Defaults to Postgres when omitted. Set `clickhouse: true` to additionally sync the indexed data to ClickHouse. Mark a backend with `default: true` to store entities that don't have an @storage directive in the schema, e.g. `clickhouse: {default: true}`.",
       "anyOf": [
         {
           "$ref": "#/$defs/StorageConfig"
@@ -89,17 +89,75 @@
       "type": "object",
       "properties": {
         "postgres": {
-          "description": "Whether to use Postgres as a storage backend (default: true).",
-          "type": [
-            "boolean",
-            "null"
+          "description": "Whether to use Postgres as a storage backend (default: true). Accepts a boolean or an options object (the object form implies the backend is enabled).",
+          "anyOf": [
+            {
+              "type": [
+                "boolean",
+                "null"
+              ]
+            },
+            {
+              "type": "object",
+              "properties": {
+                "default": {
+                  "description": "Whether entities without an @storage directive are stored in this backend (default: true when Postgres is the only enabled backend, false otherwise).",
+                  "type": [
+                    "boolean",
+                    "null"
+                  ]
+                },
+                "column_name_format": {
+                  "description": "How entity fields are reflected in the storage column names. `original` keeps the schema.graphql field names as is, `snake_case` converts them to snake_case in the database while keeping the original casing in the exposed APIs. (default: original)",
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "enum": [
+                    "original",
+                    "snake_case",
+                    null
+                  ]
+                }
+              },
+              "additionalProperties": false
+            }
           ]
         },
         "clickhouse": {
-          "description": "Whether to additionally sync the indexed data to ClickHouse. Requires Postgres to be enabled (default: false).",
-          "type": [
-            "boolean",
-            "null"
+          "description": "Whether to additionally sync the indexed data to ClickHouse. Requires Postgres to be enabled (default: false). Accepts a boolean or an options object (the object form implies the backend is enabled).",
+          "anyOf": [
+            {
+              "type": [
+                "boolean",
+                "null"
+              ]
+            },
+            {
+              "type": "object",
+              "properties": {
+                "default": {
+                  "description": "Whether entities without an @storage directive are stored in this backend (default: false).",
+                  "type": [
+                    "boolean",
+                    "null"
+                  ]
+                },
+                "column_name_format": {
+                  "description": "How entity fields are reflected in the storage column names. `original` keeps the schema.graphql field names as is, `snake_case` converts them to snake_case in the database while keeping the original casing in the exposed APIs. (default: original)",
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "enum": [
+                    "original",
+                    "snake_case",
+                    null
+                  ]
+                }
+              },
+              "additionalProperties": false
+            }
           ]
         }
       },
@@ -121,7 +179,14 @@
           "if": {
             "properties": {
               "clickhouse": {
-                "const": true
+                "anyOf": [
+                  {
+                    "const": true
+                  },
+                  {
+                    "type": "object"
+                  }
+                ]
               }
             },
             "required": [
@@ -131,7 +196,14 @@
           "then": {
             "properties": {
               "postgres": {
-                "const": true
+                "anyOf": [
+                  {
+                    "const": true
+                  },
+                  {
+                    "type": "object"
+                  }
+                ]
               }
             },
             "required": [

package/index.d.ts

@@ -107,7 +107,7 @@ export type Prettify<T> = { [K in keyof T]: T[K] } & {};
 
 /**
  * Operator for filtering entity fields in getWhere queries.
- * Only fields with `@index` in the schema can be queried at runtime.
+ * Only `id` and fields with `@index` in the schema can be queried at runtime.
  */
 export type GetWhereOperator<T> = {
   /** Matches entities where the field equals the given value. */
@@ -128,7 +128,7 @@ export type GetWhereOperator<T> = {
  * Constructs a getWhere filter type from an entity type.
  * Each field can be filtered using {@link GetWhereOperator} (`_eq`, `_gt`, `_lt`, `_gte`, `_lte`, `_in`).
  *
- * Note: only fields with `@index` in the schema can be queried at runtime.
+ * Note: only `id` and fields with `@index` in the schema can be queried at runtime.
  * Attempting to filter on a non-indexed field will throw a descriptive error.
  */
 export type GetWhereFilter<E> = {
@@ -959,6 +959,144 @@ export type SvmOnSlotOptions<Config extends IndexerConfigTypes = GlobalConfig> =
   readonly where?: (args: SvmOnSlotWhereArgs<Config>) => SvmOnSlotWhereResult;
 };
 
+// ============== SVM onInstruction types ==============
+
+/** Borsh-decoded params 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 SvmInstructionParams = {
+  /** 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[];
+};
+
+/** Block context for a matched instruction. */
+export type SvmInstructionBlock = {
+  /** Slot this instruction's block was matched in. */
+  readonly slot: number;
+  readonly time: number;
+  /** Always empty for now — reserved for the future reorg-guard route. */
+  readonly hash: string;
+};
+
+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 delivered to an `onInstruction` handler.
+ *
+ * Carries the matched instruction's own fields (`programId`, `data`,
+ * `accounts`, discriminator prefixes, `params`) plus the program/instruction
+ * names, parent transaction, scoped logs, and block context. Parameterised
+ * over `Params` so the per-(program, instruction) overload of
+ * `onInstruction` can narrow `instruction.params` to the codegen-generated
+ * `{ args, accounts }` shape.
+ *
+ * `data` and discriminator prefixes are `0x`-prefixed hex strings; accounts
+ * are base58 strings. */
+export type SvmInstruction<
+  Params extends SvmInstructionParams = SvmInstructionParams,
+> = {
+  /** Program name as declared under `programs[].name` in `config.yaml`. */
+  readonly programName: string;
+  /** Instruction name as declared under `instructions[].name` in
+   * `config.yaml`. */
+  readonly instructionName: string;
+  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;
+  /** Borsh-decoded params. Present when a schema is configured and matched. */
+  readonly params?: Params;
+  /** 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 block: SvmInstructionBlock;
+};
+
+/** Arguments passed to handlers registered via `indexer.onInstruction`. */
+export type SvmOnInstructionHandlerArgs<
+  Config extends IndexerConfigTypes = GlobalConfig,
+  Instr extends SvmInstruction = SvmInstruction,
+> = {
+  readonly instruction: Instr;
+  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 `SvmInstructionParams`-compatible record. */
+type SvmParamsFromProgramTable<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[];
+    }
+  : SvmInstructionParams;
+
+/** 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
@@ -1136,7 +1274,14 @@ type FuelEcosystem<Config extends IndexerConfigTypes = GlobalConfig> =
       : never
     : never;
 
-// SVM ecosystem type — chains plus onSlot handler method. SVM has no onEvent yet.
+// Surfaced when an SVM indexer configures no `programs`, so there's no
+// instruction to register a handler for. Mirrors `CodegenRequiredHint`: the
+// string literal becomes the argument type, so any `onInstruction` call fails
+// with this text naming the fix.
+type SvmNoProgramsHint =
+  "Add at least one entry under `svm.programs` in config.yaml to register instruction handlers with onInstruction.";
+
+// 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 }
@@ -1160,7 +1305,42 @@ 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.
+                 * `instruction.params.args` and
+                 * `instruction.params.accounts` are typed from the
+                 * program's Borsh schema (Anchor IDL, bundled, or
+                 * hand-written `accounts`/`args` in YAML). `params` 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,
+                      SvmInstruction<SvmParamsFromProgramTable<Programs[P][I]>>
+                    >,
+                  ) => Promise<void>,
+                ) => void;
+              }
+            : {
+                /** No `programs` configured under `svm` in config.yaml, so
+                 * there's nothing to register an instruction handler for. The
+                 * rest parameter is typed as a string-literal hint so any call
+                 * site fails with a message naming the fix. */
+                readonly onInstruction: (
+                  ...hint: SvmNoProgramsHint[]
+                ) => void;
+              })
         : never
       : never
     : never;
@@ -1176,6 +1356,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.1.2",
+  "version": "3.2.0",
   "type": "module",
   "description": "A latency and sync speed optimized, developer friendly blockchain data indexer.",
   "bin": "./bin.mjs",
@@ -70,10 +70,10 @@
     "tsx": "4.21.0"
   },
   "optionalDependencies": {
-    "envio-linux-x64": "3.1.2",
-    "envio-linux-x64-musl": "3.1.2",
-    "envio-linux-arm64": "3.1.2",
-    "envio-darwin-x64": "3.1.2",
-    "envio-darwin-arm64": "3.1.2"
+    "envio-linux-x64": "3.2.0",
+    "envio-linux-x64-musl": "3.2.0",
+    "envio-linux-arm64": "3.2.0",
+    "envio-darwin-x64": "3.2.0",
+    "envio-darwin-arm64": "3.2.0"
   }
 }

package/src/Batch.res

@@ -207,7 +207,7 @@ let prepareBatch = (
     let prevBlockNumber = ref(chainBeforeBatch.progressBlockNumber)
     if chainBatchSize > 0 {
       for idx in 0 to chainBatchSize - 1 {
-        let item = fetchState.buffer->Belt.Array.getUnsafe(idx)
+        let item = fetchState.buffer->Array.getUnsafe(idx)
         let blockNumber = item->Internal.getItemBlockNumber
 
         // Every new block we should create a new checkpoint
@@ -243,7 +243,7 @@ let prepareBatch = (
         } else {
           let lastIndex = checkpointEventsProcessed->Array.length - 1
           checkpointEventsProcessed
-          ->Belt.Array.setUnsafe(
+          ->Array.setUnsafe(
             lastIndex,
             checkpointEventsProcessed->Array.getUnsafe(lastIndex) + 1,
           )

package/src/ChainFetcher.res

@@ -153,14 +153,14 @@ let make = (
     onBlockConfigs->Array.forEach(onBlockConfig => {
       if onBlockConfig.startBlock->Option.getOr(startBlock) < startBlock {
         JsError.throwWithMessage(
-          `The start block for onBlock handler "${onBlockConfig.name}" is less than the chain start block (${startBlock->Belt.Int.toString}). This is not supported yet.`,
+          `The start block for onBlock handler "${onBlockConfig.name}" is less than the chain start block (${startBlock->Int.toString}). This is not supported yet.`,
         )
       }
       switch endBlock {
       | Some(chainEndBlock) =>
         if onBlockConfig.endBlock->Option.getOr(chainEndBlock) > chainEndBlock {
           JsError.throwWithMessage(
-            `The end block for onBlock handler "${onBlockConfig.name}" is greater than the chain end block (${chainEndBlock->Belt.Int.toString}). This is not supported yet.`,
+            `The end block for onBlock handler "${onBlockConfig.name}" is greater than the chain end block (${chainEndBlock->Int.toString}). This is not supported yet.`,
           )
         }
       | None => ()
@@ -229,7 +229,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, rpc) {
+    | (None, None) =>
+      JsError.throwWithMessage(
+        `Chain ${chain->ChainMap.Chain.toChainId->Int.toString} has no SVM data source`,
+      )
+    | (None, Some(rpc)) => [Svm.makeRPCSource(~chain, ~rpc)]
+    | (Some(hypersyncUrl), _) =>
+      // HyperSync drives instruction sync. A configured RPC is ignored for now
+      // (RPC fallback isn't wired up yet).
+      let svmEventConfigs =
+        chainConfig.contracts
+        ->Array.flatMap(contract => contract.events)
+        ->(Utils.magic: array<Internal.eventConfig> => array<Internal.svmInstructionEventConfig>)
+      let apiToken = Env.envioApiToken
+      [
+        SvmHyperSyncSource.make({
+          chain,
+          endpointUrl: hypersyncUrl,
+          apiToken,
+          eventConfigs: svmEventConfigs,
+          clientTimeoutMillis: Env.hyperSyncClientTimeoutMillis,
+        }),
+      ]
+    }
   // For tests: use ready-to-use sources directly
   | Config.CustomSources(sources) => sources
   }

package/src/ChainFetcher.res.mjs

@@ -20,6 +20,7 @@ import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 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 SvmHyperSyncSource from "./sources/SvmHyperSyncSource.res.mjs";
 import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
 import * as SafeCheckpointTracking from "./SafeCheckpointTracking.res.mjs";
 
@@ -89,10 +90,10 @@ function make(chainConfig, indexingAddresses, startBlock, endBlock, firstEventBl
   if (onBlockConfigs !== undefined) {
     onBlockConfigs.forEach(onBlockConfig => {
       if (Stdlib_Option.getOr(onBlockConfig.startBlock, startBlock) < startBlock) {
-        Stdlib_JsError.throwWithMessage(`The start block for onBlock handler "` + onBlockConfig.name + `" is less than the chain start block (` + String(startBlock) + `). This is not supported yet.`);
+        Stdlib_JsError.throwWithMessage(`The start block for onBlock handler "` + onBlockConfig.name + `" is less than the chain start block (` + startBlock.toString() + `). This is not supported yet.`);
       }
       if (endBlock !== undefined && Stdlib_Option.getOr(onBlockConfig.endBlock, endBlock) > endBlock) {
-        return Stdlib_JsError.throwWithMessage(`The end block for onBlock handler "` + onBlockConfig.name + `" is greater than the chain end block (` + String(endBlock) + `). This is not supported yet.`);
+        return Stdlib_JsError.throwWithMessage(`The end block for onBlock handler "` + onBlockConfig.name + `" is greater than the chain end block (` + endBlock.toString() + `). This is not supported yet.`);
       }
     });
   }
@@ -132,7 +133,20 @@ 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 = [SvmHyperSyncSource.make({
+            chain: chain,
+            endpointUrl: hypersync,
+            apiToken: Env.envioApiToken,
+            eventConfigs: svmEventConfigs,
+            clientTimeoutMillis: Env.hyperSyncClientTimeoutMillis
+          })];
+      } else {
+        sources$1 = rpc !== undefined ? [Svm.makeRPCSource(chain, rpc, undefined)] : Stdlib_JsError.throwWithMessage(`Chain ` + chain.toString() + ` has no SVM data source`);
+      }
       break;
     case "CustomSources" :
       sources$1 = sources._0;