envio 3.0.0-alpha.2 → 3.0.0-alpha.20

package/fuel.schema.json

@@ -15,10 +15,6 @@
       "description": "Name of the project",
       "type": "string"
     },
-    "ecosystem": {
-      "description": "Ecosystem of the project.",
-      "$ref": "#/$defs/EcosystemTag"
-    },
     "schema": {
       "description": "Custom path to schema.graphql file",
       "type": [
@@ -33,6 +29,26 @@
         "null"
       ]
     },
+    "handlers": {
+      "description": "Optional relative path to handlers directory for auto-loading. Defaults to 'src/handlers' if not specified.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "full_batch_size": {
+      "description": "Target number of events to be processed per batch. Set it to smaller number if you have many Effect API calls which are slow to resolve and can't be batched. (Default: 5000)",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint64",
+      "minimum": 0
+    },
+    "ecosystem": {
+      "description": "Ecosystem of the project.",
+      "$ref": "#/$defs/EcosystemTag"
+    },
     "contracts": {
       "description": "Global contract definitions that must contain all definitions except addresses. You can share a single handler/abi/event definitions for contracts across multiple chains.",
       "type": [
@@ -47,7 +63,7 @@
       "description": "Configuration of the blockchain chains that the project is deployed on.",
       "type": "array",
       "items": {
-        "$ref": "#/$defs/Network"
+        "$ref": "#/$defs/Chain"
       }
     },
     "raw_events": {
@@ -56,13 +72,6 @@
         "boolean",
         "null"
       ]
-    },
-    "handlers": {
-      "description": "Optional relative path to handlers directory for auto-loading. Defaults to 'src/handlers' if not specified.",
-      "type": [
-        "string",
-        "null"
-      ]
     }
   },
   "additionalProperties": false,
@@ -152,11 +161,11 @@
         "call"
       ]
     },
-    "Network": {
+    "Chain": {
       "type": "object",
       "properties": {
         "id": {
-          "description": "Public chain/network id",
+          "description": "Public chain id",
           "type": "integer",
           "format": "uint64",
           "minimum": 0
@@ -187,19 +196,39 @@
             }
           ]
         },
+        "max_reorg_depth": {
+          "description": "The number of blocks from the head that the indexer should account for in case of reorgs.",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint32",
+          "minimum": 0
+        },
+        "block_lag": {
+          "description": "The number of blocks behind the chain head that the indexer should lag. Useful for avoiding reorg issues by indexing slightly behind the tip.",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint32",
+          "minimum": 0
+        },
         "contracts": {
-          "description": "All the contracts that should be indexed on the given network",
-          "type": "array",
+          "description": "All the contracts that should be indexed on the given chain",
+          "type": [
+            "array",
+            "null"
+          ],
           "items": {
-            "$ref": "#/$defs/NetworkContract_for_ContractConfig"
+            "$ref": "#/$defs/ChainContract_for_ContractConfig"
           }
         }
       },
       "additionalProperties": false,
       "required": [
         "id",
-        "start_block",
-        "contracts"
+        "start_block"
       ]
     },
     "HyperfuelConfig": {
@@ -215,7 +244,7 @@
         "url"
       ]
     },
