envio 3.1.1 → 3.2.0

package/src/Config.res.mjs

@@ -10,9 +10,7 @@ import * as Utils from "./Utils.res.mjs";
 import * as Address from "./Address.res.mjs";
 import * as ChainMap from "./ChainMap.res.mjs";
 import * as Internal from "./Internal.res.mjs";
-import * as Belt_Array from "@rescript/runtime/lib/es6/Belt_Array.js";
 import * as BigDecimal from "./bindings/BigDecimal.res.mjs";
-import * as Belt_Option from "@rescript/runtime/lib/es6/Belt_Option.js";
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
@@ -25,7 +23,7 @@ import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_excep
 let name = "envio_addresses";
 
 function makeId(chainId, address) {
-  return String(chainId) + "-" + address;
+  return chainId.toString() + "-" + address;
 }
 
 function getAddress(entity) {
@@ -41,14 +39,12 @@ let schema = S$RescriptSchema.schema(s => ({
   contract_name: s.m(S$RescriptSchema.string)
 }));
 
-let rowsSchema = S$RescriptSchema.array(schema);
-
 let table = Table.mkTable(name, undefined, [
-  Table.mkField("id", "String", S$RescriptSchema.string, undefined, undefined, undefined, true, undefined, undefined, undefined),
-  Table.mkField("chain_id", "Int32", S$RescriptSchema.int, undefined, undefined, undefined, undefined, undefined, undefined, undefined),
-  Table.mkField("registration_block", "Int32", S$RescriptSchema.int, undefined, undefined, undefined, undefined, undefined, undefined, undefined),
-  Table.mkField("registration_log_index", "Int32", S$RescriptSchema.int, undefined, undefined, undefined, undefined, undefined, undefined, undefined),
-  Table.mkField("contract_name", "String", S$RescriptSchema.string, undefined, undefined, undefined, undefined, undefined, undefined, undefined)
+  Table.mkField("id", "String", S$RescriptSchema.string, undefined, undefined, undefined, true, undefined, undefined, undefined, undefined, undefined),
+  Table.mkField("chain_id", "Int32", S$RescriptSchema.int, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined),
+  Table.mkField("registration_block", "Int32", S$RescriptSchema.int, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined),
+  Table.mkField("registration_log_index", "Int32", S$RescriptSchema.int, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined),
+  Table.mkField("contract_name", "String", S$RescriptSchema.string, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined, undefined)
 ], undefined);
 
 let entityConfig_storage = {
@@ -60,7 +56,6 @@ let entityConfig = {
   name: name,
   index: -1,
   schema: schema,
-  rowsSchema: rowsSchema,
   table: table,
   storage: entityConfig_storage
 };
@@ -71,7 +66,6 @@ let EnvioAddresses = {
   makeId: makeId,
   getAddress: getAddress,
   schema: schema,
-  rowsSchema: rowsSchema,
   table: table,
   entityConfig: entityConfig
 };
@@ -113,24 +107,48 @@ let publicConfigChainSchema = S$RescriptSchema.schema(s => ({
   contracts: s.m(S$RescriptSchema.option(S$RescriptSchema.dict(chainContractSchema)))
 }));
 
+let svmEventDescriptorSchema = S$RescriptSchema.schema(s => ({
+  discriminator: s.m(S$RescriptSchema.option(S$RescriptSchema.string)),
+  discriminatorByteLen: s.m(S$RescriptSchema.int),
+  includeTransaction: s.m(S$RescriptSchema.bool),
+  includeLogs: s.m(S$RescriptSchema.bool),
+  includeTokenBalances: s.m(S$RescriptSchema.bool),
+  accountFilters: s.m(S$RescriptSchema.option(S$RescriptSchema.array(S$RescriptSchema.schema(s => ({
+    position: s.m(S$RescriptSchema.int),
+    values: s.m(S$RescriptSchema.array(S$RescriptSchema.string))
+  }))))),
+  isInner: s.m(S$RescriptSchema.option(S$RescriptSchema.bool)),
+  accounts: s.m(S$RescriptSchema.option(S$RescriptSchema.array(S$RescriptSchema.string))),
+  args: s.m(S$RescriptSchema.option(S$RescriptSchema.json(false)))
+}));
+
+let svmAbiSchema = S$RescriptSchema.schema(s => ({
+  programId: s.m(S$RescriptSchema.string),
+  definedTypes: s.m(S$RescriptSchema.json(false)),
+  source: s.m(S$RescriptSchema.string)
+}));
+
 let contractEventItemSchema = S$RescriptSchema.schema(s => ({
   name: s.m(S$RescriptSchema.string),
   sighash: s.m(S$RescriptSchema.string),
   params: s.m(S$RescriptSchema.option(S$RescriptSchema.array(EventConfigBuilder.paramMetaSchema))),
   kind: s.m(S$RescriptSchema.option(S$RescriptSchema.string)),
   blockFields: s.m(S$RescriptSchema.option(S$RescriptSchema.array(Internal.evmBlockFieldSchema))),
-  transactionFields: s.m(S$RescriptSchema.option(S$RescriptSchema.array(Internal.evmTransactionFieldSchema)))
+  transactionFields: s.m(S$RescriptSchema.option(S$RescriptSchema.array(Internal.evmTransactionFieldSchema))),
+  svm: s.m(S$RescriptSchema.option(svmEventDescriptorSchema))
 }));
 
 let contractConfigSchema = S$RescriptSchema.schema(s => ({
   abi: s.m(S$RescriptSchema.json(false)),
   handler: s.m(S$RescriptSchema.option(S$RescriptSchema.string)),
-  events: s.m(S$RescriptSchema.option(S$RescriptSchema.array(contractEventItemSchema)))
+  events: s.m(S$RescriptSchema.option(S$RescriptSchema.array(contractEventItemSchema))),
+  svmAbi: s.m(S$RescriptSchema.option(svmAbiSchema))
 }));
 
 let publicConfigEcosystemSchema = S$RescriptSchema.schema(s => ({
   chains: s.m(S$RescriptSchema.dict(publicConfigChainSchema)),
-  contracts: s.m(S$RescriptSchema.option(S$RescriptSchema.dict(contractConfigSchema)))
+  contracts: s.m(S$RescriptSchema.option(S$RescriptSchema.dict(contractConfigSchema))),
+  programs: s.m(S$RescriptSchema.option(S$RescriptSchema.dict(contractConfigSchema)))
 }));
 
 let publicConfigEvmSchema = S$RescriptSchema.schema(s => ({
@@ -158,6 +176,8 @@ let derivedFieldSchema = S$RescriptSchema.schema(s => ({
 
 let propertySchema = S$RescriptSchema.schema(s => ({
   name: s.m(S$RescriptSchema.string),
+  postgresDbName: s.m(S$RescriptSchema.option(S$RescriptSchema.string)),
+  clickhouseDbName: s.m(S$RescriptSchema.option(S$RescriptSchema.string)),
   type: s.m(S$RescriptSchema.string),
   isNullable: s.m(S$RescriptSchema.option(S$RescriptSchema.bool)),
   isArray: s.m(S$RescriptSchema.option(S$RescriptSchema.bool)),
@@ -299,7 +319,7 @@ function parseEntitiesFromJson(entitiesJson, enumConfigsByName, globalStorage) {
     let entityName = entityJson.name;
     let fields = entityJson.properties.map(prop => {
       let match = getFieldTypeAndSchema(prop, enumConfigsByName);
-      return Table.mkField(prop.name, match[0], match[1], undefined, match[3], match[2], prop.name === "id", match[4], prop.linkedEntity, prop.description);
+      return Table.mkField(prop.name, match[0], match[1], undefined, match[3], match[2], prop.name === "id", match[4], prop.linkedEntity, prop.description, prop.postgresDbName, prop.clickhouseDbName);
     });
     let derivedFields = Stdlib_Option.getOr(entityJson.derivedFields, []).map(df => Table.mkDerivedFromField(df.fieldName, df.derivedFromEntity, df.derivedFromField, df.description));
     let compositeIndices = Stdlib_Option.getOr(entityJson.compositeIndices, []).map(ci => ci.map(f => ({
@@ -307,13 +327,19 @@ function parseEntitiesFromJson(entitiesJson, enumConfigsByName, globalStorage) {
       direction: f.direction === "Asc" ? "Asc" : "Desc"
     })));
     let table = Table.mkTable(entityName, compositeIndices, fields.concat(derivedFields), entityJson.description);
+    let getApiFieldName = prop => {
+      let match = prop.linkedEntity;
+      if (match !== undefined) {
+        return prop.name + "_id";
+      } else {
+        return prop.name;
+      }
+    };
     let schema = S$RescriptSchema.schema(s => {
       let dict = {};
       entityJson.properties.forEach(prop => {
         let match = getFieldTypeAndSchema(prop, enumConfigsByName);
-        let match$1 = prop.linkedEntity;
-        let dbFieldName = match$1 !== undefined ? prop.name + "_id" : prop.name;
-        dict[dbFieldName] = s.m(match[1]);
+        dict[getApiFieldName(prop)] = s.m(match[1]);
       });
       return dict;
     });
@@ -335,7 +361,6 @@ function parseEntitiesFromJson(entitiesJson, enumConfigsByName, globalStorage) {
       name: entityName,
       index: index,
       schema: schema,
-      rowsSchema: S$RescriptSchema.array(schema),
       table: table,
       storage: storage
     };
@@ -415,6 +440,7 @@ function fromPublic(publicConfigJson) {
   let lowercaseAddresses = evm !== undefined ? Stdlib_Option.getOr(Primitive_option.valFromOption(evm).addressFormat, "checksum") === "lowercase" : false;
   let match$4 = publicConfig.evm;
   let match$5 = publicConfig.fuel;
+  let match$6 = publicConfig.svm;
   let publicContractsConfig;
   switch (ecosystemName) {
     case "evm" :
@@ -424,38 +450,43 @@ function fromPublic(publicConfigJson) {
       publicContractsConfig = match$5 !== undefined ? Primitive_option.valFromOption(match$5).contracts : undefined;
       break;
     case "svm" :
-      publicContractsConfig = undefined;
+      publicContractsConfig = match$6 !== undefined ? Primitive_option.valFromOption(match$6).programs : undefined;
       break;
   }
   let evm$1 = publicConfig.evm;
-  let match$6;
+  let match$7;
   if (evm$1 !== undefined) {
     let evm$2 = Primitive_option.valFromOption(evm$1);
-    match$6 = [
+    match$7 = [
       new Set(EventConfigBuilder.alwaysIncludedBlockFields.concat(Stdlib_Option.getOr(evm$2.globalBlockFields, []))),
       new Set(Stdlib_Option.getOr(evm$2.globalTransactionFields, []))
     ];
   } else {
-    match$6 = [
+    match$7 = [
       new Set(EventConfigBuilder.alwaysIncludedBlockFields),
       new Set()
     ];
   }
-  let globalTransactionFieldsSet = match$6[1];
-  let globalBlockFieldsSet = match$6[0];
+  let globalTransactionFieldsSet = match$7[1];
+  let globalBlockFieldsSet = match$7[0];
   let contractDataByName = {};
   if (publicContractsConfig !== undefined) {
     Object.entries(publicContractsConfig).forEach(param => {
       let contractConfig = param[1];
       let capitalizedName = Utils.$$String.capitalize(param[0]);
       let abi = contractConfig.abi;
+      let events = contractConfig.events;
+      let eventSignatures = events !== undefined ? events.map(eventItem => eventItem.sighash) : [];
       contractDataByName[capitalizedName] = {
         abi: abi,
-        events: contractConfig.events
+        eventSignatures: eventSignatures,
+        events: contractConfig.events,
+        svmAbi: contractConfig.svmAbi
       };
     });
   }
-  let buildContractEvents = (contractName, events, abi, chainId, startBlock) => {
+  let buildContractEvents = (contractName, events, abi, chainId, startBlock, addresses, svmDefinedTypesOpt) => {
+    let svmDefinedTypes = svmDefinedTypesOpt !== undefined ? svmDefinedTypesOpt : null;
     if (events !== undefined) {
       return events.map(eventItem => {
         let eventName = eventItem.name;
@@ -463,17 +494,27 @@ function fromPublic(publicConfigJson) {
         let params = Stdlib_Option.getOr(eventItem.params, []);
         let kind = eventItem.kind;
         switch (ecosystemName) {
+          case "evm" :
+            return EventConfigBuilder.buildEvmEventConfig(contractName, eventName, sighash, params, false, undefined, undefined, undefined, chainId, ecosystem.onEventBlockFilterSchema, eventItem.blockFields, eventItem.transactionFields, startBlock, Primitive_option.some(globalBlockFieldsSet), Primitive_option.some(globalTransactionFieldsSet));
           case "fuel" :
             if (kind !== undefined) {
               return EventConfigBuilder.buildFuelEventConfig(contractName, eventName, kind, sighash, abi, false, undefined, undefined, startBlock);
             } else {
               return Stdlib_JsError.throwWithMessage(`Fuel event ` + contractName + `.` + eventName + ` is missing "kind" in internal config`);
             }
-          case "evm" :
           case "svm" :
-            break;
+            let len = addresses.length;
+            let programId = len !== 1 ? (
+                len !== 0 ? Stdlib_JsError.throwWithMessage(`SVM program ` + contractName + ` on chain ` + chainId.toString() + ` has multiple addresses; a program is uniquely identified by a single program_id`) : Stdlib_JsError.throwWithMessage(`SVM program ` + contractName + ` on chain ` + chainId.toString() + ` is missing a program_id`)
+              ) : addresses[0];
+            let s = eventItem.svm;
+            let svm = s !== undefined ? Primitive_option.valFromOption(s) : Stdlib_JsError.throwWithMessage(`SVM instruction ` + contractName + `.` + eventName + ` is missing the "svm" descriptor in internal config`);
+            let accountFilters = Stdlib_Option.getOr(svm.accountFilters, []).map(group => group.map(af => ({
+              position: af.position,
+              values: af.values
+            })));
+            return EventConfigBuilder.buildSvmInstructionEventConfig(contractName, eventName, programId, svm.discriminator, svm.discriminatorByteLen, svm.includeTransaction, svm.includeLogs, svm.includeTokenBalances, accountFilters, svm.isInner, false, undefined, undefined, Stdlib_Option.getOr(svm.accounts, []), Stdlib_Option.getOr(svm.args, null), svmDefinedTypes, startBlock);
         }
-        return EventConfigBuilder.buildEvmEventConfig(contractName, eventName, sighash, params, false, undefined, undefined, undefined, chainId, ecosystem.onEventBlockFilterSchema, eventItem.blockFields, eventItem.transactionFields, startBlock, Primitive_option.some(globalBlockFieldsSet), Primitive_option.some(globalTransactionFieldsSet));
       });
     } else {
       return [];
@@ -510,9 +551,10 @@ function fromPublic(publicConfigJson) {
       let contractData = param[1];
       let capitalizedName = param[0];
       let chainContract = chainContracts[capitalizedName];
-      let addresses = Stdlib_Option.getOr(Stdlib_Option.flatMap(chainContract, cc => cc.addresses), []).map(parseAddress);
+      let rawAddresses = Stdlib_Option.getOr(Stdlib_Option.flatMap(chainContract, cc => cc.addresses), []);
+      let addresses = rawAddresses.map(parseAddress);
       let startBlock = Stdlib_Option.flatMap(chainContract, cc => cc.startBlock);
-      let events = buildContractEvents(capitalizedName, contractData.events, contractData.abi, chainId, startBlock);
+      let events = buildContractEvents(capitalizedName, contractData.events, contractData.abi, chainId, startBlock, rawAddresses, Stdlib_Option.getOr(Stdlib_Option.map(contractData.svmAbi, a => a.definedTypes), null));
       return {
         name: capitalizedName,
         abi: contractData.abi,
@@ -521,6 +563,18 @@ function fromPublic(publicConfigJson) {
         startBlock: startBlock
       };
     });
+    let contractNameByAddress = {};
+    contracts.forEach(contract => {
+      contract.addresses.forEach(address => {
+        let existingContractName = contractNameByAddress[address];
+        if (existingContractName !== undefined) {
+          return Stdlib_JsError.throwWithMessage(existingContractName === contract.name ? `Address ` + address + ` is listed multiple times for the contract ` + contract.name + ` on chain ` + chainId.toString() + `. Please remove the duplicate from your config.` : `Address ` + address + ` on chain ` + chainId.toString() + ` is configured for multiple contracts: ` + existingContractName + ` and ` + contract.name + `. Indexing the same address with multiple contract definitions is not supported. Please define the events on a single contract definition instead.`);
+        } else {
+          contractNameByAddress[address] = contract.name;
+          return;
+        }
+      });
+    });
     let sourceConfig;
     switch (ecosystemName) {
       case "evm" :
@@ -565,11 +619,16 @@ function fromPublic(publicConfigJson) {
           }) : Stdlib_JsError.throwWithMessage(`Chain ` + chainName + ` is missing hypersync endpoint in config`);
         break;
       case "svm" :
+        let hypersync$1 = publicChainConfig.hypersync;
         let rpc = publicChainConfig.rpc;
-        sourceConfig = rpc !== undefined ? ({
-            TAG: "SvmSourceConfig",
-            rpc: rpc
-          }) : Stdlib_JsError.throwWithMessage(`Chain ` + chainName + ` is missing rpc endpoint in config`);
+        if (Stdlib_Option.isNone(hypersync$1) && Stdlib_Option.isNone(rpc)) {
+          Stdlib_JsError.throwWithMessage(`Chain ` + chainName + ` is missing a data source: provide either an rpc endpoint or an experimental hypersync config`);
+        }
+        sourceConfig = {
+          TAG: "SvmSourceConfig",
+          hypersync: hypersync$1,
+          rpc: rpc
+        };
         break;
     }
     let tmp;
@@ -663,7 +722,7 @@ function getEventConfig(config, contractName, eventName, chainId) {
     if (acc !== undefined) {
       return acc;
     } else {
-      return Belt_Option.flatMap(chain.contracts.find(c => c.name === contractName), contract => contract.events.find(e => e.name === eventName));
+      return Stdlib_Option.flatMap(chain.contracts.find(c => c.name === contractName), contract => contract.events.find(e => e.name === eventName));
     }
   });
 }
@@ -782,8 +841,8 @@ function diffPaths(stored, current) {
         let maxLen = Math.max(s.length, c.length);
         for (let i = 0; i < maxLen; ++i) {
           let p = prefix + `[` + i.toString() + `]`;
-          let match = Belt_Array.get(s, i);
-          let match$1 = Belt_Array.get(c, i);
+          let match = s[i];
+          let match$1 = c[i];
           if (match !== undefined && match$1 !== undefined) {
             go(match, match$1, p);
           } else {
@@ -883,7 +942,7 @@ function diffPaths(stored, current) {
     if (firstHit !== undefined) {
       runTier(firstHit);
     } else {
-      let knownSet = new Set(Belt_Array.concatMany(tiers));
+      let knownSet = new Set(tiers.flat());
       runTier(Array.from(new Set(Object.keys(stored).concat(Object.keys(current)))).filter(k => !knownSet.has(k)).toSorted(Primitive_string.compare).filter(topKeyDiffers));
     }
   } else {
@@ -930,6 +989,8 @@ export {
   rpcConfigSchema,
   chainContractSchema,
   publicConfigChainSchema,
+  svmEventDescriptorSchema,
+  svmAbiSchema,
   contractEventItemSchema,
   contractConfigSchema,
   publicConfigEcosystemSchema,

package/src/Core.res

@@ -1,19 +1,25 @@
 // Resolution order:
-//   1. Production: require("envio-{os}-{arch}") — platform-specific npm package
-//   2. Dev build:  find repo → cargo build --lib → load from target/debug/
+//   1. Production: require("envio-{os}-{arch}") - platform-specific npm package
+//   2. Dev build:  find repo -> cargo build --lib -> load from target/debug/
 
 // NAPI encodes Rust `Option<T>` as `null | T` (never `undefined`), so the
 // tighter `Null.t` captures the exact boundary shape.
-type hypersyncClientCtor
-type decoderCtor
+type evmHypersyncClientCtor
+type evmRpcClientCtor
+type evmDecoderCtor
+type svmHypersyncClientCtor
 
 type addon = {
   getConfigJson: (~configPath: Null.t<string>, ~directory: Null.t<string>) => string,
   runCli: (~args: array<string>, ~envioPackageDir: Null.t<string>) => promise<Null.t<string>>,
-  @as("HypersyncClient")
-  hypersyncClient: hypersyncClientCtor,
-  @as("Decoder")
-  decoder: decoderCtor,
+  @as("EvmHypersyncClient")
+  evmHypersyncClient: evmHypersyncClientCtor,
+  @as("EvmRpcClient")
+  evmRpcClient: evmRpcClientCtor,
+  @as("EvmDecoder")
+  evmDecoder: evmDecoderCtor,
+  @as("SvmHypersyncClient")
+  svmHypersyncClient: svmHypersyncClientCtor,
 }
 
 @module("node:module") external createRequire: string => {..} = "createRequire"
@@ -122,8 +128,8 @@ let loadAddon = () => {
   }
 
   // Only swallow MODULE_NOT_FOUND (the optional package isn't installed on
-  // this host). Any other failure — corrupt .node, ABI mismatch, dlopen
-  // error — is a real load failure and must surface.
+  // this host). Any other failure - corrupt .node, ABI mismatch, dlopen
+  // error - is a real load failure and must surface.
   let rec tryRequire = i =>
     switch candidates[i] {
     | None => None

package/src/Ecosystem.res

@@ -7,9 +7,6 @@ type t = {
   blockNumberName: string,
   blockTimestampName: string,
   blockHashName: string,
-  getNumber: Internal.eventBlock => int,
-  getTimestamp: Internal.eventBlock => int,
-  getId: Internal.eventBlock => string,
   cleanUpRawEventFieldsInPlace: JSON.t => unit,
   /** Method name that the block handler is exposed under on the public
       `indexer` object — `"onBlock"` for chain-based ecosystems, `"onSlot"`

package/src/Env.res

@@ -15,7 +15,7 @@ let maxPartitionConcurrency =
 // unwritten batch items) the store holds before processing waits for the write
 // cycle to catch up.
 let inMemoryObjectsTarget =
-  envSafe->EnvSafe.get("ENVIO_IN_MEMORY_OBJECTS_TARGET", S.int, ~fallback=100_000)->Belt.Int.toFloat
+  envSafe->EnvSafe.get("ENVIO_IN_MEMORY_OBJECTS_TARGET", S.int, ~fallback=100_000)->Int.toFloat
 
 // FIXME: This broke HS grafana dashboard. Should investigate it later. Maybe we should use :: as a default value?
 // We want to be able to set it to 0.0.0.0
@@ -86,7 +86,7 @@ Logging.setLogger(
     ~logStrategy,
     ~logFilePath,
     ~defaultFileLogLevel,
-    ~userLogLevel=userLogLevel->Belt.Option.getWithDefault(#info),
+    ~userLogLevel=userLogLevel->Option.getOr(#info),
   ),
 )
 

package/src/Env.res.mjs

@@ -3,7 +3,7 @@
 import * as EnvSafe from "./EnvSafe.res.mjs";
 import * as Logging from "./Logging.res.mjs";
 import * as Postgres from "./bindings/Postgres.res.mjs";
-import * as Belt_Option from "@rescript/runtime/lib/es6/Belt_Option.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as HyperSyncClient from "./sources/HyperSyncClient.res.mjs";
 import * as S$RescriptSchema from "rescript-schema/src/S.res.mjs";
@@ -71,7 +71,7 @@ let logStrategy = EnvSafe.get(envSafe, "LOG_STRATEGY", S$RescriptSchema.$$enum([
   "both-prettyconsole"
 ]), undefined, "console-pretty", undefined, undefined);
 
-Logging.setLogger(Logging.makeLogger(logStrategy, logFilePath, defaultFileLogLevel, Belt_Option.getWithDefault(userLogLevel, "info")));
+Logging.setLogger(Logging.makeLogger(logStrategy, logFilePath, defaultFileLogLevel, Stdlib_Option.getOr(userLogLevel, "info")));
 
 let host = EnvSafe.get(envSafe, "ENVIO_PG_HOST", S$RescriptSchema.string, undefined, undefined, "localhost", undefined);
 

package/src/Envio.res

@@ -20,6 +20,105 @@ type svmOnSlotArgs<'context> = {
   context: 'context,
 }
 
+/** Borsh-decoded instruction view. Present whenever a `ProgramSchema` was
+ attached to the program (bundled schema, Anchor IDL, or hand-written YAML
+ `accounts`/`args`). Absent (`None`) when no schema applied or the
+ discriminator didn't match any registered instruction. */
+type svmInstructionParams = {
+  /** Schema-declared instruction name (matches the codegen module suffix). */
+  name: string,
+  /** Borsh-decoded args. `JSON.Object({})` for no-arg instructions
+   (e.g. `VerifyCollection`). POC types this as raw `JSON.t`; cast at the
+   handler with `(json :> MyArgsType)` until typed codegen lands. */
+  args: JSON.t,
+  /** Named accounts in schema order. Keys are exactly the schema-declared
+   names; values are base58 pubkey strings. */
+  accounts: dict<string>,
+  /** Accounts beyond the schema's named list (Anchor `remaining_accounts`,
+   IDL drift). `[]` when counts match. */
+  extraAccounts: array<string>,
+}
+
+type svmTokenBalance = {
+  account?: SvmTypes.Pubkey.t,
+  mint?: SvmTypes.Pubkey.t,
+  owner?: SvmTypes.Pubkey.t,
+  preAmount?: string,
+  postAmount?: string,
+}
+
+type svmTransaction = {
+  signatures: array<string>,
+  feePayer?: SvmTypes.Pubkey.t,
+  success?: bool,
+  err?: string,
+  fee?: bigint,
+  computeUnitsConsumed?: bigint,
+  accountKeys: array<SvmTypes.Pubkey.t>,
+  recentBlockhash?: string,
+  version?: string,
+  tokenBalances?: array<svmTokenBalance>,
+}
+
+type svmLog = {
+  kind: string,
+  message: string,
+}
+
+/** Block context for a matched instruction. `time`/`hash` follow the
+ EVM/Fuel field names so the shared `Ecosystem.t` getters in `Svm.res` read
+ them uniformly. */
+type svmInstructionBlock = {
+  /** Slot this instruction's block was matched in. */
+  slot: int,
+  /** Unix block time (seconds). `0` when HyperSync didn't return a block
+   for this instruction's slot. */
+  time: int,
+  /** Block hash. Currently always empty — populated by the future
+   reorg-guard `queryBlockHash(slot)` route. */
+  hash: string,
+}
+
+/** The per-instruction payload handlers receive as their `instruction`
+ argument. Carries the matched instruction's own fields plus the
+ program/instruction names, parent transaction, scoped logs, and block. */
+type svmInstruction = {
+  /** Program name as declared under `programs[].name` in `config.yaml`. */
+  programName: string,
+  /** Instruction name as declared under `instructions[].name` in
+   `config.yaml`. */
+  instructionName: string,
+  programId: SvmTypes.Pubkey.t,
+  /** Raw instruction bytes as `0x`-prefixed hex. */
+  data: string,
+  accounts: array<SvmTypes.Pubkey.t>,
+  /** Path through the call tree: `[outerIndex]` for top-level instructions,
+   appended child indices for inner CPI calls. */
+  instructionAddress: array<int>,
+  isInner: bool,
+  /** Discriminator prefixes pre-extracted by HyperSync. Each is `Some` only
+   when the underlying instruction is at least that long. */
+  d1?: string,
+  d2?: string,
+  d4?: string,
+  d8?: string,
+  /** Borsh-decoded params view. See [[svmInstructionParams]]. */
+  params?: svmInstructionParams,
+  /** Parent transaction. Absent when the per-instruction
+   `include_transaction` flag is `false`. */
+  transaction?: svmTransaction,
+  /** Program log entries scoped to this instruction. Absent when the
+   per-instruction `include_logs` flag is `false`. */
+  logs?: array<svmLog>,
+  block: svmInstructionBlock,
+}
+
+/** Arguments passed to handlers registered via `indexer.onInstruction`. */
+type svmOnInstructionArgs<'context> = {
+  instruction: svmInstruction,
+  context: 'context,
+}
+
 // Internal-only type for the `indexer.onBlock` (and SVM `onSlot`) `where`
 // callback argument. The canonical TypeScript shape lives in
 // `packages/envio/index.d.ts`; the ReScript declaration here is free to
@@ -216,7 +315,7 @@ module TestHelpers = {
         "0xbDA5747bFD65F08deb54cb465eB87D40e51B197E",
         "0xdD2FD4581271e230360230F9337D5c0430Bf44C0",
         "0x8626f6940E2eb28930eFb4CeF49B2d1F2C9C1199",
-      ]->Belt.Array.map(Address.Evm.fromStringOrThrow)
-    let defaultAddress = mockAddresses->Belt.Array.getUnsafe(0)
+      ]->Array.map(Address.Evm.fromStringOrThrow)
+    let defaultAddress = mockAddresses->Array.getUnsafe(0)
   }
 }

package/src/Envio.res.mjs

@@ -3,7 +3,6 @@
 import * as Address from "./Address.res.mjs";
 import * as Process from "process";
 import * as Internal from "./Internal.res.mjs";
-import * as Belt_Array from "@rescript/runtime/lib/es6/Belt_Array.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as S$RescriptSchema from "rescript-schema/src/S.res.mjs";
 
@@ -67,7 +66,7 @@ function isNonInteractive() {
   }
 }
 
-let mockAddresses = Belt_Array.map([
+let mockAddresses = [
   "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266",
   "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
   "0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC",
@@ -88,7 +87,7 @@ let mockAddresses = Belt_Array.map([
   "0xbDA5747bFD65F08deb54cb465eB87D40e51B197E",
   "0xdD2FD4581271e230360230F9337D5c0430Bf44C0",
   "0x8626f6940E2eb28930eFb4CeF49B2d1F2C9C1199"
-], Address.Evm.fromStringOrThrow);
+].map(Address.Evm.fromStringOrThrow);
 
 let defaultAddress = mockAddresses[0];
 

package/src/EventConfigBuilder.res

@@ -386,6 +386,58 @@ let buildEvmEventConfig = (
 
 // ============== Build Fuel event config ==============
 
+let buildSvmInstructionEventConfig = (
+  ~contractName: string,
+  ~instructionName: string,
+  ~programId: SvmTypes.Pubkey.t,
+  ~discriminator: option<string>,
+  ~discriminatorByteLen: int,
+  ~includeTransaction: bool,
+  ~includeLogs: bool,
+  ~includeTokenBalances: bool,
+  ~accountFilters: array<Internal.svmAccountFilterGroup>,
+  ~isInner: option<bool>,
+  ~isWildcard: bool,
+  ~handler: option<Internal.handler>,
+  ~contractRegister: option<Internal.contractRegister>,
+  ~accounts: array<string>=[],
+  ~args: JSON.t=JSON.Null,
+  ~definedTypes: JSON.t=JSON.Null,
+  ~startBlock: option<int>=?,
+): Internal.svmInstructionEventConfig => {
+  let paramsSchema =
+    S.json(~validate=false)
+    ->Utils.Schema.coerceToJsonPgType
+    ->(Utils.magic: S.t<JSON.t> => S.t<Internal.eventParams>)
+  {
+    id: switch discriminator {
+    | Some(d) => d
+    | None => "none"
+    },
+    name: instructionName,
+    contractName,
+    isWildcard,
+    handler,
+    contractRegister,
+    paramsRawEventSchema: paramsSchema,
+    simulateParamsSchema: paramsSchema,
+    filterByAddresses: false,
+    dependsOnAddresses: !isWildcard,
+    startBlock,
+    programId,
+    discriminator,
+    discriminatorByteLen,
+    includeTransaction,
+    includeLogs,
+    includeTokenBalances,
+    accountFilters,
+    isInner,
+    accounts,
+    args,
+    definedTypes,
+  }
+}
+
 let buildFuelEventConfig = (
   ~contractName: string,
   ~eventName: string,