envio 3.15.0 → 3.16.0-subgraph

package/src/sources/SourceManager.res

@@ -85,7 +85,7 @@ type t = {
   // Should take into consideration partitions fetching for previous states (before rollback)
   mutable fetchingPartitionsCount: int,
   recoveryTimeout: float,
-  retryBackoffScale: float,
+  clock: Clock.t,
   // Why a source was last disabled for good. A disabled source is never
   // retried, so by the time the manager runs out of sources this is the reason
   // it did — and the only thing that tells a caller what to change.
@@ -93,11 +93,10 @@ type t = {
   mutable hasRealtime: bool,
   mutable committedRateLimitTimeMs: float,
   mutable rateLimitWaiters: int,
-  // Wall-clock timestamp (Date.now()) when the current rate-limit window
-  // started, or None if not currently waiting. Wall-clock so consumers
-  // (TUI) can compute elapsed time with their own Date.now() reads.
+  // When the current rate-limit window started on `clock`, or None if not
+  // currently waiting.
   mutable activeRateLimitStartMs: option<float>,
-  // Wall-clock timestamp by which the server expects the longest current
+  // Timestamp on `clock` by which the server expects the longest current
   // wait to clear. Tracks the latest reset across concurrent waiters so
   // the displayed countdown reflects when the indexer will actually retry.
   mutable activeRateLimitResetAtMs: option<float>,
@@ -206,20 +205,20 @@ let inFlightCount = sourceManager => sourceManager.fetchingPartitionsCount
 let getRateLimitTimeMs = sourceManager =>
   sourceManager.committedRateLimitTimeMs +.
   switch sourceManager.activeRateLimitStartMs {
-  | Some(startMs) => Date.now() -. startMs
+  | Some(startMs) => sourceManager.clock.now() -. startMs
   | None => 0.0
   }
 
 let getRateLimitResetInMs = sourceManager =>
   switch sourceManager.activeRateLimitResetAtMs {
   | Some(resetAt) =>
-    let remaining = resetAt -. Date.now()
+    let remaining = resetAt -. sourceManager.clock.now()
     remaining > 0.0 ? Some(remaining) : None
   | None => None
   }
 
 let startRateLimitTimeout = (sourceManager, ~resetMs) => {
-  let now = Date.now()
+  let now = sourceManager.clock.now()
   if sourceManager.rateLimitWaiters === 0 {
     sourceManager.activeRateLimitStartMs = Some(now)
   }
@@ -237,7 +236,7 @@ let stopRateLimitTimeout = sourceManager => {
     switch sourceManager.activeRateLimitStartMs {
     | Some(startMs) =>
       sourceManager.committedRateLimitTimeMs =
-        sourceManager.committedRateLimitTimeMs +. Date.now() -. startMs
+        sourceManager.committedRateLimitTimeMs +. sourceManager.clock.now() -. startMs
       sourceManager.activeRateLimitStartMs = None
     | None => ()
     }
@@ -259,16 +258,8 @@ let waitForRateLimitReset = async (sourceManager: t, ~resetMs, ~retry, ~logger)
         ->Int.toString}s. For higher limits upgrade your plan at https://envio.dev/app/api-tokens.`,
     ~params={"retry": retry, "waitMs": waitMs},
   )
-  let waitedAt = Date.now()
   sourceManager->startRateLimitTimeout(~resetMs=waitMs)
-  await Utils.delay(waitMs)
-  // Timers run on the event loop's cached clock, so one can fire with Date.now()
-  // a millisecond short of the wait it was set for, and the wait is counted by
-  // Date.now(). Temporary until main takes the same fix.
-  let short = waitedAt +. waitMs->Int.toFloat -. Date.now()
-  if short > 0. {
-    await Utils.delay(short->Math.ceil->Float.toInt)
-  }
+  await sourceManager.clock->Clock.delay(~label="rate-limit reset", waitMs)
   sourceManager->stopRateLimitTimeout
 }
 
@@ -354,11 +345,12 @@ type timing = {
   reducedPollingInterval?: int,
   recoveryTimeout?: float,
   getHeightRetryInterval?: (~retry: int) => int,
-  retryBackoffScale?: float,
   heightPollTimeout?: int,
+  clock?: Clock.t,
 }
 
 let make = (~sources: array<Source.t>, ~logger: Logger.t, ~isRealtime, ~timing: timing={}) => {
+  let clock = timing.clock->Option.getOr(Clock.real)
   let newBlockStallTimeout = timing.newBlockStallTimeout->Option.getOr(60_000)
   let newBlockStallTimeoutRealtime = timing.newBlockStallTimeoutRealtime->Option.getOr(20_000)
   let stalledPollingInterval = timing.stalledPollingInterval->Option.getOr(5_000)
@@ -392,6 +384,7 @@ let make = (~sources: array<Source.t>, ~logger: Logger.t, ~isRealtime, ~timing:
           ~recordRequestStats=stats => requestStats->recordStatsInto(stats),
           ~getHeightRetryInterval,
           ~pollTimeoutMillis=timing.heightPollTimeout->Option.getOr(60_000),
+          ~clock,
         ),
         disabled: false,
         lastFailedAt: None,
@@ -408,7 +401,7 @@ let make = (~sources: array<Source.t>, ~logger: Logger.t, ~isRealtime, ~timing:
     stalledPollingInterval,
     reducedPollingInterval,
     recoveryTimeout,
-    retryBackoffScale: timing.retryBackoffScale->Option.getOr(1.),
+    clock,
     statusStart: Performance.now(),
     status: Idle,
     idleSeconds: 0.,
@@ -517,8 +510,8 @@ let compareByOldestFailure = (a: sourceState, b: sourceState) =>
   }
 
 // Priority: working primaries > working secondaries > all primaries.
-let getNextSources = (sourceManager, ~isRealtime, ~excludedSources=?) => {
-  let now = Date.now()
+let getNextSources = (sourceManager: t, ~isRealtime, ~excludedSources=?) => {
+  let now = sourceManager.clock.now()
   let workingPrimarySources = []
   let allPrimarySources = []
   let workingSecondarySources = []
@@ -589,10 +582,8 @@ let retryBackoffMillis = retry =>
 // 0, these must never busy-loop when there is no other source to move to.
 let minRecoverableBackoffMillis = 50
 
-// The logged backoff stays the unscaled one, so a scaled-down test still reads
-// the schedule an operator would see.
 let sleepBackoff = (sourceManager: t, millis) =>
-  Utils.delay((millis->Int.toFloat *. sourceManager.retryBackoffScale)->Float.toInt)
+  sourceManager.clock->Clock.delay(~label="retry backoff", millis)
 
 // Back off before retrying the same request, failing the source over first when
 // another one can actually take over. Marking `lastFailedAt` only demotes this
@@ -614,7 +605,7 @@ let backoffBeforeRetry = async (
   let switchedToWorkingSource = if (
     retry >= failoverAfterRetries && (retry - failoverAfterRetries)->mod(2) === 0
   ) {
-    let now = Date.now()
+    let now = sourceManager.clock.now()
     sourceState.lastFailedAt = Some(now)
     switch sourceManager->getNextSource(~isRealtime, ~excludedSources?) {
     | Some(next) =>
@@ -851,8 +842,8 @@ let waitForNewBlock = (sourceManager: t, ~knownHeight, ~isRealtime, ~reducedPoll
     let cleanup = () => {
       watched->Array.forEach(subscription => subscription.unsubscribe())
       watched->Utils.Array.clearInPlace
-      pokeTimeoutId->Utils.clearTimeoutRef
-      stallTimeoutId->Utils.clearTimeoutRef
+      sourceManager.clock->Clock.clearRef(pokeTimeoutId)
+      sourceManager.clock->Clock.clearRef(stallTimeoutId)
     }
 
     let settled = ref(false)
@@ -922,32 +913,44 @@ let waitForNewBlock = (sourceManager: t, ~knownHeight, ~isRealtime, ~reducedPoll
       // Re-armed because distrusting a stream is a one-shot — the next height it
       // delivers takes it back at its word — and the silence that earned it can
       // come straight back.
-      let rec armPokeTimeout = () => pokeTimeoutId := Some(setTimeout(() => {
-              pokeTimeoutId := None
-              if !settled.contents {
-                watched->Array.forEach(subscription => subscription.distrustStream())
-              }
-
-              // Re-checked: distrusting can answer the wait, and a timer armed
-              // after the cleanup that follows is one nothing can ever clear.
-              if !settled.contents {
-                armPokeTimeout()
-              }
-            }, Utils.jitter(stallTimeout)))
+      let rec armPokeTimeout = () =>
+        pokeTimeoutId :=
+          Some(
+            sourceManager.clock.setTimeout(
+              ~label="stall poke",
+              () => {
+                pokeTimeoutId := None
+                if !settled.contents {
+                  watched->Array.forEach(subscription => subscription.distrustStream())
+                }
+
+                // Re-checked: distrusting can answer the wait, and a timer armed
+                // after the cleanup that follows is one nothing can ever clear.
+                if !settled.contents {
+                  armPokeTimeout()
+                }
+              },
+              sourceManager.clock->Clock.jitter(stallTimeout),
+            ),
+          )
 
       // Punctual, unlike the poke above: newBlockStallTimeout is a promise to the
       // operator about when they hear about a quiet chain, and spreading that
       // would report it early. Fires once — the warning is worth saying once per
       // wait, and a fallback stays recruited.
-      let armStallTimeout = () => stallTimeoutId := Some(setTimeout(() => {
-              stallTimeoutId := None
-              if !settled.contents {
-                stalled := true
-
-                // Build fallback: non-disabled sources not in mainSources with a valid role, even with recent lastFailedAt
-                let fallbackSources = []
-                sourcesState->Array.forEach(
-                  sourceState => {
+      let armStallTimeout = () =>
+        stallTimeoutId :=
+          Some(
+            sourceManager.clock.setTimeout(
+              ~label="stall timeout",
+              () => {
+                stallTimeoutId := None
+                if !settled.contents {
+                  stalled := true
+
+                  // Build fallback: non-disabled sources not in mainSources with a valid role, even with recent lastFailedAt
+                  let fallbackSources = []
+                  sourcesState->Array.forEach(sourceState => {
                     if (
                       !sourceState.disabled &&
                       !(mainSources->Array.includes(sourceState)) &&
@@ -959,37 +962,41 @@ let waitForNewBlock = (sourceManager: t, ~knownHeight, ~isRealtime, ~reducedPoll
                     ) {
                       fallbackSources->Array.push(sourceState)
                     }
-                  },
-                )
-
-                switch fallbackSources {
-                | [] =>
-                  logger->Logger.warn(
-                    `No new blocks detected within ${(stallTimeout / 1000)
-                        ->Int.toString}s. Polling will continue at a reduced rate. For better reliability, refer to our RPC fallback guide: https://docs.envio.dev/docs/HyperIndex/rpc-sync`,
+                  })
+
+                  switch fallbackSources {
+                  | [] =>
+                    logger->Logger.warn(
+                      `No new blocks detected within ${(stallTimeout / 1000)
+                          ->Int.toString}s. Polling will continue at a reduced rate. For better reliability, refer to our RPC fallback guide: https://docs.envio.dev/docs/HyperIndex/rpc-sync`,
+                    )
+                  | _ =>
+                    logger->Logger.warn(
+                      `No new blocks detected within ${(stallTimeout / 1000)
+                          ->Int.toString}s. Continuing polling with secondary RPC sources from the configuration.`,
+                    )
+                  }
+
+                  // Recruited to poll, not to stream: see `watch`.
+                  fallbackSources->Array.forEach(sourceState =>
+                    sourceState->watch(~withStream=false)
                   )
-                | _ =>
-                  logger->Logger.warn(
-                    `No new blocks detected within ${(stallTimeout / 1000)
-                        ->Int.toString}s. Continuing polling with secondary RPC sources from the configuration.`,
-                  )
-                }
 
-                // Recruited to poll, not to stream: see `watch`.
-                fallbackSources->Array.forEach(sourceState => sourceState->watch(~withStream=false))
-
-                // A fallback recruited here can still be holding a stream from an
-                // earlier wait that made it a primary, and a live stream is not
-                // polled behind. It has to inherit the verdict the primaries
-                // already earned — this wait has heard nothing for a whole window
-                // — or it would sit silent behind that stream until the next
-                // spread poke. Distrusting a waiter that already does so is a
-                // no-op, so this reaches the new ones only.
-                if !settled.contents {
-                  watched->Array.forEach(subscription => subscription.distrustStream())
+                  // A fallback recruited here can still be holding a stream from an
+                  // earlier wait that made it a primary, and a live stream is not
+                  // polled behind. It has to inherit the verdict the primaries
+                  // already earned — this wait has heard nothing for a whole window
+                  // — or it would sit silent behind that stream until the next
+                  // spread poke. Distrusting a waiter that already does so is a
+                  // no-op, so this reaches the new ones only.
+                  if !settled.contents {
+                    watched->Array.forEach(subscription => subscription.distrustStream())
+                  }
                 }
-              }
-            }, stallTimeout))
+              },
+              stallTimeout,
+            ),
+          )
 
       armPokeTimeout()
       armStallTimeout()

package/src/sources/SourceManager.res.mjs

@@ -1,5 +1,6 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Clock from "../Clock.res.mjs";
 import * as Utils from "../Utils.res.mjs";
 import * as Logger from "../Logger.res.mjs";
 import * as Source from "./Source.res.mjs";
@@ -153,7 +154,7 @@ function inFlightCount(sourceManager) {
 function getRateLimitTimeMs(sourceManager) {
   let startMs = sourceManager.activeRateLimitStartMs;
   return sourceManager.committedRateLimitTimeMs + (
-    startMs !== undefined ? Date.now() - startMs : 0.0
+    startMs !== undefined ? sourceManager.clock.now() - startMs : 0.0
   );
 }
 
@@ -162,14 +163,14 @@ function getRateLimitResetInMs(sourceManager) {
   if (resetAt === undefined) {
     return;
   }
-  let remaining = resetAt - Date.now();
+  let remaining = resetAt - sourceManager.clock.now();
   if (remaining > 0.0) {
     return remaining;
   }
 }
 
 function startRateLimitTimeout(sourceManager, resetMs) {
-  let now = Date.now();
+  let now = sourceManager.clock.now();
   if (sourceManager.rateLimitWaiters === 0) {
     sourceManager.activeRateLimitStartMs = now;
   }
@@ -186,20 +187,15 @@ async function waitForRateLimitReset(sourceManager, resetMs, retry, logger) {
     retry: retry,
     waitMs: waitMs
   });
-  let waitedAt = Date.now();
   startRateLimitTimeout(sourceManager, waitMs);
-  await Utils.delay(waitMs);
-  let short = waitedAt + waitMs - Date.now();
-  if (short > 0) {
-    await Utils.delay(Math.ceil(short) | 0);
-  }
+  await Clock.delay(sourceManager.clock, "rate-limit reset", waitMs);
   sourceManager.rateLimitWaiters = sourceManager.rateLimitWaiters - 1 | 0;
   if (sourceManager.rateLimitWaiters !== 0) {
     return;
   }
   let startMs = sourceManager.activeRateLimitStartMs;
   if (startMs !== undefined) {
-    sourceManager.committedRateLimitTimeMs = sourceManager.committedRateLimitTimeMs + Date.now() - startMs;
+    sourceManager.committedRateLimitTimeMs = sourceManager.committedRateLimitTimeMs + sourceManager.clock.now() - startMs;
     sourceManager.activeRateLimitStartMs = undefined;
   }
   sourceManager.activeRateLimitResetAtMs = undefined;
@@ -278,6 +274,7 @@ function makeGetHeightRetryInterval(initialRetryInterval, backoffMultiplicative,
 
 function make(sources, logger, isRealtime, timingOpt) {
   let timing = timingOpt !== undefined ? timingOpt : ({});
+  let clock = Stdlib_Option.getOr(timing.clock, Clock.real);
   let newBlockStallTimeout = Stdlib_Option.getOr(timing.newBlockStallTimeout, 60000);
   let newBlockStallTimeoutRealtime = Stdlib_Option.getOr(timing.newBlockStallTimeoutRealtime, 20000);
   let stalledPollingInterval = Stdlib_Option.getOr(timing.stalledPollingInterval, 5000);
@@ -293,7 +290,7 @@ function make(sources, logger, isRealtime, timingOpt) {
       let requestStats = {};
       return {
         source: source,
-        feed: HeightFeed.make(source, logger, stats => recordStatsInto(requestStats, stats), getHeightRetryInterval$1, Stdlib_Option.getOr(timing.heightPollTimeout, 60000)),
+        feed: HeightFeed.make(source, logger, stats => recordStatsInto(requestStats, stats), getHeightRetryInterval$1, Stdlib_Option.getOr(timing.heightPollTimeout, 60000), clock),
         disabled: false,
         lastFailedAt: undefined,
         requestStats: requestStats
@@ -314,7 +311,7 @@ function make(sources, logger, isRealtime, timingOpt) {
     waitingLogged: false,
     fetchingPartitionsCount: 0,
     recoveryTimeout: recoveryTimeout,
-    retryBackoffScale: Stdlib_Option.getOr(timing.retryBackoffScale, 1),
+    clock: clock,
     disableReason: undefined,
     hasRealtime: hasRealtime,
     committedRateLimitTimeMs: 0.0,
@@ -422,7 +419,7 @@ function compareByOldestFailure(a, b) {
 }
 
 function getNextSources(sourceManager, isRealtime, excludedSources) {
-  let now = Date.now();
+  let now = sourceManager.clock.now();
   let workingPrimarySources = [];
   let allPrimarySources = [];
   let workingSecondarySources = [];
@@ -475,7 +472,7 @@ function getNextSource(sourceManager, isRealtime, excludedSources) {
 }
 
 function sleepBackoff(sourceManager, millis) {
-  return Utils.delay(millis * sourceManager.retryBackoffScale | 0);
+  return Clock.delay(sourceManager.clock, "retry backoff", millis);
 }
 
 async function backoffBeforeRetry(sourceManager, sourceState, retry, isRealtime, backoffMillis, minBackoffMillisOpt, failoverAfterRetriesOpt, excludedSources) {
@@ -483,7 +480,7 @@ async function backoffBeforeRetry(sourceManager, sourceState, retry, isRealtime,
   let failoverAfterRetries = failoverAfterRetriesOpt !== undefined ? failoverAfterRetriesOpt : 2;
   let switchedToWorkingSource;
   if (retry >= failoverAfterRetries && (retry - failoverAfterRetries | 0) % 2 === 0) {
-    let now = Date.now();
+    let now = sourceManager.clock.now();
     sourceState.lastFailedAt = now;
     let next = getNextSource(sourceManager, isRealtime, excludedSources);
     if (next !== undefined) {
@@ -599,8 +596,8 @@ function waitForNewBlock(sourceManager, knownHeight, isRealtime, reducedPolling)
     let cleanup = () => {
       watched.forEach(subscription => subscription.unsubscribe());
       Utils.$$Array.clearInPlace(watched);
-      Utils.clearTimeoutRef(pokeTimeoutId);
-      Utils.clearTimeoutRef(stallTimeoutId);
+      Clock.clearRef(sourceManager.clock, pokeTimeoutId);
+      Clock.clearRef(sourceManager.clock, stallTimeoutId);
     };
     let settled = {
       contents: false
@@ -648,7 +645,7 @@ function waitForNewBlock(sourceManager, knownHeight, isRealtime, reducedPolling)
       return;
     }
     let armPokeTimeout = () => {
-      pokeTimeoutId.contents = Primitive_option.some(setTimeout(() => {
+      pokeTimeoutId.contents = Primitive_option.some(sourceManager.clock.setTimeout("stall poke", () => {
         pokeTimeoutId.contents = undefined;
         if (!settled.contents) {
           watched.forEach(subscription => subscription.distrustStream());
@@ -656,10 +653,10 @@ function waitForNewBlock(sourceManager, knownHeight, isRealtime, reducedPolling)
         if (!settled.contents) {
           return armPokeTimeout();
         }
-      }, Utils.jitter(stallTimeout)));
+      }, Clock.jitter(sourceManager.clock, stallTimeout)));
     };
     let armStallTimeout = () => {
-      stallTimeoutId.contents = Primitive_option.some(setTimeout(() => {
+      stallTimeoutId.contents = Primitive_option.some(sourceManager.clock.setTimeout("stall timeout", () => {
         stallTimeoutId.contents = undefined;
         if (settled.contents) {
           return;

package/src/sources/SourceManager.resi

@@ -17,11 +17,10 @@ type timing = {
   reducedPollingInterval?: int,
   recoveryTimeout?: float,
   getHeightRetryInterval?: (~retry: int) => int,
-  // Multiplies the sleep before retrying an items query or a block-hash
-  // lookup, but not the backoff it logs. A rate limit's wait is the server's
-  // to set and isn't scaled.
-  retryBackoffScale?: float,
   heightPollTimeout?: int,
+  // Every timer the manager and its height feeds arm, and every time they
+  // read. A test passes one that only moves when the test advances it.
+  clock?: Clock.t,
 }
 
 let make: (~sources: array<Source.t>, ~logger: Logger.t, ~isRealtime: bool, ~timing: timing=?) => t

package/src/sources/StartBlockResolver.res

@@ -25,6 +25,7 @@ let makeProbeSources = (chainConfig: Config.chain, ~logger, ~lowercaseAddresses)
     ~blockStore=BlockStore.make(~ecosystem=chainConfig.ecosystem),
     ~transactionStore=TransactionStore.make(~ecosystem=chainConfig.ecosystem),
     ~logger,
+    ~maxAddressesPerRequest=Env.maxAddrInPartition,
   )
 }
 

package/src/sources/StartBlockResolver.res.mjs

@@ -1,5 +1,6 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Env from "../Env.res.mjs";
 import * as Utils from "../Utils.res.mjs";
 import * as Logger from "../Logger.res.mjs";
 import * as ChainId from "../ChainId.res.mjs";
@@ -14,7 +15,7 @@ import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_excep
 
 function makeProbeSources(chainConfig, logger, lowercaseAddresses) {
   let addressStore = AddressStore.make(chainConfig.ecosystem, []);
-  return ChainSources.make(chainConfig, [], undefined, addressStore, lowercaseAddresses, BlockStore.make(chainConfig.ecosystem), TransactionStore.make(chainConfig.ecosystem), logger);
+  return ChainSources.make(chainConfig, [], undefined, addressStore, lowercaseAddresses, BlockStore.make(chainConfig.ecosystem), TransactionStore.make(chainConfig.ecosystem), logger, Env.maxAddrInPartition);
 }
 
 function candidateSources(sources) {
@@ -132,4 +133,4 @@ export {
   resolveHeadOrThrow,
   resolveAllOrThrow,
 }
-/* Utils Not a pure module */
+/* Env Not a pure module */

package/src/sources/SvmHyperSyncSource.res

@@ -277,7 +277,7 @@ let make = (
       {height, requestStats: [{method: "getHeight", seconds}]}
     },
     getItemsOrThrow,
-    createHeightSubscription: (~onHeight, ~onStatus) =>
-      HyperSyncSSE.subscribe(~hyperSyncUrl=endpointUrl, ~apiToken, ~onHeight, ~onStatus),
+    createHeightSubscription: (~clock, ~onHeight, ~onStatus) =>
+      HyperSyncSSE.subscribe(~clock, ~hyperSyncUrl=endpointUrl, ~apiToken, ~onHeight, ~onStatus),
   }
 }

package/src/sources/SvmHyperSyncSource.res.mjs

@@ -205,7 +205,7 @@ function make(param) {
       };
     },
     getItemsOrThrow: getItemsOrThrow,
-    createHeightSubscription: (onHeight, onStatus) => HyperSyncSSE.subscribe(endpointUrl, apiToken, onHeight, onStatus)
+    createHeightSubscription: (clock, onHeight, onStatus) => HyperSyncSSE.subscribe(clock, endpointUrl, apiToken, onHeight, onStatus)
   };
 }
 

package/src/subgraph/abi-types.ts

@@ -0,0 +1,84 @@
+/**
+ * Contract-call signatures and ABI type lists as graph codegen writes them.
+ * Free of envio imports: the graph-ts shim reads them too.
+ */
+
+export type ParsedSignature = {
+  name: string;
+  inputs: string;
+  outputs: string;
+};
+
+/**
+ * graph codegen emits `"balanceOf(address):(uint256)"`. Types only, no names —
+ * which is all the ABI codec needs.
+ */
+export function parseSignature(signature: string): ParsedSignature {
+  const open = signature.indexOf("(");
+  if (open === -1) {
+    throw new Error(`Unreadable contract call signature "${signature}"`);
+  }
+  const name = signature.slice(0, open);
+
+  let depth = 0;
+  let close = -1;
+  for (let index = open; index < signature.length; index++) {
+    const char = signature[index];
+    if (char === "(") depth++;
+    if (char === ")") {
+      depth--;
+      if (depth === 0) {
+        close = index;
+        break;
+      }
+    }
+  }
+  if (close === -1) {
+    throw new Error(`Unreadable contract call signature "${signature}"`);
+  }
+
+  const inputs = signature.slice(open + 1, close);
+  const rest = signature.slice(close + 1).replace(/^:/, "");
+  const outputs = rest.startsWith("(") ? rest.slice(1, -1) : rest;
+
+  return { name, inputs, outputs };
+}
+
+/** `address,(uint256,bytes)` → `["address", "(uint256,bytes)"]`. */
+export function splitTypes(list: string): string[] {
+  const types: string[] = [];
+  let depth = 0;
+  let start = 0;
+  for (let index = 0; index < list.length; index++) {
+    const char = list[index];
+    if (char === "(") depth++;
+    else if (char === ")") depth--;
+    else if (char === "," && depth === 0) {
+      types.push(list.slice(start, index));
+      start = index + 1;
+    }
+  }
+  if (list.length > 0) types.push(list.slice(start));
+  return types;
+}
+
+type AbiParam = { type: string; components?: AbiParam[] };
+
+/** An ABI parameter's type as graph codegen spells it: a tuple as `(…)`, keeping its array suffix. */
+function abiTypeString(param: AbiParam): string {
+  if (!param.type.startsWith("tuple")) return param.type;
+  return `(${(param.components ?? []).map(abiTypeString).join(",")})${param.type.slice("tuple".length)}`;
+}
+
+/** The first function named `name` in an ABI, as graph codegen's call signature: `name(inputs):(outputs)`. */
+export function functionSignature(abi: unknown, name: string): string | null {
+  const record = abi as { abi?: unknown; compilerOutput?: { abi?: unknown } } | null;
+  const entries = Array.isArray(abi) ? abi : (record?.abi ?? record?.compilerOutput?.abi);
+  if (!Array.isArray(entries)) return null;
+  const found = entries.find(
+    (entry) => (entry?.type ?? "function") === "function" && entry?.name === name,
+  ) as { inputs?: AbiParam[]; outputs?: AbiParam[] } | undefined;
+  if (!found) return null;
+  const list = (params: AbiParam[] | undefined) => (params ?? []).map(abiTypeString).join(",");
+  return `${name}(${list(found.inputs)}):(${list(found.outputs)})`;
+}