-    "NetworkContract_for_ContractConfig": {
+    "ChainContract_for_ContractConfig": {
       "type": "object",
       "properties": {
         "name": {
@@ -227,7 +256,7 @@
           "$ref": "#/$defs/Addresses"
         },
         "start_block": {
-          "description": "The block at which the indexer should start ingesting data for this specific contract. If not specified, uses the network start_block. Can be greater than the network start_block for more specific indexing.",
+          "description": "The block at which the indexer should start ingesting data for this specific contract. If not specified, uses the chain start_block. Can be greater than the chain start_block for more specific indexing.",
           "type": [
             "integer",
             "null"

package/index.d.ts

@@ -8,10 +8,45 @@ export type {
   rateLimit as RateLimit,
   blockEvent as BlockEvent,
   fuelBlockEvent as FuelBlockEvent,
+  svmOnBlockArgs as SvmOnBlockArgs,
   onBlockArgs as OnBlockArgs,
   onBlockOptions as OnBlockOptions,
 } from "./src/Envio.gen.ts";
-export type { EffectCaller } from "./src/Types.ts";
+import type { Address } from "./src/Types.ts";
+export type { EffectCaller, Address } from "./src/Types.ts";
+
+/** Utility type to expand/flatten complex types for better IDE display. */
+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.
+ */
+export type WhereOperator<T> = {
+  /** Matches entities where the field equals the given value. */
+  readonly _eq?: T;
+  /** Matches entities where the field is greater than the given value. */
+  readonly _gt?: T;
+  /** Matches entities where the field is less than the given value. */
+  readonly _lt?: T;
+  /** Matches entities where the field is greater than or equal to the given value. */
+  readonly _gte?: T;
+  /** Matches entities where the field is less than or equal to the given value. */
+  readonly _lte?: T;
+  /** Matches entities where the field equals any of the given values. */
+  readonly _in?: readonly T[];
+};
+
+/**
+ * Constructs a getWhere filter type from an entity type.
+ * Each field can be filtered using {@link WhereOperator} (`_eq`, `_gt`, `_lt`, `_gte`, `_lte`, `_in`).
+ *
+ * Note: only 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> = {
+  [K in keyof E]?: WhereOperator<E[K]>;
+};
 
 import type {
   effect as Effect,
@@ -108,6 +143,10 @@ export declare namespace S {
   export type Input<T> = Sury.Input<T>;
   export type Schema<Output, Input = unknown> = Sury.Schema<Output, Input>;
   export const string: typeof Sury.string;
+  export const address: Sury.Schema<Address, Address>;
+  // export const evmChainId: Sury.Schema<EvmChainId, EvmChainId>;
+  // export const fuelChainId: Sury.Schema<FuelChainId, FuelChainId>;
+  // export const svmChainId: Sury.Schema<SvmChainId, SvmChainId>;
   export const jsonString: typeof Sury.jsonString;
   export const boolean: typeof Sury.boolean;
   export const int32: typeof Sury.int32;
@@ -137,3 +176,460 @@ export declare namespace S {
   export const assertOrThrow: typeof Sury.assertOrThrow;
   export const parseOrThrow: typeof Sury.parseOrThrow;
 }
+
+// ============== Indexer Config (Module Augmentation) ==============
+
+/**
+ * Configuration interface for the indexer.
+ * This interface is augmented by generated/envio.d.ts with project-specific config using typeof config.
+ *
+ * @example
+ * // In generated/envio.d.ts:
+ * declare module "envio" {
+ *   interface Global {
+ *     config: typeof config;
+ *   }
+ * }
+ */
+export interface Global {}
+
+/**
+ * Shape of the indexer configuration.
+ * Will be used internally for defineConfig.
+ * Currently should match the internal.config.json structure.
+ */
+type IndexerConfig = {
+  /** The indexer name. */
+  name: string;
+  /** The indexer description. */
+  description?: string;
+  /** Path to handlers directory for auto-loading (default: "src/handlers"). */
+  handlers?: string;
+  /** Multichain mode: ordered or unordered (default: "unordered"). */
+  multichain?: "ordered" | "unordered";
+  /** Target batch size for event processing (default: 5000). */
+  fullBatchSize?: number;
+  /** Whether to rollback on chain reorg (default: true). */
+  rollbackOnReorg?: boolean;
+  /** Whether to save full entity history (default: false). */
+  saveFullHistory?: boolean;
+  /** Whether raw events are enabled (default: false). */
+  rawEvents?: boolean;
+  /** EVM ecosystem configuration. */
+  evm?: {
+    /** Chain configurations keyed by chain name. */
+    chains: Record<string, EvmChainConfig>;
+    /** Contract configurations keyed by contract name. */
+    contracts?: Record<string, EvmContractConfig>;
+    /** Address format (default: "checksum"). */
+    addressFormat?: "lowercase" | "checksum";
+  };
+  /** Fuel ecosystem configuration. */
+  fuel?: {
+    /** Chain configurations keyed by chain name. */
+    chains: Record<string, FuelChainConfig>;
+    /** Contract configurations keyed by contract name. */
+    contracts?: Record<string, FuelContractConfig>;
+  };
+  /** SVM ecosystem configuration. */
+  svm?: {
+    /** Chain configurations keyed by chain name. */
+    chains: Record<string, SvmChainConfig>;
+  };
+};
+
+// ============== Contract Types ==============
+
+/** EVM contract configuration. */
+type EvmContractConfig = {
+  /** The contract ABI. */
+  readonly abi: unknown;
+};
+
+/** Fuel contract configuration. */
+type FuelContractConfig = {
+  /** The contract ABI. */
+  readonly abi: unknown;
+};
+
+// ============== EVM Types ==============
+
+/** EVM chain configuration (for IndexerConfig). */
+type EvmChainConfig<Id extends number = number> = {
+  /** The chain ID. */
+  readonly id: Id;
+  /** The block number indexing starts from. */
+  readonly startBlock: number;
+  /** The block number indexing stops at (if configured). */
+  readonly endBlock?: number;
+  /** Number of blocks to keep for reorg handling (default: 200). */
+  readonly maxReorgDepth?: number;
+  /** Number of blocks behind the chain head to lag (default: 0). */
+  readonly blockLag?: number;
+};
+
+/** EVM chain value (for runtime Indexer). */
+type EvmChain<
+  Id extends number = number,
+  ContractName extends string = never
+> = {
+  /** The chain ID. */
+  readonly id: Id;
+  /** The chain name. */
+  readonly name: string;
+  /** The block number indexing starts from. */
+  readonly startBlock: number;
+  /** The block number indexing stops at (if configured). */
+  readonly endBlock: number | undefined;
+  /** Whether the chain has completed initial sync and is processing live events. */
+  readonly isLive: boolean;
+} & {
+  readonly [K in ContractName]: EvmContract<K>;
+};
+
+/** EVM contract (for runtime Indexer). */
+type EvmContract<Name extends string = string> = {
+  /** The contract name. */
+  readonly name: Name;
+  /** The contract ABI. */
+  readonly abi: readonly unknown[];
+  /** The contract addresses. */
+  readonly addresses: readonly Address[];
+};
+
+/** Fuel contract (for runtime Indexer). */
+type FuelContract<Name extends string = string> = {
+  /** The contract name. */
+  readonly name: Name;
+  /** The contract ABI. */
+  readonly abi: unknown;
+  /** The contract addresses. */
+  readonly addresses: readonly Address[];
+};
+
+// ============== Fuel Types ==============
+
+/** Fuel chain configuration (for IndexerConfig). */
+type FuelChainConfig<Id extends number = number> = {
+  /** The chain ID. */
+  readonly id: Id;
+  /** The block number indexing starts from. */
+  readonly startBlock: number;
+  /** The block number indexing stops at (if configured). */
+  readonly endBlock?: number;
+  /** Number of blocks to keep for reorg handling (default: 200). */
+  readonly maxReorgDepth?: number;
+  /** Number of blocks behind the chain head to lag (default: 0). */
+  readonly blockLag?: number;
+};
+
+/** Fuel chain value (for runtime Indexer). */
+type FuelChain<
+  Id extends number = number,
+  ContractName extends string = never
+> = {
+  /** The chain ID. */
+  readonly id: Id;
+  /** The chain name. */
+  readonly name: string;
+  /** The block number indexing starts from. */
+  readonly startBlock: number;
+  /** The block number indexing stops at (if configured). */
+  readonly endBlock: number | undefined;
+  /** Whether the chain has completed initial sync and is processing live events. */
+  readonly isLive: boolean;
+} & {
+  readonly [K in ContractName]: FuelContract<K>;
+};
+
+// ============== SVM (Solana) Types ==============
+
+/** SVM chain configuration (for IndexerConfig). */
+type SvmChainConfig<Id extends number = number> = {
+  /** The chain ID. */
+  readonly id: Id;
+  /** The block number indexing starts from. */
+  readonly startBlock: number;
+  /** The block number indexing stops at (if configured). */
+  readonly endBlock?: number;
+  /** Number of blocks to keep for reorg handling (default: 200). */
+  readonly maxReorgDepth?: number;
+  /** Number of blocks behind the chain head to lag (default: 0). */
+  readonly blockLag?: number;
+};
+
+/** SVM chain value (for runtime Indexer). */
+type SvmChain<Id extends number = number> = {
+  /** The chain ID. */
+  readonly id: Id;
+  /** The chain name. */
+  readonly name: string;
+  /** The block number indexing starts from. */
+  readonly startBlock: number;
+  /** The block number indexing stops at (if configured). */
+  readonly endBlock: number | undefined;
+  /** Whether the chain has completed initial sync and is processing live events. */
+  readonly isLive: boolean;
+};
+
+// ============== Indexer Type ==============
+
+/** Minimal type constraint for IndexerFromConfig to allow usage without full IndexerConfig. */
+type IndexerConfigTypes = {
+  evm?: {
+    chains: Record<string, { id: number }>;
+    contracts?: Record<string, {}>;
+  };
+  fuel?: {
+    chains: Record<string, { id: number }>;
+    contracts?: Record<string, {}>;
+  };
+  svm?: { chains: Record<string, { id: number }> };
+  entities?: Record<string, object>;
+};
+
+// Helper: Check if ecosystem is configured in a given config
+type HasEvm<Config> = "evm" extends keyof Config ? true : false;
+type HasFuel<Config> = "fuel" extends keyof Config ? true : false;
+type HasSvm<Config> = "svm" extends keyof Config ? true : false;
+
+// Count ecosystems using tuple length
+type BoolToNum<B extends boolean> = B extends true ? 1 : 0;
+type EcosystemTuple<Config> = [
+  ...([BoolToNum<HasEvm<Config>>] extends [1] ? [1] : []),
+  ...([BoolToNum<HasFuel<Config>>] extends [1] ? [1] : []),
+  ...([BoolToNum<HasSvm<Config>>] extends [1] ? [1] : [])
+];
+type EcosystemCount<Config> = EcosystemTuple<Config>["length"];
+
+// EVM ecosystem type
+type EvmEcosystem<Config extends IndexerConfigTypes> =
+  "evm" extends keyof Config
+    ? Config["evm"] extends {
+        chains: infer Chains;
+        contracts?: Record<infer ContractName, any>;
+      }
+      ? Chains extends Record<string, { id: number }>
+        ? {
+            /** Array of all EVM chain IDs. */
+            readonly chainIds: readonly Chains[keyof Chains]["id"][];
+            /** Per-chain configuration keyed by chain name or ID. */
+            readonly chains: {
+              readonly [K in Chains[keyof Chains]["id"]]: EvmChain<
+                K,
+                ContractName extends string ? ContractName : never
+              >;
+            } & {
+              readonly [K in keyof Chains]: EvmChain<
+                Chains[K]["id"],
+                ContractName extends string ? ContractName : never
+              >;
+            };
+          }
+        : never
+      : never
+    : never;
+
+// Fuel ecosystem type
+type FuelEcosystem<Config extends IndexerConfigTypes> =
+  "fuel" extends keyof Config
+    ? Config["fuel"] extends {
+        chains: infer Chains;
+        contracts?: Record<infer ContractName, any>;
+      }
+      ? Chains extends Record<string, { id: number }>
+        ? {
+            /** Array of all Fuel chain IDs. */
+            readonly chainIds: readonly Chains[keyof Chains]["id"][];
+            /** Per-chain configuration keyed by chain name or ID. */
+            readonly chains: {
+              readonly [K in Chains[keyof Chains]["id"]]: FuelChain<
+                K,
+                ContractName extends string ? ContractName : never
+              >;
+            } & {
+              readonly [K in keyof Chains]: FuelChain<
+                Chains[K]["id"],
+                ContractName extends string ? ContractName : never
+              >;
+            };
+          }
+        : never
+      : never
+    : never;
+
+// SVM ecosystem type
+type SvmEcosystem<Config extends IndexerConfigTypes> =
+  "svm" extends keyof Config
+    ? Config["svm"] extends { chains: infer Chains }
+      ? Chains extends Record<string, { id: number }>
+        ? {
+            /** Array of all SVM chain IDs. */
+            readonly chainIds: readonly Chains[keyof Chains]["id"][];
+            /** Per-chain configuration keyed by chain name or ID. */
+            readonly chains: {
+              readonly [K in Chains[keyof Chains]["id"]]: SvmChain<K>;
+            } & {
+              readonly [K in keyof Chains]: SvmChain<Chains[K]["id"]>;
+            };
+          }
+        : never
+      : never
+    : never;
+
+// Single ecosystem chains (flattened at root level)
+type SingleEcosystemChains<Config extends IndexerConfigTypes> =
+  HasEvm<Config> extends true
+    ? EvmEcosystem<Config>
+    : HasFuel<Config> extends true
+    ? FuelEcosystem<Config>
+    : HasSvm<Config> extends true
+    ? SvmEcosystem<Config>
+    : {};
+
+// Multi-ecosystem chains (namespaced by ecosystem)
+type MultiEcosystemChains<Config extends IndexerConfigTypes> =
+  (HasEvm<Config> extends true
+    ? {
+        /** EVM ecosystem configuration. */
+        readonly evm: EvmEcosystem<Config>;
+      }
+    : {}) &
+    (HasFuel<Config> extends true
+      ? {
+          /** Fuel ecosystem configuration. */
+          readonly fuel: FuelEcosystem<Config>;
+        }
+      : {}) &
+    (HasSvm<Config> extends true
+      ? {
+          /** SVM ecosystem configuration. */
+          readonly svm: SvmEcosystem<Config>;
+        }
+      : {});
+
+/**
+ * Indexer type resolved from config, adapting chain properties based on configured ecosystems.
+ * - Single ecosystem: chains are at the root level.
+ * - Multiple ecosystems: chains are namespaced by ecosystem (evm, fuel, svm).
+ */
+export type IndexerFromConfig<Config extends IndexerConfigTypes> = Prettify<
+  {
+    /** The indexer name from config.yaml. */
+    readonly name: string;
+    /** The indexer description from config.yaml. */
+    readonly description: string | undefined;
+  } & (EcosystemCount<Config> extends 1
+    ? SingleEcosystemChains<Config>
+    : MultiEcosystemChains<Config>)
+>;
+
+// ============== Test Indexer Types ==============
+
+/** Configuration for a single chain in the test indexer. */
+export type TestIndexerChainConfig = {
+  /** The block number to start processing from. */
+  startBlock: number;
+  /** The block number to stop processing at. */
+  endBlock: number;
+};
+
+/** Entity change value containing sets and/or deleted IDs. */
+type EntityChangeValue<Entity> = {
+  /** Entities that were created or updated. */
+  readonly sets?: readonly Entity[];
+  /** IDs of entities that were deleted. */
+  readonly deleted?: readonly string[];
+};
+
+/** A dynamic contract address registration. */
+type AddressRegistration = {
+  /** The contract address. */
+  readonly address: Address;
+  /** The contract name. */
+  readonly contract: string;
+};
+
+/** Extract entities from config. */
+type ConfigEntities<Config extends IndexerConfigTypes> =
+  Config["entities"] extends Record<string, object> ? Config["entities"] : {};
+
+/** Entity operations available on test indexer for direct entity manipulation. */
+type EntityOps<Entity> = {
+  /** Get an entity by ID. Returns undefined if not found. */
+  readonly get: (id: string) => Promise<Entity | undefined>;
+  /** Set (create or update) an entity. */
+  readonly set: (entity: Entity) => void;
+};
+
+/** A single change representing entity modifications at a specific block. */
+type EntityChange<Config extends IndexerConfigTypes> = {
+  /** The block where the changes occurred. */
+  readonly block: number;
+  /** The block hash (if available). */
+  readonly blockHash?: string;
+  /** The chain ID. */
+  readonly chainId: number;
+  /** Number of events processed in this block. */
+  readonly eventsProcessed: number;
+  /** Dynamic contract address registrations for this block. */
+  readonly addresses?: {
+    readonly sets?: readonly AddressRegistration[];
+  };
+} & {
+  readonly [K in keyof ConfigEntities<Config>]?: EntityChangeValue<
+    ConfigEntities<Config>[K]
+  >;
+};
+
+
+// Helper to extract chain IDs from config for test indexer
+type TestIndexerChainIds<Config extends IndexerConfigTypes> =
+  HasEvm<Config> extends true
+    ? Config["evm"] extends { chains: infer Chains }
+      ? Chains extends Record<string, { id: number }>
+        ? Chains[keyof Chains]["id"]
+        : never
+      : never
+    : HasFuel<Config> extends true
+    ? Config["fuel"] extends { chains: infer Chains }
+      ? Chains extends Record<string, { id: number }>
+        ? Chains[keyof Chains]["id"]
+        : never
+      : never
+    : HasSvm<Config> extends true
+    ? Config["svm"] extends { chains: infer Chains }
+      ? Chains extends Record<string, { id: number }>
+        ? Chains[keyof Chains]["id"]
+        : never
+      : never
+    : never;
+
+/** Process configuration for the test indexer, with chains keyed by chain ID. */
+export type TestIndexerProcessConfig<Config extends IndexerConfigTypes> = {
+  /** Chain configurations keyed by chain ID. Each chain specifies start and end blocks. */
+  chains: {
+    [K in TestIndexerChainIds<Config>]?: TestIndexerChainConfig;
+  };
+};
+
+/**
+ * Test indexer type resolved from config.
+ * Allows running the indexer for specific block ranges and inspecting results.
+ */
+export type TestIndexerFromConfig<Config extends IndexerConfigTypes> = {
+  /** Process blocks for the specified chains and return progress with checkpoints and changes. */
+  process: (
+    config: Prettify<TestIndexerProcessConfig<Config>>
+  ) => Promise<{
+    /** Changes happened during the processing. */
+    readonly changes: readonly EntityChange<Config>[];
+  }>;
+} & (EcosystemCount<Config> extends 1
+  ? SingleEcosystemChains<Config>
+  : MultiEcosystemChains<Config>) & {
+  /** Entity operations for direct manipulation outside of handlers. */
+  readonly [K in keyof ConfigEntities<Config>]: EntityOps<
+    ConfigEntities<Config>[K]
+  >;
+};

package/index.js

@@ -12,6 +12,10 @@ export * from "./src/Envio.res.mjs";
 // Important! Should match the index.d.ts file
 export const S = {
   string: Sury.string,
+  address: Sury.string,
+  evmChainId: Sury.number,
+  fuelChainId: Sury.number,
+  svmChainId: Sury.number,
   jsonString: Sury.jsonString,
   boolean: Sury.boolean,
   int32: Sury.int32,