envio 3.0.0-alpha.1 → 3.0.0-alpha.11

package/index.d.ts

@@ -8,10 +8,15 @@ 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] } & {};
 
 import type {
   effect as Effect,
@@ -108,6 +113,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 +146,452 @@ 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;
+};
+
+/** 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;
+};
+
+/** 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;
+};
+
+/** 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>[];
+  }>;
+} & {
+  /** 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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envio",
-  "version": "v3.0.0-alpha.1",
+  "version": "v3.0.0-alpha.11",
   "type": "module",
   "description": "A latency and sync speed optimized, developer friendly blockchain data indexer.",
   "bin": "./bin.js",
@@ -29,23 +29,35 @@
     "node": ">=22.0.0"
   },
   "optionalDependencies": {
-    "envio-linux-x64": "v3.0.0-alpha.1",
-    "envio-linux-arm64": "v3.0.0-alpha.1",
-    "envio-darwin-x64": "v3.0.0-alpha.1",
-    "envio-darwin-arm64": "v3.0.0-alpha.1"
+    "envio-linux-x64": "v3.0.0-alpha.11",
+    "envio-linux-arm64": "v3.0.0-alpha.11",
+    "envio-darwin-x64": "v3.0.0-alpha.11",
+    "envio-darwin-arm64": "v3.0.0-alpha.11"
   },
   "dependencies": {
     "@clickhouse/client": "1.12.1",
-    "@envio-dev/hypersync-client": "0.7.0",
+    "@elastic/ecs-pino-format": "1.4.0",
     "@envio-dev/hyperfuel-client": "1.2.2",
+    "@envio-dev/hypersync-client": "0.7.0",
+    "bignumber.js": "9.1.2",
+    "eventsource": "4.1.0",
+    "express": "4.19.2",
+    "pino": "10.1.0",
+    "pino-pretty": "13.1.3",
+    "prom-client": "15.0.0",
+    "yargs": "17.7.2",
     "rescript": "11.1.3",
     "rescript-schema": "9.3.4",
     "viem": "2.21.0",
-    "bignumber.js": "9.1.2",
-    "pino": "8.16.1",
-    "pino-pretty": "10.2.3",
-    "@elastic/ecs-pino-format": "1.4.0",
-    "prom-client": "15.0.0"
+    "rescript-envsafe": "5.0.0",
+    "dotenv": "16.4.5",
+    "date-fns": "3.3.1",
+    "@rescript/react": "0.14.0",
+    "ink": "6.5.1",
+    "ink-big-text": "2.0.0",
+    "ink-spinner": "5.0.0",
+    "postgres": "3.4.8",
+    "tsx": "4.21.0"
   },
   "files": [
     "bin.js",

package/rescript.json

@@ -19,6 +19,9 @@
     "generatedFileExtension": ".gen.ts",
     "moduleResolution": "node16"
   },
-  "bs-dependencies": ["rescript-schema"],
+  "jsx": {
+    "version": 4
+  },
+  "bs-dependencies": ["rescript-schema", "@rescript/react", "rescript-envsafe"],
   "bsc-flags": ["-open RescriptSchema"]
 }

package/src/Batch.res.mjs

@@ -80,7 +80,7 @@ function getProgressedChainsById(chainsBeforeBatch, batchSizePerChain, progressB
           var progressedChain;
           if (batchSize !== undefined) {
             var leftItems = fetchState.buffer.slice(batchSize);
-            progressedChain = getChainAfterBatchIfProgressed(chainBeforeBatch, progressBlockNumberAfterBatch, FetchState.updateInternal(fetchState, undefined, undefined, undefined, leftItems, undefined), batchSize);
+            progressedChain = getChainAfterBatchIfProgressed(chainBeforeBatch, progressBlockNumberAfterBatch, FetchState.updateInternal(fetchState, undefined, undefined, undefined, leftItems, undefined, undefined), batchSize);
           } else {
             progressedChain = getChainAfterBatchIfProgressed(chainBeforeBatch, progressBlockNumberAfterBatch, chainBeforeBatch.fetchState, 0);
           }