[TC] feat: get pool deployment block from external sync if avail (#236)

Author: Gomorongi

packages/plugins/src/host/index.ts

@@ -59,10 +59,18 @@ export type ExternalSyncProvider = {
     ): AsyncIterable<ExternalRawEvent>;
 
     /**
-     * The highest block this provider has data for on the given pool, or `null`
-     * if it has none. Consumers use this to decide where the chain must take over.
+     * The lowest block this provider has data for on the given pool — roughly the
+     * pool's deployment/registration block. Consumers use it as a scan-start hint.
+     * @throws if the provider has no data for the pool.
      */
-    lastCoveredBlock(params: ExternalSyncPoolId): Promise<Hex | null>;
+    firstCoveredBlock(params: ExternalSyncPoolId): Promise<Hex>;
+
+    /**
+     * The highest block this provider has data for on the given pool. Consumers
+     * use it to decide where the chain must take over.
+     * @throws if the provider has no data for the pool.
+     */
+    lastCoveredBlock(params: ExternalSyncPoolId): Promise<Hex>;
 };
 
 /**

packages/tornado-cash/src/data/interfaces/sync.service.interface.ts

@@ -19,7 +19,10 @@ export type ExternalSyncClient = {
   getEvents(
     params: ExternalSyncPoolId & { fromBlock: Hex; toBlock: Hex },
   ): Promise<ExternalRawEvent[]>;
-  lastCoveredBlock(params: ExternalSyncPoolId): Promise<Hex | null>;
+  /** @throws if the provider has no data for the pool. */
+  firstCoveredBlock(params: ExternalSyncPoolId): Promise<Hex>;
+  /** @throws if the provider has no data for the pool. */
+  lastCoveredBlock(params: ExternalSyncPoolId): Promise<Hex>;
 };
 
 export interface SyncServiceParams {
@@ -71,4 +74,11 @@ export interface ISyncService {
   getRelayerRegistryEvents(
     params: IGetEventsParams,
   ): Promise<IGetRelayerRegistryEventsResult>;
+
+  /**
+   * Resolves a pool's scan-start block. Uses the external provider's first
+   * covered block when available (an O(1) lookup), else falls back to the
+   * on-chain deployment-block binary search.
+   */
+  getPoolDeploymentBlock(params: { chainId: bigint; address: Address }): Promise<bigint>;
 }

packages/tornado-cash/src/data/sync.service.ts

@@ -1,5 +1,6 @@
 import { ExternalRawEvent } from "@kohaku-eth/plugins";
 import { toHex } from "viem";
+import { Address } from "../interfaces/types.interface";
 import {
   ExternalSyncClient,
   IGetEventsParams,
@@ -100,6 +101,33 @@ export class SyncService implements ISyncService {
     };
   }
 
+  async getPoolDeploymentBlock({
+    chainId,
+    address,
+  }: {
+    chainId: bigint;
+    address: Address;
+  }): Promise<bigint> {
+    const provider = this.externalSyncProvider;
+
+    if (provider) {
+      try {
+        // The provider's first covered block ≈ the pool's registration block, at
+        // O(1) — much cheaper than the on-chain deployment-block binary search.
+        return BigInt(
+          await provider.firstCoveredBlock({
+            chainId: toHex(chainId),
+            address: toHex(address, { size: 20 }),
+          }),
+        );
+      } catch {
+        // Provider has no data for this pool — fall through to on-chain discovery.
+      }
+    }
+
+    return this.dataService.getContractDeploymentBlock(address);
+  }
+
   /**
    * Decides whether to use the external provider and, if so, streams its raw
    * events for `[fromBlock, coverage]`. Event-agnostic: callers parse the raw
@@ -123,14 +151,16 @@ export class SyncService implements ISyncService {
 
     const chainId = toHex(rawChainId);
     const hexAddress = toHex(address, { size: 20 });
-    const rawCoverage = await provider.lastCoveredBlock({ chainId, address: hexAddress });
 
-    if (!rawCoverage) {
+    let coverage: bigint;
+
+    try {
+      coverage = BigInt(await provider.lastCoveredBlock({ chainId, address: hexAddress }));
+    } catch {
+      // Provider has no data for this pool (or failed) — fall back to chain-only.
       return null;
     }
 
-    const coverage = BigInt(rawCoverage);
-
     if (coverage <= fromBlock) {
       return null;
     }

packages/tornado-cash/src/plugin/base.ts

@@ -77,6 +77,7 @@ export class TornadoCashProtocol implements TCInstance {
 
           return events;
         },
+        firstCoveredBlock: (params) => externalSyncProvider.firstCoveredBlock(params),
         lastCoveredBlock: (params) => externalSyncProvider.lastCoveredBlock(params),
       };
 

packages/tornado-cash/src/state/thunks/syncPoolsThunk.ts

@@ -3,19 +3,22 @@ import { IPool } from '../../data/interfaces/events.interface';
 import { registerPools } from '../slices/poolsSlice';
 import { RootState } from '../store';
 import { IDataService } from '../../data/interfaces/data.service.interface';
+import { ISyncService } from '../../data/interfaces/sync.service.interface';
 import { instanceRegistryInfoSelector, poolsSelector } from '../selectors/slices.selectors';
 
 export interface SyncPoolsThunkParams {
   dataService: IDataService;
+  syncService: ISyncService;
 }
 
 export const syncPoolsThunk = createAsyncThunk<void, SyncPoolsThunkParams, { state: RootState }>(
   'sync/pools',
   async ({
-    dataService
+    dataService,
+    syncService,
   }, { dispatch, getState }) => {
     const state = getState();
-    const { instanceRegistry: { address: instanceRegistryAddress } } = instanceRegistryInfoSelector(state);
+    const { chainId, instanceRegistry: { address: instanceRegistryAddress } } = instanceRegistryInfoSelector(state);
     const existingPools = poolsSelector(state);
 
     const poolsAddressses = await dataService.getAllPoolsAddresses(instanceRegistryAddress);
@@ -25,7 +28,7 @@ export const syncPoolsThunk = createAsyncThunk<void, SyncPoolsThunkParams, { sta
       unsyncedPools.map(async (poolAddress) => {
         const [config, registeredBlock] = await Promise.all([
           dataService.getPoolConfig(instanceRegistryAddress, poolAddress),
-          dataService.getContractDeploymentBlock(poolAddress),
+          syncService.getPoolDeploymentBlock({ chainId, address: poolAddress }),
         ]);
 
         return { config, registeredBlock };

packages/tornado-cash/src/state/thunks/syncThunk.ts

@@ -29,6 +29,7 @@ export const syncThunk = createAsyncThunk<void, SyncThunkParams, { state: RootSt
 
     unwrapResult(await dispatch(syncPoolsThunk({
       dataService,
+      syncService,
     })));
 
     unwrapResult(await dispatch(syncRelayersThunk({ dataService, syncService })));

packages/tornado-cash/tests/unit/sync-service.test.ts

@@ -66,27 +66,50 @@ const makeDataService = () => {
     RelayerRegistered: events.map((e) => relayerRegistered(BigInt(e.blockNumber))),
   }));
 
+  const getContractDeploymentBlock = vi.fn(async () => 42n);
+
   return {
     getBlockNumber: vi.fn(async () => HEAD),
     getPoolEvents,
     parsePoolEvents,
     getRelayerRegistryEvents,
     parseRelayerRegistryEvents,
+    getContractDeploymentBlock,
   } as unknown as IDataService & {
     getPoolEvents: typeof getPoolEvents;
     parsePoolEvents: typeof parsePoolEvents;
     getRelayerRegistryEvents: typeof getRelayerRegistryEvents;
     parseRelayerRegistryEvents: typeof parseRelayerRegistryEvents;
+    getContractDeploymentBlock: typeof getContractDeploymentBlock;
   };
 };
 
-const makeProvider = (coverage: bigint | null, events: ExternalRawEvent[] = []) => {
+const makeProvider = (
+  coverage: bigint | null,
+  events: ExternalRawEvent[] = [],
+  firstBlock: bigint | null = null,
+) => {
   const getEvents = vi.fn(async () => events);
 
   return {
-    lastCoveredBlock: vi.fn(async () => (coverage == null ? null : toHex(coverage))),
+    // Coverage methods throw (rather than return null) when the provider has no
+    // data for the pool.
+    lastCoveredBlock: vi.fn(async () => {
+      if (coverage == null) throw new Error('no coverage');
+
+      return toHex(coverage);
+    }),
+    firstCoveredBlock: vi.fn(async () => {
+      if (firstBlock == null) throw new Error('no coverage');
+
+      return toHex(firstBlock);
+    }),
     getEvents,
-  } as unknown as ExternalSyncClient & { getEvents: typeof getEvents };
+  } as unknown as ExternalSyncClient & {
+    getEvents: typeof getEvents;
+    lastCoveredBlock: ReturnType<typeof vi.fn>;
+    firstCoveredBlock: ReturnType<typeof vi.fn>;
+  };
 };
 
 const rawAt = (block: bigint): ExternalRawEvent => ({
@@ -235,3 +258,48 @@ describe('SyncService.getRelayerRegistryEvents', () => {
     expect(result.RelayerRegistered.map((r) => r.blockNumber)).toEqual([100n]);
   });
 });
+
+describe('SyncService.getPoolDeploymentBlock', () => {
+  it("uses the provider's first covered block, skipping the on-chain search", async () => {
+    const dataService = makeDataService();
+    const provider = makeProvider(600n, [], 12345n);
+    const service = new SyncService({
+      dataService,
+      externalSyncProvider: provider,
+      minExternalSyncBlocksAmount: 100,
+    });
+
+    const block = await service.getPoolDeploymentBlock({ chainId: CHAIN_ID, address: POOL });
+
+    expect(block).toBe(12345n);
+    expect(provider.firstCoveredBlock).toHaveBeenCalledWith(
+      expect.objectContaining({ chainId: toHex(CHAIN_ID) }),
+    );
+    expect(dataService.getContractDeploymentBlock).not.toHaveBeenCalled();
+  });
+
+  it('falls back to the on-chain deployment block when the provider has no coverage', async () => {
+    const dataService = makeDataService();
+    const provider = makeProvider(600n, [], null); // firstCoveredBlock throws
+    const service = new SyncService({
+      dataService,
+      externalSyncProvider: provider,
+      minExternalSyncBlocksAmount: 100,
+    });
+
+    const block = await service.getPoolDeploymentBlock({ chainId: CHAIN_ID, address: POOL });
+
+    expect(block).toBe(42n);
+    expect(dataService.getContractDeploymentBlock).toHaveBeenCalledWith(POOL);
+  });
+
+  it('falls back to the on-chain deployment block when no provider is configured', async () => {
+    const dataService = makeDataService();
+    const service = new SyncService({ dataService });
+
+    const block = await service.getPoolDeploymentBlock({ chainId: CHAIN_ID, address: POOL });
+
+    expect(block).toBe(42n);
+    expect(dataService.getContractDeploymentBlock).toHaveBeenCalledWith(POOL);
+  });
+});