envio 3.0.0-alpha.2 → 3.0.0-alpha.21

package/index.d.ts

@@ -8,10 +8,57 @@ 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";
+
+export const TestHelpers: {
+  Addresses: {
+    readonly mockAddresses: readonly [
+      Address, Address, Address, Address, Address,
+      Address, Address, Address, Address, Address,
+      Address, Address, Address, Address, Address,
+      Address, Address, Address, Address, Address,
+    ];
+    readonly defaultAddress: Address;
+  };
+};
+
+/** 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 +155,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 +188,529 @@ 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, Record<string, { eventName: string }>>;
+  };
+  fuel?: {
+    chains: Record<string, { id: number }>;
+    contracts?: Record<string, Record<string, { eventName: 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 ==============
+
+/** Simulate item type for EVM ecosystem. */
+type EvmSimulateItem<Config extends IndexerConfigTypes> =
+  Config["evm"] extends { contracts: infer Contracts extends Record<string, Record<string, any>> }
+    ? {
+        [C in keyof Contracts]: {
+          [E in keyof Contracts[C]]: {
+            /** The contract name as defined in config.yaml. */
+            contract: C;
+            /** The event name as defined in the contract ABI. */
+            event: E;
+            /** Override the source address. Defaults to the first contract address. */
+            srcAddress?: Address;
+            /** Override the log index. Auto-increments by default. */
+            logIndex?: number;
+            /** Override block fields. */
+            block?: Partial<Contracts[C][E]["block"]>;
+            /** Override transaction fields. */
+            transaction?: Partial<Contracts[C][E]["transaction"]>;
+            /** Event parameters. Keys match the event's parameter names. */
+            params?: Partial<Contracts[C][E]["params"]>;
+          };
+        }[keyof Contracts[C]];
+      }[keyof Contracts]
+    : never;
+
+/** Simulate item type for Fuel ecosystem. */
+type FuelSimulateItem<Config extends IndexerConfigTypes> =
+  Config["fuel"] extends { contracts: infer Contracts extends Record<string, Record<string, any>> }
+    ? {
+        [C in keyof Contracts]: {
+          [E in keyof Contracts[C]]: {
+            /** The contract name as defined in config.yaml. */
+            contract: C;
+            /** The event name as defined in the contract ABI. */
+            event: E;
+            /** Override the source address. Defaults to the first contract address. */
+            srcAddress?: Address;
+            /** Override the log index. Auto-increments by default. */
+            logIndex?: number;
+            /** Override block fields. */
+            block?: Partial<Contracts[C][E]["block"]>;
+            /** Override transaction fields. */
+            transaction?: Partial<Contracts[C][E]["transaction"]>;
+            /** Event parameters. Keys match the event's parameter names. */
+            params: Contracts[C][E]["params"];
+          };
+        }[keyof Contracts[C]];
+      }[keyof Contracts]
+    : never;
+
+/** Configuration for a single EVM chain in the test indexer. */
+type EvmTestIndexerChainConfig<Config extends IndexerConfigTypes> = {
+  /** The block number to start processing from. Defaults to config startBlock or progressBlock+1. */
+  startBlock?: number;
+  /** The block number to stop processing at. Defaults to max simulate block number when simulate is provided. */
+  endBlock?: number;
+  /** Simulate items to process instead of fetching from real sources. */
+  simulate?: EvmSimulateItem<Config>[];
+};
+
+/** Configuration for a single Fuel chain in the test indexer. */
+type FuelTestIndexerChainConfig<Config extends IndexerConfigTypes> = {
+  /** The block number to start processing from. Defaults to config startBlock or progressBlock+1. */
+  startBlock?: number;
+  /** The block number to stop processing at. Defaults to max simulate block height when simulate is provided. */
+  endBlock?: number;
+  /** Simulate items to process instead of fetching from real sources. */
+  simulate?: FuelSimulateItem<Config>[];
+};
+
+/** 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 TestIndexerEntityOperations<Entity> = {
+  /** Get an entity by ID. Returns undefined if not found. */
+  readonly get: (id: string) => Promise<Entity | undefined>;
+  /** Get an entity by ID or throw if not found. */
+  readonly getOrThrow: (id: string, message?: string) => Promise<Entity>;
+  /** Get all entities. */
+  readonly getAll: () => Promise<Entity[]>;
+  /** 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 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 per ecosystem
+type EvmChainIds<Config extends IndexerConfigTypes> =
+  Config["evm"] extends { chains: infer Chains }
+    ? Chains extends Record<string, { id: number }>
+      ? Chains[keyof Chains]["id"]
+      : never
+    : never;
+
+type FuelChainIds<Config extends IndexerConfigTypes> =
+  Config["fuel"] extends { chains: infer Chains }
+    ? Chains extends Record<string, { id: number }>
+      ? Chains[keyof Chains]["id"]
+      : never
+    : never;
+
+// Per-ecosystem chain config mappings
+type EvmTestChains<Config extends IndexerConfigTypes> =
+  HasEvm<Config> extends true
+    ? { [K in EvmChainIds<Config>]?: EvmTestIndexerChainConfig<Config> }
+    : {};
+
+type FuelTestChains<Config extends IndexerConfigTypes> =
+  HasFuel<Config> extends true
+    ? { [K in FuelChainIds<Config>]?: FuelTestIndexerChainConfig<Config> }
+    : {};
+
+/** 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: Prettify<
+    EvmTestChains<Config> &
+    FuelTestChains<Config>
+  >;
+};
+
+/**
+ * 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>]: TestIndexerEntityOperations<
+    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,