@quaivault/sdk 0.1.1 → 0.2.1

package/dist/index.js

@@ -44,6 +44,11 @@ var QuaiVaultError = class extends Error {
     };
   }
 };
+var AbortError = class extends QuaiVaultError {
+  constructor(operation = "The operation") {
+    super("ABORTED", `${operation} was aborted.`);
+  }
+};
 var ConfigError = class extends QuaiVaultError {
   constructor(message, remediation) {
     super("CONFIG", message, { remediation });
@@ -162,6 +167,16 @@ var Connection = class {
       write ? this.requireSigner("This recovery write") : this.provider
     );
   }
+  /**
+   * Read-only handle to a token contract.
+   *
+   * No write variant: the SDK never calls a token directly. Moving tokens goes
+   * through the vault's proposal flow, which encodes the transfer as calldata.
+   */
+  token(address2, standard) {
+    const abi = standard === "ERC20" ? Erc20Abi : standard === "ERC721" ? Erc721Abi : Erc1155Abi;
+    return new Contract(address2, abi, this.provider);
+  }
 };
 function createPrivateKeySigner(privateKey, provider) {
   const normalized = privateKey.startsWith("0x") ? privateKey : `0x${privateKey}`;
@@ -204,6 +219,36 @@ function normalizeTxHash(value, label = "transaction hash") {
 // src/config/resolve.ts
 import { isAddress } from "quais";
 
+// src/lifecycle/status.ts
+function nowSeconds() {
+  return Math.floor(Date.now() / 1e3);
+}
+function executableAfterOf(approvedAt, executionDelay) {
+  return approvedAt > 0 ? approvedAt + executionDelay : 0;
+}
+function deriveStatus(state, at = nowSeconds()) {
+  if (state.failed) return "failed";
+  if (state.executed) return "executed";
+  if (state.cancelled) return state.isExpired ? "expired" : "cancelled";
+  if (state.expiration > 0 && at > state.expiration) return "expired";
+  if (state.approvalCount < state.threshold) return "pending";
+  const executableAfter = executableAfterOf(state.approvedAt, state.executionDelay);
+  if (state.executionDelay > 0 && (state.approvedAt === 0 || at < executableAfter)) {
+    return "timelocked";
+  }
+  return "ready";
+}
+function isTerminal(status) {
+  return status === "executed" || status === "failed" || status === "cancelled" || status === "expired";
+}
+function deriveRecoveryStatus(state, at = nowSeconds()) {
+  if (state.executed) return "executed";
+  if (state.expiration > 0 && at > state.expiration) return "expired";
+  if (state.approvalCount < state.requiredThreshold) return "pending";
+  if (at < state.executionTime) return "timelocked";
+  return "ready";
+}
+
 // src/config/networks.ts
 var INDEXER_URL = "https://xbftgyuxaxagptudledv.supabase.co";
 var INDEXER_PUBLISHABLE_KEY = "sb_publishable_EO-sTB-jqUzlsiugOEks-Q_qRtHDaHU";
@@ -398,9 +443,14 @@ function resolveConfig(options = {}) {
     contracts,
     indexer,
     rpcUrl,
-    privateKey: pick(options.privateKey, env[ENV_VARS.privateKey]),
+    // An explicit signer wins outright in `Connection`, so resolving a key here would
+    // only pull a secret into memory that nothing can use. Skip it.
+    privateKey: options.signer ? void 0 : pick(options.privateKey, env[ENV_VARS.privateKey]),
     consistency,
     maxIndexerLagBlocks: options.maxIndexerLagBlocks ?? parseLag(env[ENV_VARS.maxIndexerLagBlocks]) ?? 50,
+    // Deliberately not environment-configurable: a clock is a function, and a numeric
+    // offset in an env var would reintroduce the sign convention `Clock` exists to avoid.
+    now: options.now ?? nowSeconds,
     retry: {
       ...options.retry?.maxAttempts != null ? { maxAttempts: options.retry.maxAttempts } : {},
       ...options.retry?.baseDelayMs != null ? { baseDelayMs: options.retry.baseDelayMs } : {},
@@ -528,7 +578,7 @@ function isTransient(error) {
 }
 var sleep = (ms, signal) => new Promise((resolve, reject) => {
   if (signal?.aborted) {
-    reject(new Error("Aborted"));
+    reject(new AbortError("Waiting to retry"));
     return;
   }
   const timer = setTimeout(() => {
@@ -537,7 +587,7 @@ var sleep = (ms, signal) => new Promise((resolve, reject) => {
   }, ms);
   const onAbort = () => {
     clearTimeout(timer);
-    reject(new Error("Aborted"));
+    reject(new AbortError("Waiting to retry"));
   };
   signal?.addEventListener("abort", onAbort, { once: true });
 });
@@ -547,7 +597,7 @@ async function withRetry(fn, options = {}) {
   const maxDelayMs = options.maxDelayMs ?? DEFAULTS.maxDelayMs;
   let lastError;
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    if (options.signal?.aborted) throw new Error("Aborted");
+    if (options.signal?.aborted) throw new AbortError("The retried operation");
     try {
       return await fn();
     } catch (error) {
@@ -742,8 +792,39 @@ var FactoryContract = class {
 
 // src/errors/decode.ts
 import { Interface, AbiCoder } from "quais";
+
+// src/text.ts
+var UNSAFE_CHARS = new RegExp(
+  [
+    "[\\u0000-\\u001F",
+    // C0 controls, incl. ESC (0x1B) — the head of every ANSI sequence
+    "\\u007F-\\u009F",
+    // DEL and the C1 controls
+    "\\u200B-\\u200F",
+    // zero-width space/joiners, LRM, RLM
+    "\\u202A-\\u202E",
+    // bidi embeddings and overrides
+    "\\u2060-\\u2064",
+    // word joiner and the invisible operators
+    "\\u2066-\\u2069",
+    // bidi isolates
+    "\\uFEFF]"
+    // zero-width no-break space / BOM
+  ].join(""),
+  "g"
+);
+var DEFAULT_TEXT_LIMIT = 128;
+function sanitizeText(value, maxLength = DEFAULT_TEXT_LIMIT) {
+  if (typeof value !== "string") return "";
+  const cleaned = value.replace(UNSAFE_CHARS, "").trim();
+  if (cleaned.length <= maxLength) return cleaned;
+  return `${cleaned.slice(0, Math.max(0, maxLength - 1))}\u2026`;
+}
+
+// src/errors/decode.ts
 var SOLIDITY_ERROR_SELECTOR = "0x08c379a0";
 var SOLIDITY_PANIC_SELECTOR = "0x4e487b71";
+var REVERT_TEXT_LIMIT = 256;
 var registry = null;
 function buildRegistry() {
   const map = /* @__PURE__ */ new Map();
@@ -833,7 +914,7 @@ function formatArgs(fragment, args) {
   if (args.length === 0) return "";
   const parts = fragment.inputs.map((input, i) => {
     const value = args[i];
-    const rendered = typeof value === "bigint" ? value.toString() : String(value);
+    const rendered = typeof value === "bigint" ? value.toString() : typeof value === "string" ? sanitizeText(value, REVERT_TEXT_LIMIT) : String(value);
     return input.name ? `${input.name}: ${rendered}` : rendered;
   });
   return `(${parts.join(", ")})`;
@@ -849,7 +930,7 @@ function decodeRevert(data) {
         name: "Error",
         args: [reason],
         selector,
-        message: String(reason)
+        message: sanitizeText(reason, REVERT_TEXT_LIMIT)
       };
     } catch {
       return void 0;
@@ -916,7 +997,7 @@ function knownErrorSelectors() {
 }
 
 // src/encode/index.ts
-import { AbiCoder as AbiCoder2, Interface as Interface2, concat, getBytes, solidityPacked, zeroPadValue, toBeHex } from "quais";
+import { AbiCoder as AbiCoder2, Interface as Interface2, concat, getBytes, solidityPacked } from "quais";
 
 // src/types.ts
 var Operation = /* @__PURE__ */ ((Operation2) => {
@@ -937,6 +1018,7 @@ var MAX_EXECUTION_DELAY = 30 * 24 * 60 * 60;
 var MAX_OWNERS = 20;
 var MAX_MODULES = 50;
 var SENTINEL_MODULES = "0x0000000000000000000000000000000000000001";
+var ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
 var selfCall = {
   addOwner: (owner) => vault.encodeFunctionData("addOwner", [owner]),
   removeOwner: (owner) => vault.encodeFunctionData("removeOwner", [owner]),
@@ -1043,7 +1125,7 @@ function encodeMultiSendPayload(calls) {
 function encodeMultiSend(calls) {
   return multiSend.encodeFunctionData("multiSend", [encodeMultiSendPayload(calls)]);
 }
-function minimumExpiration(effectiveDelaySeconds, marginSeconds = 300, at = Math.floor(Date.now() / 1e3)) {
+function minimumExpiration(effectiveDelaySeconds, marginSeconds = 300, at = nowSeconds()) {
   return at + effectiveDelaySeconds + marginSeconds;
 }
 
@@ -1104,7 +1186,7 @@ var syncStrategy = {
   async mine({ factory, deployer, bytecodeHash, targetPrefix, maxAttempts, timeoutMs, onProgress, signal }) {
     const startedAt = Date.now();
     for (let attempts = 0; attempts < maxAttempts; ) {
-      if (signal?.aborted) throw new SaltMiningError("Salt mining was aborted.");
+      if (signal?.aborted) throw new AbortError("Salt mining");
       if (Date.now() - startedAt > timeoutMs) {
         throw new SaltMiningError(
           `Salt mining timed out after ${timeoutMs} ms (${attempts} attempts).`,
@@ -1132,109 +1214,127 @@ var syncStrategy = {
     );
   }
 };
-var workerThreadsStrategy = {
-  name: "worker_threads",
-  async mine(job) {
-    let Worker;
-    let availableParallelism;
-    try {
-      ({ Worker } = await import("worker_threads"));
-      const os = await import("os");
-      availableParallelism = os.availableParallelism ?? (() => os.cpus().length);
-    } catch {
-      return syncStrategy.mine(job);
+var WorkersUnavailable = class extends Error {
+};
+async function loadNodeWorkers() {
+  try {
+    const { Worker } = await import("worker_threads");
+    const os = await import("os");
+    return { Worker, parallelism: (os.availableParallelism ?? (() => os.cpus().length))() };
+  } catch {
+    return null;
+  }
+}
+function createWorkerThreadsStrategy(load = loadNodeWorkers) {
+  return {
+    name: "worker_threads",
+    async mine(job) {
+      const runtime = await load();
+      if (!runtime) return syncStrategy.mine(job);
+      try {
+        return await mineInWorkers(runtime.Worker, runtime.parallelism, job);
+      } catch (err) {
+        if (err instanceof WorkersUnavailable) return syncStrategy.mine(job);
+        throw err;
+      }
     }
-    const { factory, deployer, bytecodeHash, targetPrefix, maxAttempts, timeoutMs, onProgress, signal } = job;
-    const workerCount = Math.max(1, Math.min(8, availableParallelism() - 1));
-    const perWorker = Math.ceil(maxAttempts / workerCount);
-    const startedAt = Date.now();
-    const workerSource = `
-      const { parentPort, workerData } = require('node:worker_threads');
-      const { getCreate2Address, hexlify, isQuaiAddress, keccak256, randomBytes, solidityPacked } = require('quais');
-      const { factory, deployer, bytecodeHash, targetPrefix, maxAttempts } = workerData;
-      for (let i = 0; i < maxAttempts; i++) {
-        const salt = hexlify(randomBytes(32));
-        const fullSalt = keccak256(solidityPacked(['address', 'bytes32'], [deployer, salt]));
-        const address = getCreate2Address(factory, fullSalt, bytecodeHash);
-        if (address.toLowerCase().startsWith(targetPrefix) && isQuaiAddress(address)) {
-          parentPort.postMessage({ type: 'result', salt, address, attempts: i + 1 });
-          return;
-        }
-        if ((i + 1) % ${PROGRESS_INTERVAL} === 0) parentPort.postMessage({ type: 'progress', attempts: i + 1 });
+  };
+}
+var workerThreadsStrategy = createWorkerThreadsStrategy();
+function mineInWorkers(Worker, parallelism, job) {
+  const { factory, deployer, bytecodeHash, targetPrefix, maxAttempts, timeoutMs, onProgress, signal } = job;
+  const workerCount = Math.max(1, Math.min(8, parallelism - 1));
+  const perWorker = Math.ceil(maxAttempts / workerCount);
+  const startedAt = Date.now();
+  const workerSource = `
+    const { parentPort, workerData } = require('node:worker_threads');
+    const { getCreate2Address, hexlify, isQuaiAddress, keccak256, randomBytes, solidityPacked } = require('quais');
+    const { factory, deployer, bytecodeHash, targetPrefix, maxAttempts } = workerData;
+    for (let i = 0; i < maxAttempts; i++) {
+      const salt = hexlify(randomBytes(32));
+      const fullSalt = keccak256(solidityPacked(['address', 'bytes32'], [deployer, salt]));
+      const address = getCreate2Address(factory, fullSalt, bytecodeHash);
+      if (address.toLowerCase().startsWith(targetPrefix) && isQuaiAddress(address)) {
+        parentPort.postMessage({ type: 'result', salt, address, attempts: i + 1 });
+        return;
       }
-      parentPort.postMessage({ type: 'exhausted', attempts: maxAttempts });
-    `;
-    return new Promise((resolve, reject) => {
-      const workers = [];
-      let settled = false;
-      let exhausted = 0;
-      let totalAttempts = 0;
-      const progressByWorker = new Array(workerCount).fill(0);
-      const cleanup = () => {
-        clearTimeout(timer);
-        signal?.removeEventListener("abort", onAbort);
-        for (const w of workers) void w.terminate();
-      };
-      const settle = (fn) => {
-        if (settled) return;
-        settled = true;
-        cleanup();
-        fn();
-      };
-      const timer = setTimeout(
-        () => settle(
-          () => reject(
-            new SaltMiningError(
-              `Salt mining timed out after ${timeoutMs} ms (~${totalAttempts} attempts across ${workerCount} workers).`,
-              "Raise timeoutMs or maxAttempts."
-            )
+      if ((i + 1) % ${PROGRESS_INTERVAL} === 0) parentPort.postMessage({ type: 'progress', attempts: i + 1 });
+    }
+    parentPort.postMessage({ type: 'exhausted', attempts: maxAttempts });
+  `;
+  return new Promise((resolve, reject) => {
+    const workers = [];
+    let settled = false;
+    let exhausted = 0;
+    let totalAttempts = 0;
+    const progressByWorker = new Array(workerCount).fill(0);
+    const cleanup = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      for (const w of workers) void w.terminate();
+    };
+    const settle = (fn) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      fn();
+    };
+    const timer = setTimeout(
+      () => settle(
+        () => reject(
+          new SaltMiningError(
+            `Salt mining timed out after ${timeoutMs} ms (~${totalAttempts} attempts across ${workerCount} workers).`,
+            "Raise timeoutMs or maxAttempts."
           )
-        ),
-        timeoutMs
-      );
-      const onAbort = () => settle(() => reject(new SaltMiningError("Salt mining was aborted.")));
-      signal?.addEventListener("abort", onAbort, { once: true });
-      for (let i = 0; i < workerCount; i++) {
-        const worker = new Worker(workerSource, {
+        )
+      ),
+      timeoutMs
+    );
+    const onAbort = () => settle(() => reject(new AbortError("Salt mining")));
+    signal?.addEventListener("abort", onAbort, { once: true });
+    for (let i = 0; i < workerCount; i++) {
+      let worker;
+      try {
+        worker = new Worker(workerSource, {
           eval: true,
           workerData: { factory, deployer, bytecodeHash, targetPrefix, maxAttempts: perWorker }
         });
-        workers.push(worker);
-        worker.on("message", (msg) => {
-          if (msg.type === "progress") {
-            progressByWorker[i] = msg.attempts ?? 0;
-            totalAttempts = progressByWorker.reduce((a, b) => a + b, 0);
-            onProgress?.(totalAttempts);
-          } else if (msg.type === "result") {
+      } catch (err) {
+        settle(() => reject(new WorkersUnavailable(String(err))));
+        return;
+      }
+      workers.push(worker);
+      worker.on("message", (msg) => {
+        if (msg.type === "progress") {
+          progressByWorker[i] = msg.attempts ?? 0;
+          totalAttempts = progressByWorker.reduce((a, b) => a + b, 0);
+          onProgress?.(totalAttempts);
+        } else if (msg.type === "result") {
+          settle(
+            () => resolve({
+              salt: msg.salt,
+              predictedAddress: msg.address,
+              attempts: totalAttempts + (msg.attempts ?? 0),
+              durationMs: Date.now() - startedAt
+            })
+          );
+        } else if (msg.type === "exhausted") {
+          if (++exhausted === workerCount) {
             settle(
-              () => resolve({
-                salt: msg.salt,
-                predictedAddress: msg.address,
-                attempts: totalAttempts + (msg.attempts ?? 0),
-                durationMs: Date.now() - startedAt
-              })
-            );
-          } else if (msg.type === "exhausted") {
-            if (++exhausted === workerCount) {
-              settle(
-                () => reject(
-                  new SaltMiningError(
-                    `No valid salt found for prefix ${targetPrefix} after ${maxAttempts} attempts.`,
-                    "Raise maxAttempts, or confirm the deployer address is on the shard you expect."
-                  )
+              () => reject(
+                new SaltMiningError(
+                  `No valid salt found for prefix ${targetPrefix} after ${maxAttempts} attempts.`,
+                  "Raise maxAttempts, or confirm the deployer address is on the shard you expect."
                 )
-              );
-            }
+              )
+            );
           }
-        });
-        worker.on(
-          "error",
-          (err) => settle(() => reject(new SaltMiningError(`Salt mining worker failed: ${err.message}`)))
-        );
-      }
-    });
-  }
-};
+        }
+      });
+      worker.on("error", (err) => settle(() => reject(new WorkersUnavailable(err.message))));
+    }
+  });
+}
 function defaultStrategy() {
   const hasNode = typeof globalThis.process?.versions?.node === "string";
   return hasNode ? workerThreadsStrategy : syncStrategy;
@@ -1456,7 +1556,7 @@ function validateCreateParams(params) {
   owners.forEach((owner, i) => {
     assertQuaiAddress(owner, `owner[${i}]`);
     const key = owner.toLowerCase();
-    if (key === "0x0000000000000000000000000000000000000000" || key === "0x0000000000000000000000000000000000000001") {
+    if (key === ZERO_ADDRESS || key === SENTINEL_MODULES) {
       throw new ValidationError(
         `Owner ${owner} is reserved \u2014 the zero address and the module sentinel 0x\u202601 are rejected.`
       );
@@ -1465,6 +1565,11 @@ function validateCreateParams(params) {
     seen.add(key);
   });
   if (params.initialModules?.length) {
+    if (params.initialModules.length > MAX_MODULES) {
+      throw new ValidationError(
+        `A vault may have at most ${MAX_MODULES} modules (got ${params.initialModules.length}).`
+      );
+    }
     assertQuaiAddresses(params.initialModules, "initialModules");
   }
   if (params.initialDelegatecallTargets?.length) {
@@ -1502,7 +1607,8 @@ function extractCreatedVault(receipt, factoryAddress) {
 }
 
 // src/indexer/client.ts
-import { createClient } from "@supabase/supabase-js";
+import { PostgrestClient } from "@supabase/postgrest-js";
+import { RealtimeClient } from "@supabase/realtime-js";
 
 // src/indexer/schemas.ts
 var schemas_exports = {};
@@ -1701,30 +1807,63 @@ function toNumber(value, fallback = 0) {
 }
 
 // src/indexer/client.ts
-var SDK_VERSION = "0.1.0";
+var SDK_VERSION = true ? "0.2.1" : "dev";
 var IndexerClient = class {
   config;
   client;
+  realtime = null;
   healthCache = null;
   inflightHealth = null;
-  /** Health results are reused for this long to keep read paths cheap. */
+  /**
+   * Health results are reused for this long to keep read paths cheap.
+   *
+   * This and `waitForBlock`'s deadline are elapsed-time arithmetic, so they use the
+   * raw local clock rather than `ClientOptions.now` — see the note in `chain/retry.ts`.
+   */
   healthCacheMs;
   constructor(config, options = {}) {
     this.config = config;
     this.healthCacheMs = options.healthCacheMs ?? 5e3;
-    this.client = createClient(config.url, config.anonKey, {
-      db: { schema: config.schema },
-      auth: { persistSession: false, autoRefreshToken: false },
-      global: { headers: { "x-client-info": `quaivault-sdk/${SDK_VERSION}` } }
+    this.client = new PostgrestClient(`${baseUrl(config.url)}/rest/v1`, {
+      headers: {
+        apikey: config.anonKey,
+        Authorization: `Bearer ${config.anonKey}`,
+        "x-client-info": `quaivault-sdk/${SDK_VERSION}`
+      },
+      schema: config.schema
     });
   }
-  /** Raw Supabase client, for queries the SDK does not wrap. */
-  get raw() {
+  /** The PostgREST client, for queries the SDK does not wrap. */
+  get rest() {
     return this.client;
   }
   from(table) {
     return this.client.from(table);
   }
+  /**
+   * Realtime client, constructed on first use.
+   *
+   * Lazy because it opens a WebSocket and starts a heartbeat, and the large majority
+   * of SDK usage never calls `watch()`. Nothing here should cost a socket unless
+   * somebody asked to follow a vault.
+   */
+  realtimeClient() {
+    if (!this.realtime) {
+      this.realtime = new RealtimeClient(
+        `${baseUrl(this.config.url).replace(/^http/, "ws")}/realtime/v1`,
+        { params: { apikey: this.config.anonKey } }
+      );
+    }
+    return this.realtime;
+  }
+  /** Open a Realtime channel. See `watchVault`, which is what callers should use. */
+  channel(name) {
+    return this.realtimeClient().channel(name);
+  }
+  /** Close a channel opened by {@link channel}. */
+  async removeChannel(channel) {
+    await this.realtimeClient().removeChannel(channel);
+  }
   /**
    * Run a query, parse each row, and surface failures as `IndexerQueryError`.
    *
@@ -1742,6 +1881,36 @@ var IndexerClient = class {
     }
     return (data ?? []).map((row) => schema.parse(row));
   }
+  /**
+   * Paged select: an exact `hasMore`, an approximate `total`.
+   *
+   * Both halves of that are deliberate. An `exact` count makes Postgres scan every
+   * matching row on every page request, which is invisible on a young vault and
+   * quadratic on a busy one — so the count is `estimated`, cheap and good enough for
+   * "roughly how much history is there".
+   *
+   * But `hasMore` derived from an estimate would be a lie a caller can act on: a
+   * paging loop that stops early drops real rows. So callers request one row beyond
+   * the page and this trims it, which answers "is there another page" exactly, for
+   * the cost of a single extra row.
+   */
+  async selectPage(table, schema, limit, build) {
+    const { data, error, count } = await build(this.client.from(table));
+    if (error) {
+      throw new IndexerQueryError(`Indexer query on "${table}" failed: ${error.message}`, error);
+    }
+    const rows = data ?? [];
+    const hasMore = rows.length > limit;
+    const parsed = (hasMore ? rows.slice(0, limit) : rows).map(
+      (row) => schema.parse(row)
+    );
+    return {
+      data: parsed,
+      // Never report a total below what was just handed out, however the estimate lands.
+      total: Math.max(count ?? 0, parsed.length),
+      hasMore
+    };
+  }
   /** Single-row variant. Returns null for PostgREST's "no rows" code. */
   async selectOne(table, schema, build) {
     const { data, error } = await build(this.client.from(table));
@@ -1796,7 +1965,7 @@ var IndexerClient = class {
     const pollIntervalMs = options.pollIntervalMs ?? 1500;
     const deadline = Date.now() + timeoutMs;
     for (; ; ) {
-      if (options.signal?.aborted) throw new Error("Aborted");
+      if (options.signal?.aborted) throw new AbortError("Waiting for the indexer");
       const state = await this.state();
       const head = state?.lastIndexedBlock ?? 0;
       if (head >= blockNumber) return { reached: true, lastIndexedBlock: head };
@@ -1808,12 +1977,12 @@ var IndexerClient = class {
   }
   async probeHealth() {
     if (this.config.healthUrl) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), 5e3);
       try {
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), 5e3);
         const res = await fetch(new URL("/health", this.config.healthUrl), {
           signal: controller.signal
-        }).finally(() => clearTimeout(timer));
+        });
         const body = await res.json();
         const d = body.details ?? {};
         return {
@@ -1825,6 +1994,8 @@ var IndexerClient = class {
           ...res.ok ? {} : { error: `health endpoint returned ${res.status}` }
         };
       } catch {
+      } finally {
+        clearTimeout(timer);
       }
     }
     try {
@@ -1847,10 +2018,14 @@ var IndexerClient = class {
     }
   }
 };
+function baseUrl(url) {
+  return url.replace(/\/+$/, "");
+}
 
 // src/indexer/queries.ts
 var DEFAULT_LIMIT = 50;
 var MAX_LIMIT = 200;
+var CONFIRMATION_CHUNK = 40;
 function lower(address2) {
   return address2.toLowerCase();
 }
@@ -1909,14 +2084,40 @@ var IndexerQueries = class {
       (q) => q.select("*").eq("wallet_address", lower(vault2)).eq("tx_hash", txHash.toLowerCase()).single()
     );
   }
+  /**
+   * Several transactions by hash, chunked for the same reasons as
+   * {@link activeConfirmationsBatch} — hashes are long, and they go in the query string.
+   *
+   * Rows come back in no particular order and hashes with no row are simply absent;
+   * the caller matches them up.
+   */
+  async transactionsByHash(vault2, txHashes) {
+    if (txHashes.length === 0) return [];
+    const hashes = txHashes.map((h) => h.toLowerCase());
+    const chunks = [];
+    for (let i = 0; i < hashes.length; i += CONFIRMATION_CHUNK) {
+      chunks.push(hashes.slice(i, i + CONFIRMATION_CHUNK));
+    }
+    const pages = await Promise.all(
+      chunks.map(
+        (chunk) => this.client.select(
+          "transactions",
+          TransactionSchema,
+          (q) => q.select("*").eq("wallet_address", lower(vault2)).in("tx_hash", chunk)
+        )
+      )
+    );
+    return pages.flat();
+  }
   async transactionHistory(vault2, options = {}) {
     const { limit, offset } = bounds(options);
     const statuses = options.status ?? ["executed", "cancelled", "expired", "failed"];
-    const { data, error, count } = await this.client.from("transactions").select("*", { count: "exact" }).eq("wallet_address", lower(vault2)).in("status", statuses).order("submitted_at_block", { ascending: false }).range(offset, offset + limit - 1);
-    if (error) throw new IndexerQueryError(`Indexer query failed: ${error.message}`, error);
-    const rows = (data ?? []).map((r) => TransactionSchema.parse(r));
-    const total = count ?? rows.length;
-    return { data: rows, total, hasMore: offset + rows.length < total };
+    return this.client.selectPage(
+      "transactions",
+      TransactionSchema,
+      limit,
+      (q) => q.select("*", { count: "estimated" }).eq("wallet_address", lower(vault2)).in("status", statuses).order("submitted_at_block", { ascending: false }).range(offset, offset + limit)
+    );
   }
   /** All confirmations for one transaction, including revoked ones. */
   async confirmations(vault2, txHash) {
@@ -1927,26 +2128,41 @@ var IndexerQueries = class {
     );
   }
   /**
-   * Active confirmations for many transactions in one round trip.
+   * Active confirmations for many transactions, in as few round trips as is safe.
    *
    * "Active" here means not revoked. It does NOT mean the confirming address is
    * still an owner — the indexer does not deactivate confirmations when an owner is
    * removed, while the contract invalidates them via approval epochs. Callers must
    * intersect with the active owner set; `Vault` does this for you.
+   *
+   * Chunked rather than issued as one `in(...)`, because a single filter fails two
+   * ways at scale. PostgREST reads filters from the query string, and each 32-byte
+   * hash costs ~70 characters there — a full {@link MAX_LIMIT} page of hashes builds a
+   * ~14 KB request line, past the 8 KB cap most reverse proxies apply by default. The
+   * response is bounded too: {@link CONFIRMATION_CHUNK} transactions can carry at most
+   * `chunk × MAX_OWNERS` rows, and the chunk is sized to keep that under the
+   * `max-rows` ceiling PostgREST deployments commonly set, so a busy vault cannot be
+   * silently short-served.
    */
   async activeConfirmationsBatch(vault2, txHashes) {
     const result = /* @__PURE__ */ new Map();
     for (const hash of txHashes) result.set(hash.toLowerCase(), []);
     if (txHashes.length === 0) return result;
-    const rows = await this.client.select(
-      "confirmations",
-      ConfirmationSchema,
-      (q) => q.select("*").eq("wallet_address", lower(vault2)).in(
-        "tx_hash",
-        txHashes.map((h) => h.toLowerCase())
-      ).eq("is_active", true)
+    const hashes = txHashes.map((h) => h.toLowerCase());
+    const chunks = [];
+    for (let i = 0; i < hashes.length; i += CONFIRMATION_CHUNK) {
+      chunks.push(hashes.slice(i, i + CONFIRMATION_CHUNK));
+    }
+    const pages = await Promise.all(
+      chunks.map(
+        (chunk) => this.client.select(
+          "confirmations",
+          ConfirmationSchema,
+          (q) => q.select("*").eq("wallet_address", lower(vault2)).in("tx_hash", chunk).eq("is_active", true)
+        )
+      )
     );
-    for (const row of rows) {
+    for (const row of pages.flat()) {
       const key = row.tx_hash.toLowerCase();
       const list = result.get(key);
       if (list) list.push(row);
@@ -1974,19 +2190,52 @@ var IndexerQueries = class {
   // ---- value movement ------------------------------------------------------
   async deposits(vault2, options = {}) {
     const { limit, offset } = bounds(options);
-    const { data, error, count } = await this.client.from("deposits").select("*", { count: "exact" }).eq("wallet_address", lower(vault2)).order("deposited_at_block", { ascending: false }).range(offset, offset + limit - 1);
-    if (error) throw new IndexerQueryError(`Indexer query failed: ${error.message}`, error);
-    const rows = (data ?? []).map((r) => DepositSchema.parse(r));
-    const total = count ?? rows.length;
-    return { data: rows, total, hasMore: offset + rows.length < total };
+    return this.client.selectPage(
+      "deposits",
+      DepositSchema,
+      limit,
+      (q) => q.select("*", { count: "estimated" }).eq("wallet_address", lower(vault2)).order("deposited_at_block", { ascending: false }).range(offset, offset + limit)
+    );
   }
   async tokenTransfers(vault2, options = {}) {
     const { limit, offset } = bounds(options);
-    const { data, error, count } = await this.client.from("token_transfers").select("*", { count: "exact" }).eq("wallet_address", lower(vault2)).order("block_number", { ascending: false }).range(offset, offset + limit - 1);
-    if (error) throw new IndexerQueryError(`Indexer query failed: ${error.message}`, error);
-    const rows = (data ?? []).map((r) => TokenTransferSchema.parse(r));
-    const total = count ?? rows.length;
-    return { data: rows, total, hasMore: offset + rows.length < total };
+    return this.client.selectPage(
+      "token_transfers",
+      TokenTransferSchema,
+      limit,
+      (q) => q.select("*", { count: "estimated" }).eq("wallet_address", lower(vault2)).order("block_number", { ascending: false }).range(offset, offset + limit)
+    );
+  }
+  /**
+   * Scan up to `budget` of the most recent transfer rows, paging past {@link MAX_LIMIT}.
+   *
+   * `tokenTransfers` clamps a single request, so a caller asking for more than the cap
+   * silently received a short page — and then computed "did I see everything?" from
+   * that short page's `hasMore`, which reported truncation the caller had not actually
+   * hit. Paging here keeps the caller's budget meaningful and makes the returned
+   * `hasMore` mean what it says: rows exist beyond the budget that was scanned.
+   *
+   * Pages by offset over a descending order, so a transfer landing mid-scan can shift
+   * rows by one. That is acceptable for token *discovery* — a duplicate collapses into
+   * the same map key and a missed row costs at most one candidate that the next call
+   * picks up. Do not reuse this for anything that must see each row exactly once.
+   */
+  async tokenTransferScan(vault2, budget) {
+    const target = Math.max(1, Math.floor(budget));
+    const data = [];
+    let total = 0;
+    let hasMore = false;
+    while (data.length < target) {
+      const page = await this.tokenTransfers(vault2, {
+        limit: Math.min(MAX_LIMIT, target - data.length),
+        offset: data.length
+      });
+      data.push(...page.data);
+      total = page.total;
+      hasMore = page.hasMore;
+      if (page.data.length === 0 || !page.hasMore) break;
+    }
+    return { data, total, hasMore };
   }
   async tokens(addresses) {
     if (addresses.length === 0) return [];
@@ -2178,39 +2427,7 @@ var RecoveryContract = class {
   }
 };
 
-// src/lifecycle/status.ts
-function nowSeconds() {
-  return Math.floor(Date.now() / 1e3);
-}
-function executableAfterOf(approvedAt, executionDelay) {
-  return approvedAt > 0 ? approvedAt + executionDelay : 0;
-}
-function deriveStatus(state, at = nowSeconds()) {
-  if (state.failed) return "failed";
-  if (state.executed) return "executed";
-  if (state.cancelled) return state.isExpired ? "expired" : "cancelled";
-  if (state.expiration > 0 && at > state.expiration) return "expired";
-  if (state.approvalCount < state.threshold) return "pending";
-  const executableAfter = executableAfterOf(state.approvedAt, state.executionDelay);
-  if (state.executionDelay > 0 && (state.approvedAt === 0 || at < executableAfter)) {
-    return "timelocked";
-  }
-  return "ready";
-}
-function isTerminal(status) {
-  return status === "executed" || status === "failed" || status === "cancelled" || status === "expired";
-}
-function deriveRecoveryStatus(state, at = nowSeconds()) {
-  if (state.executed) return "executed";
-  if (state.expiration > 0 && at > state.expiration) return "expired";
-  if (state.approvalCount < state.requiredThreshold) return "pending";
-  if (at < state.executionTime) return "timelocked";
-  return "ready";
-}
-
 // src/recovery.ts
-var SENTINEL = "0x0000000000000000000000000000000000000001";
-var ZERO = "0x0000000000000000000000000000000000000000";
 var RecoveryModule = class {
   constructor(ctx) {
     this.ctx = ctx;
@@ -2232,14 +2449,27 @@ var RecoveryModule = class {
   get vault() {
     return this.ctx.vaultAddress;
   }
+  /**
+   * The vault this module acts on, through the same retrying facade every other vault
+   * read in the SDK uses. Recovery reaches into the vault for three checks — is the
+   * module enabled, is the caller an owner, who are the current owners — and each of
+   * them gates a write, so none of them should be the one read that silently skips
+   * transient-failure handling.
+   */
+  /** Now, in Unix seconds, for anything compared against a chain timestamp. */
+  now() {
+    return (this.ctx.now ?? nowSeconds)();
+  }
+  vaultContract() {
+    return new VaultContract(this.ctx.connection.vault(this.vault), this.ctx.connection.retry);
+  }
   // =========================================================================
   // Reads
   // =========================================================================
   /** Whether the module is currently enabled on the vault. */
   async isEnabled() {
     if (!this.ctx.moduleAddress) return false;
-    const vault2 = this.ctx.connection.vault(this.vault);
-    return vault2.getFunction("isModuleEnabled(address)")(this.address);
+    return this.vaultContract().isModuleEnabled(this.address);
   }
   async config() {
     const raw = await this.contract().getRecoveryConfig(this.vault);
@@ -2297,7 +2527,7 @@ var RecoveryModule = class {
    */
   async history(options = {}) {
     const queries = this.ctx.queries;
-    if (!queries) return [];
+    if (!queries) throw new NoIndexerError("Listing recovery history");
     const rows = await queries.recoveryHistory(this.vault, options);
     return rows.map((row) => ({
       hash: row.recovery_hash,
@@ -2317,7 +2547,7 @@ var RecoveryModule = class {
         requiredThreshold: row.required_threshold,
         executionTime: Number(row.execution_time),
         expiration: Number(row.expiration ?? 0)
-      }),
+      }, this.now()),
       executed: row.status === "executed",
       initiator: getAddress3(row.initiator_address),
       source: "indexer"
@@ -2426,21 +2656,20 @@ var RecoveryModule = class {
         `Not enough guardian approvals: ${request.approvalCount} of ${request.requiredThreshold}.`
       );
     }
-    const now = nowSeconds();
+    const now = this.now();
     if (now < request.executionTime) {
       throw new PreconditionError(
         `The recovery period has not elapsed. Executable after ${new Date(request.executionTime * 1e3).toISOString()}.`,
         { retryableAt: request.executionTime }
       );
     }
-    const vault2 = this.ctx.connection.vault(this.vault);
-    const currentOwners = await vault2.getFunction("getOwners()")();
+    const currentOwners = await this.vaultContract().getOwners();
     const current = new Set(Array.from(currentOwners).map((o) => String(o).toLowerCase()));
     const overlap = request.newOwners.filter((o) => current.has(o.toLowerCase())).length;
     const peak = current.size + request.newOwners.length - overlap;
-    if (peak > 20) {
+    if (peak > MAX_OWNERS) {
       throw new PreconditionError(
-        `Executing this recovery would transiently hold ${peak} owners, above the 20-owner maximum \u2014 new owners are added before old ones are removed.`,
+        `Executing this recovery would transiently hold ${peak} owners, above the ${MAX_OWNERS}-owner maximum \u2014 new owners are added before old ones are removed.`,
         {
           remediation: "Run a recovery that retains at least one existing owner, then a second recovery to replace it."
         }
@@ -2455,8 +2684,7 @@ var RecoveryModule = class {
   async cancel(recoveryHash) {
     const hash = normalizeTxHash(recoveryHash, "recovery hash");
     const caller = await this.ctx.connection.address();
-    const vault2 = this.ctx.connection.vault(this.vault);
-    const isOwner = await vault2.getFunction("isOwner(address)")(caller);
+    const isOwner = await this.vaultContract().isOwner(caller);
     if (!isOwner) {
       throw new PreconditionError(
         `Only a current owner of the vault can cancel a recovery. ${caller} is not one.`
@@ -2473,7 +2701,7 @@ var RecoveryModule = class {
   // Affordances
   // =========================================================================
   /** What `caller` may do to a recovery right now, and when blocked actions unlock. */
-  async affordances(recoveryHash, caller) {
+  async affordances(recoveryHash, caller, at) {
     const hash = normalizeTxHash(recoveryHash, "recovery hash");
     const who = caller ?? await this.ctx.connection.addressOrNull();
     if (!who) {
@@ -2487,9 +2715,9 @@ var RecoveryModule = class {
       this.isGuardian(address2),
       this.contract().recoveryApprovals(this.vault, hash, address2),
       this.isEnabled(),
-      this.ctx.connection.vault(this.vault).getFunction("isOwner(address)")(address2)
+      this.vaultContract().isOwner(address2)
     ]);
-    const now = nowSeconds();
+    const now = at ?? this.now();
     const terminal = request.status === "executed" || request.status === "cancelled";
     const expired = now > request.expiration && request.expiration > 0;
     const quorum = request.approvalCount >= request.requiredThreshold;
@@ -2586,13 +2814,10 @@ var RecoveryModule = class {
     const approvalCount = Number(raw.approvalCount ?? 0);
     const requiredThreshold = Number(raw.requiredThreshold ?? 0);
     const executed = Boolean(raw.executed);
-    const status = deriveRecoveryStatus({
-      executed,
-      approvalCount,
-      requiredThreshold,
-      executionTime,
-      expiration
-    });
+    const status = deriveRecoveryStatus(
+      { executed, approvalCount, requiredThreshold, executionTime, expiration },
+      this.now()
+    );
     return {
       hash,
       vault: this.vault,
@@ -2612,7 +2837,7 @@ var RecoveryModule = class {
     const seen = /* @__PURE__ */ new Set();
     for (const owner of newOwners) {
       const key = owner.toLowerCase();
-      if (key === ZERO || key === SENTINEL) {
+      if (key === ZERO_ADDRESS || key === SENTINEL_MODULES) {
         throw new ValidationError(
           `New owner ${owner} is reserved \u2014 the zero address and the module sentinel 0x\u202601 are rejected.`
         );
@@ -2633,7 +2858,7 @@ var RecoveryModule = class {
     if (request.executed) {
       throw new PreconditionError("This recovery has already been executed.");
     }
-    if (request.expiration > 0 && nowSeconds() > request.expiration) {
+    if (request.expiration > 0 && this.now() > request.expiration) {
       throw new PreconditionError("This recovery has expired.", {
         remediation: "Call expire() to clean it up, then initiate a new recovery."
       });
@@ -2693,16 +2918,61 @@ function terminalReason(request) {
 }
 
 // src/balances.ts
-import { Contract as Contract2, getAddress as getAddress4 } from "quais";
+import { getAddress as getAddress4 } from "quais";
+
+// src/chain/token-contract.ts
+var TOKEN_RETRY = { maxAttempts: 2, baseDelayMs: 150 };
+var TokenContract = class {
+  constructor(contract, retry = {}) {
+    this.contract = contract;
+    this.retry = { ...TOKEN_RETRY, ...retry };
+  }
+  contract;
+  retry;
+  read(signature, ...args) {
+    return withRetry(() => this.contract.getFunction(signature)(...args), this.retry);
+  }
+  /** ERC20 units held, or — for ERC721 — the number of tokens held. */
+  balanceOf(owner) {
+    return this.read("balanceOf(address)", owner);
+  }
+  /** ERC721 only. Reverts for a burned or never-minted id. */
+  ownerOf(tokenId) {
+    return this.read("ownerOf(uint256)", tokenId);
+  }
+  /** ERC1155 only. One call for many ids, so it stays a single round trip. */
+  balanceOfBatch(owners, ids) {
+    return this.read("balanceOfBatch(address[],uint256[])", owners, ids);
+  }
+};
+
+// src/pool.ts
+async function mapPooled(items, limit, fn) {
+  const results = new Array(items.length);
+  let next = 0;
+  const worker = async () => {
+    for (; ; ) {
+      const i = next++;
+      if (i >= items.length) return;
+      results[i] = await fn(items[i], i);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+  return results;
+}
+var DEFAULT_CONCURRENCY = 8;
+
+// src/balances.ts
 async function loadBalances(connection, queries, vault2, options = {}) {
   const verify = options.verify !== false;
   const maxTokens = options.maxTokens ?? 50;
   const transferScanLimit = options.transferScanLimit ?? 500;
   const maxTokenIdChecks = options.maxTokenIdChecks ?? 100;
+  const concurrency = Math.max(1, options.concurrency ?? DEFAULT_CONCURRENCY);
   const address2 = getAddress4(vault2);
   const native = BigInt(await connection.provider.getBalance(address2));
   if (!queries) return { native, tokens: [] };
-  const transfers = await queries.tokenTransfers(address2, { limit: transferScanLimit });
+  const transfers = await queries.tokenTransferScan(address2, transferScanLimit);
   const seen = /* @__PURE__ */ new Map();
   for (const row of transfers.data) {
     const key = row.token_address.toLowerCase();
@@ -2721,17 +2991,18 @@ async function loadBalances(connection, queries, vault2, options = {}) {
   }
   const metadata = await queries.tokens(candidates);
   const byAddress = new Map(metadata.map((t) => [t.address.toLowerCase(), t]));
-  const balances = await Promise.all(
-    candidates.map(
-      (token2) => buildBalance(
-        connection,
-        address2,
-        token2,
-        byAddress.get(token2),
-        seen.get(token2) ?? [],
-        verify,
-        maxTokenIdChecks
-      )
+  const balances = await mapPooled(
+    candidates,
+    concurrency,
+    (token2) => buildBalance(
+      connection,
+      address2,
+      token2,
+      byAddress.get(token2),
+      seen.get(token2) ?? [],
+      verify,
+      maxTokenIdChecks,
+      concurrency
     )
   );
   return {
@@ -2741,30 +3012,35 @@ async function loadBalances(connection, queries, vault2, options = {}) {
     ...Object.keys(truncated).length ? { truncated } : {}
   };
 }
-async function buildBalance(connection, vault2, token2, meta, transfers, verify, maxTokenIdChecks) {
+async function buildBalance(connection, vault2, token2, meta, transfers, verify, maxTokenIdChecks, concurrency) {
   const standard = meta?.standard ?? inferStandard(transfers);
   const replayed = replayBalance(transfers, standard);
   const base = {
     token: getAddress4(token2),
     standard,
-    symbol: meta?.symbol ?? "???",
-    name: meta?.name ?? "Unknown token",
+    // Deployer-controlled strings headed for someone's terminal. See `src/text.ts`.
+    symbol: sanitizeText(meta?.symbol, 32) || "???",
+    name: sanitizeText(meta?.name, 64) || "Unknown token",
     decimals: meta?.decimals ?? (standard === "ERC20" ? 18 : 0),
     balance: replayed.balance,
     ...replayed.tokenIds.length > 0 ? { tokenIds: replayed.tokenIds } : {},
     verified: false
   };
   if (!verify) return base;
+  const contract = new TokenContract(connection.token(token2, standard), connection.retry);
   try {
     if (standard === "ERC20") {
-      const contract2 = new Contract2(token2, Erc20Abi, connection.provider);
-      const balance = await contract2.getFunction("balanceOf(address)")(vault2);
-      return { ...base, balance: BigInt(balance), verified: true };
+      return { ...base, balance: BigInt(await contract.balanceOf(vault2)), verified: true };
     }
     if (standard === "ERC721") {
-      const contract2 = new Contract2(token2, Erc721Abi, connection.provider);
-      const count = await contract2.getFunction("balanceOf(address)")(vault2);
-      const owned = await filterOwned(contract2, vault2, replayed.tokenIds, maxTokenIdChecks);
+      const count = await contract.balanceOf(vault2);
+      const owned = await filterOwned(
+        contract,
+        vault2,
+        replayed.tokenIds,
+        maxTokenIdChecks,
+        concurrency
+      );
       return {
         ...base,
         balance: BigInt(count),
@@ -2773,10 +3049,9 @@ async function buildBalance(connection, vault2, token2, meta, transfers, verify,
         verified: true
       };
     }
-    const contract = new Contract2(token2, Erc1155Abi, connection.provider);
     const ids = replayed.tokenIds;
     if (ids.length === 0) return { ...base, verified: true };
-    const amounts = await contract.getFunction("balanceOfBatch(address[],uint256[])")(
+    const amounts = await contract.balanceOfBatch(
       ids.map(() => vault2),
       ids
     );
@@ -2821,18 +3096,16 @@ function replayBalance(transfers, standard) {
   }
   return { balance, tokenIds };
 }
-async function filterOwned(contract, vault2, ids, limit) {
+async function filterOwned(contract, vault2, ids, limit, concurrency) {
   if (ids.length === 0) return [];
-  const results = await Promise.all(
-    ids.slice(0, limit).map(async (id) => {
-      try {
-        const owner = await contract.getFunction("ownerOf(uint256)")(id);
-        return owner.toLowerCase() === vault2.toLowerCase() ? id : null;
-      } catch {
-        return null;
-      }
-    })
-  );
+  const results = await mapPooled(ids.slice(0, limit), concurrency, async (id) => {
+    try {
+      const owner = await contract.ownerOf(id);
+      return owner.toLowerCase() === vault2.toLowerCase() ? id : null;
+    } catch {
+      return null;
+    }
+  });
   return results.filter((id) => id !== null);
 }
 function inferStandard(transfers) {
@@ -2868,7 +3141,7 @@ function watchVault(client, vault2, handler, options = {}) {
   const topics = options.topics ?? DEFAULT_TOPICS;
   const address2 = vault2.toLowerCase();
   const schema = client.config.schema;
-  const channel = client.raw.channel(`quaivault:${schema}:${address2}`);
+  const channel = client.channel(`quaivault:${schema}:${address2}`);
   for (const topic of topics) {
     const table = TABLE_FOR[topic];
     channel.on(
@@ -2898,7 +3171,7 @@ function watchVault(client, vault2, handler, options = {}) {
   return {
     topics,
     async unsubscribe() {
-      await client.raw.removeChannel(channel);
+      await client.removeChannel(channel);
     }
   };
 }
@@ -3347,8 +3620,9 @@ function classifyExecution(receipt, vault2, txHash) {
   }
   const thresholdReached = eventFor(events, "ThresholdReached", txHash);
   if (thresholdReached) {
+    const approvedAt = toNumber2(thresholdReached.args.approvedAt);
     const executableAfter = toNumber2(thresholdReached.args.executableAfter);
-    if (executableAfter > Math.floor(Date.now() / 1e3)) {
+    if (executableAfter > approvedAt) {
       return {
         ...base,
         outcome: "timelock_started",
@@ -3378,7 +3652,7 @@ function extractProposedTxHash(receipt, vault2) {
 }
 
 // src/vault.ts
-var Vault = class {
+var Vault = class _Vault {
   address;
   /** Guardian-based recovery for this vault. */
   recovery;
@@ -3390,7 +3664,8 @@ var Vault = class {
       connection: ctx.connection,
       queries: ctx.queries,
       vaultAddress: this.address,
-      moduleAddress: ctx.contracts.socialRecovery
+      moduleAddress: ctx.contracts.socialRecovery,
+      ...ctx.now ? { now: ctx.now } : {}
     });
   }
   // =========================================================================
@@ -3421,6 +3696,30 @@ var Vault = class {
     if (!this.ctx.queries) throw new NoIndexerError(operation);
     return this.ctx.queries;
   }
+  /**
+   * The indexer's head, for stamping onto records read from it.
+   *
+   * Reads the cached health result rather than querying `indexer_state` directly.
+   * `useIndexer()` has just called `health()` on this same code path and the result is
+   * cached, so this is free — whereas a `state()` call is a second round trip per
+   * hydration, paid on every indexed read purely to fill one advisory field.
+   *
+   * Undefined when the indexer is not answering: a head of 0 would read as "indexed at
+   * genesis" rather than "unknown".
+   */
+  async indexerHead() {
+    const health = await this.ctx.indexer?.health();
+    return health?.available ? health.lastIndexedBlock : void 0;
+  }
+  /**
+   * Now, in Unix seconds, for anything compared against a chain timestamp.
+   *
+   * Never used to measure elapsed time — see the duration sites in
+   * {@link waitForExecutable}, which stay on the raw local clock deliberately.
+   */
+  now() {
+    return (this.ctx.now ?? nowSeconds)();
+  }
   contract(write = false) {
     return new VaultContract(this.ctx.connection.vault(this.address, write), this.ctx.connection.retry);
   }
@@ -3448,8 +3747,48 @@ var Vault = class {
       balance: BigInt(balance)
     };
   }
-  /** Active owners. Prefers the indexer, falls back to chain. */
+  /**
+   * Capture owners and threshold once, for reuse across a burst of reads.
+   *
+   * Pair with {@link pinned}:
+   *
+   * ```ts
+   * const view = await vault.view();
+   * const pinned = vault.pinned(view);
+   * // every read below shares one owner/threshold read
+   * const txs = await pinned.transactions(hashes);
+   * ```
+   */
+  async view() {
+    const fromIndexer = await this.useIndexer();
+    const [owners, threshold, indexedAtBlock] = await Promise.all([
+      this.owners(),
+      this.threshold(),
+      this.indexerHead()
+    ]);
+    return {
+      owners,
+      threshold,
+      ...indexedAtBlock !== void 0 ? { indexedAtBlock } : {},
+      capturedAt: this.now(),
+      source: fromIndexer ? "indexer" : "chain"
+    };
+  }
+  /**
+   * A handle that answers {@link owners} and {@link threshold} from `view` instead of
+   * re-reading them.
+   *
+   * Reads only. Write preconditions go through `chainOwners` / `chainThreshold`, which
+   * bypass the snapshot by construction — pinning a view can never cause this SDK to
+   * sign against a stale owner set. Everything else about the handle, including the
+   * connection and the recovery module, is shared with the original.
+   */
+  pinned(view) {
+    return new _Vault(this.address, { ...this.ctx, view });
+  }
+  /** Active owners. Prefers a pinned view, then the indexer, then chain. */
   async owners() {
+    if (this.ctx.view) return this.ctx.view.owners;
     if (await this.useIndexer()) {
       try {
         const owners = await this.requireQueries("owners").owners(this.address);
@@ -3457,12 +3796,55 @@ var Vault = class {
       } catch {
       }
     }
+    return this.chainOwners();
+  }
+  /**
+   * Owners straight from the chain, bypassing the indexer entirely.
+   *
+   * {@link owners} prefers the indexer, which is right for display and wrong for
+   * anything that gates a write. A lagging indexer would let the SDK build a proposal
+   * against an owner set that no longer exists — admitting a `removeOwner` that drops
+   * the vault below its threshold, or rejecting one that is perfectly valid. Every
+   * propose-time precondition reads through here instead.
+   */
+  async chainOwners() {
     return (await this.contract().getOwners()).map((o) => getAddress5(String(o)));
   }
   async isOwner(address2) {
     return this.contract().isOwner(getAddress5(address2));
   }
+  /**
+   * Whether `owner`'s approval on `txHash` currently counts toward the threshold.
+   *
+   * Reads the chain, and accounts for approval-epoch invalidation: removing an owner
+   * bumps the vault's epoch and voids every approval that address made, so a
+   * confirmation the indexer still lists may already be dead. This is the authoritative
+   * answer.
+   *
+   * Public because it is one of the two inputs {@link computeAffordances} needs. Without
+   * it a consumer wanting affordances at an adjusted time had no way to assemble an
+   * `AffordanceContext` short of reimplementing this method against the raw contract.
+   */
+  async hasApproved(txHash, owner) {
+    return this.contract().hasApproved(normalizeTxHash(txHash), getAddress5(owner));
+  }
+  /** Approvals required to execute. Prefers a pinned view, then the indexer, then chain. */
   async threshold() {
+    if (this.ctx.view) return this.ctx.view.threshold;
+    if (await this.useIndexer()) {
+      try {
+        const wallet = await this.requireQueries("threshold").wallet(this.address);
+        if (wallet) return wallet.threshold;
+      } catch {
+      }
+    }
+    return this.chainThreshold();
+  }
+  /**
+   * Threshold straight from the chain. The write-path counterpart to {@link threshold},
+   * for the same reason {@link chainOwners} exists.
+   */
+  async chainThreshold() {
     return Number(await this.contract().threshold());
   }
   async balance() {
@@ -3515,6 +3897,53 @@ var Vault = class {
     }
     return this.fromChain(hash);
   }
+  /**
+   * Several transactions at once, keyed by hash.
+   *
+   * The plural form exists because the singular one is expensive to loop: each
+   * `transaction()` re-reads the owner set, the threshold and the indexer head, so
+   * fetching fifty costs fifty times that. This resolves the whole set the way the
+   * listing methods already do — one query for the rows, one owner/threshold read
+   * shared across them, one batched confirmations query.
+   *
+   * Hashes the indexer does not have fall back to chain reads, bounded by a pool.
+   * Hashes that exist nowhere are simply absent from the map rather than throwing:
+   * one unknown hash should not lose the caller the other forty-nine.
+   */
+  async transactions(txHashes) {
+    const hashes = [...new Set(txHashes.map((h) => normalizeTxHash(h)))];
+    const found = /* @__PURE__ */ new Map();
+    if (hashes.length === 0) return found;
+    if (await this.useIndexer()) {
+      try {
+        const queries = this.requireQueries("Reading transactions");
+        const [rows, owners, threshold] = await Promise.all([
+          queries.transactionsByHash(this.address, hashes),
+          this.owners(),
+          this.threshold()
+        ]);
+        for (const tx of await this.hydrateRows(rows, owners, threshold)) {
+          found.set(tx.hash.toLowerCase(), tx);
+        }
+      } catch {
+      }
+    }
+    const missing = hashes.filter((hash) => !found.has(hash));
+    if (missing.length > 0) {
+      const resolved = await mapPooled(missing, DEFAULT_CONCURRENCY, async (hash) => {
+        try {
+          return await this.fromChain(hash);
+        } catch (err) {
+          if (err instanceof NotFoundError) return null;
+          throw err;
+        }
+      });
+      for (const tx of resolved) {
+        if (tx) found.set(tx.hash.toLowerCase(), tx);
+      }
+    }
+    return found;
+  }
   async pendingTransactions(options = {}) {
     const queries = this.requireQueries("Listing pending transactions");
     const [rows, owners, threshold] = await Promise.all([
@@ -3545,7 +3974,7 @@ var Vault = class {
       this.address,
       rows.map((r) => r.tx_hash)
     );
-    const indexedAtBlock = (await this.ctx.indexer?.state())?.lastIndexedBlock;
+    const indexedAtBlock = await this.indexerHead();
     return rows.map((row) => {
       const confirmed = (confirmations.get(row.tx_hash.toLowerCase()) ?? []).map(
         (c) => c.owner_address
@@ -3568,7 +3997,7 @@ var Vault = class {
     ]);
     if (!row) return null;
     const confirmations = await queries.confirmations(this.address, hash);
-    const indexedAtBlock = (await this.ctx.indexer?.state())?.lastIndexedBlock;
+    const indexedAtBlock = await this.indexerHead();
     return this.buildTransaction({
       row,
       confirmedBy: confirmations.filter((c) => c.is_active).map((c) => c.owner_address),
@@ -3622,7 +4051,7 @@ var Vault = class {
       approvalCount,
       threshold,
       failed: row.status === "failed"
-    });
+    }, this.now());
     const failedReturnData = row.failed_return_data ?? void 0;
     return {
       hash: row.tx_hash,
@@ -3631,7 +4060,10 @@ var Vault = class {
       value,
       data,
       proposer: getAddress5(row.submitted_by),
-      proposedAt: toNumber(row.submitted_at_block),
+      // The indexer records the block, not the chain timestamp — they are not
+      // interchangeable, and reporting a block number as `proposedAt` renders as 1970.
+      proposedAt: 0,
+      proposedAtBlock: toNumber(row.submitted_at_block),
       kind: decodeResult.kind,
       decoded: decodeResult.decoded,
       summary: decodeResult.summary,
@@ -3702,7 +4134,7 @@ var Vault = class {
         approvedAt,
         approvalCount: approvals.length,
         threshold: Number(threshold)
-      }),
+      }, this.now()),
       approvals,
       approvalCount: approvals.length,
       threshold: Number(threshold),
@@ -3720,8 +4152,20 @@ var Vault = class {
    * What `caller` may legally do to `txHash` right now, and when blocked actions
    * become available. Defaults to the connected signer's address.
    */
-  async affordances(txHash, caller) {
+  async affordances(txHash, caller, at) {
     const hash = normalizeTxHash(txHash);
+    return this.resolveAffordances(hash, this.transaction(hash), caller, at);
+  }
+  /**
+   * Shared body of {@link affordances}, taking the transaction either as a value or as
+   * an in-flight promise.
+   *
+   * The promise form is the point: a caller that already holds the record (like
+   * {@link describe}) passes it and skips a redundant fetch, while `affordances()`
+   * passes the unawaited promise so the transaction read still overlaps the two
+   * ownership probes rather than serialising behind them.
+   */
+  async resolveAffordances(hash, transaction, caller, at) {
     const who = caller ?? await this.ctx.connection.addressOrNull();
     if (!who) {
       throw new ValidationError(
@@ -3730,11 +4174,17 @@ var Vault = class {
     }
     const vault2 = this.contract();
     const [tx, isOwner, hasApproved] = await Promise.all([
-      this.transaction(hash),
+      transaction,
       vault2.isOwner(getAddress5(who)),
       vault2.hasApproved(hash, getAddress5(who))
     ]);
-    return computeAffordances({ tx, caller: getAddress5(who), isOwner, hasApproved });
+    return computeAffordances({
+      tx,
+      caller: getAddress5(who),
+      isOwner,
+      hasApproved,
+      at: at ?? this.now()
+    });
   }
   // =========================================================================
   // Proposals
@@ -3825,7 +4275,7 @@ var Vault = class {
     // --- self-calls -------------------------------------------------------
     addOwner: async (owner, options = {}) => this.proposeSelfCall(selfCall.addOwner(assertQuaiAddress(owner, "owner")), options),
     removeOwner: async (owner, options = {}) => {
-      const [owners, threshold] = await Promise.all([this.owners(), this.threshold()]);
+      const [owners, threshold] = await Promise.all([this.chainOwners(), this.chainThreshold()]);
       if (!owners.some((o) => o.toLowerCase() === owner.toLowerCase())) {
         throw new PreconditionError(`${owner} is not an owner of this vault.`);
       }
@@ -3838,7 +4288,7 @@ var Vault = class {
       return this.proposeSelfCall(selfCall.removeOwner(getAddress5(owner)), options);
     },
     changeThreshold: async (threshold, options = {}) => {
-      const owners = await this.owners();
+      const owners = await this.chainOwners();
       if (threshold < 1 || threshold > owners.length) {
         throw new ValidationError(
           `Invalid threshold ${threshold}: this vault has ${owners.length} owners.`
@@ -3945,11 +4395,11 @@ var Vault = class {
     }
     if (expiration > 0) {
       const floor = isSelfCall ? 0 : Math.max(executionDelay, await this.minExecutionDelay());
-      const earliest = minimumExpiration(floor, 0);
+      const earliest = minimumExpiration(floor, 0, this.now());
       if (expiration <= earliest) {
         throw new ValidationError(
           `expiration ${expiration} is too soon: with an effective delay of ${floor}s the vault requires an expiration after ${earliest}.`,
-          `Use at least ${minimumExpiration(floor)} to leave a margin for block time.`
+          `Use at least ${minimumExpiration(floor, 300, this.now())} to leave a margin for block time.`
         );
       }
     }
@@ -4272,9 +4722,7 @@ var Vault = class {
     const pollIntervalMs = options.pollIntervalMs ?? 15e3;
     const deadline = Date.now() + timeoutMs;
     for (; ; ) {
-      if (options.signal?.aborted) {
-        throw new PreconditionError("Waiting for the transaction was aborted.");
-      }
+      if (options.signal?.aborted) throw new AbortError("Waiting for the transaction");
       const tx = await this.fromChain(hash);
       options.onPoll?.(tx);
       if (tx.status === "ready") return tx;
@@ -4290,7 +4738,7 @@ var Vault = class {
           { remediation: "Collect the remaining approvals, then wait for the timelock." }
         );
       }
-      const untilExecutable = tx.executableAfter > 0 ? tx.executableAfter * 1e3 - Date.now() : pollIntervalMs;
+      const untilExecutable = tx.executableAfter > 0 ? (tx.executableAfter - this.now()) * 1e3 : pollIntervalMs;
       const wait = Math.max(1e3, Math.min(untilExecutable, pollIntervalMs));
       if (Date.now() + wait > deadline) {
         throw new PreconditionError(
@@ -4320,7 +4768,7 @@ var Vault = class {
       lines.push(`  quorum reached: ${new Date(tx.approvedAt * 1e3).toISOString()}`);
     }
     if (tx.executableAfter > 0) {
-      const remaining = tx.executableAfter - nowSeconds();
+      const remaining = tx.executableAfter - this.now();
       lines.push(
         `  executable after: ${new Date(tx.executableAfter * 1e3).toISOString()}` + (remaining > 0 ? ` (in ${remaining}s)` : " (now)")
       );
@@ -4331,7 +4779,7 @@ var Vault = class {
     if (tx.decodedRevert) lines.push(`  revert: ${tx.decodedRevert.message}`);
     lines.push(`  source: ${tx.source}`);
     if (caller || this.ctx.connection.hasSigner()) {
-      const affordances = await this.affordances(txHash, caller);
+      const affordances = await this.resolveAffordances(tx.hash, tx, caller);
       const allowed = affordances.filter((a) => a.allowed).map((a) => a.action);
       lines.push(`  you can: ${allowed.length > 0 ? allowed.join(", ") : "nothing right now"}`);
     }
@@ -4365,6 +4813,11 @@ function toRevertError(err, context) {
 
 // src/client.ts
 var QuaiVaultClient = class {
+  /**
+   * Source of "now" for time compared against chain timestamps. Resolved once from
+   * {@link ClientOptions.now}, defaulting to the local clock. See {@link Clock}.
+   */
+  now;
   /**
    * Resolved configuration, with the private key stripped and the indexer key
    * masked — safe to log. The key itself is consumed once when building the signer.
@@ -4377,6 +4830,7 @@ var QuaiVaultClient = class {
   constructor(options = {}) {
     const resolved = resolveConfig(options);
     this.config = redactConfig(resolved);
+    this.now = resolved.now;
     this.connection = new Connection(resolved, {
       ...options.provider ? { provider: options.provider } : {},
       ...options.signer ? { signer: options.signer } : {}
@@ -4412,7 +4866,8 @@ var QuaiVaultClient = class {
       queries: this.queries,
       contracts: this.config.contracts,
       consistency: this.config.consistency,
-      maxIndexerLagBlocks: this.config.maxIndexerLagBlocks
+      maxIndexerLagBlocks: this.config.maxIndexerLagBlocks,
+      now: this.now
     };
   }
   /** Vault discovery. Requires the indexer — there is no on-chain reverse index. */
@@ -4462,8 +4917,11 @@ function connect(options = {}) {
 }
 var QuaiVault = { connect };
 export {
+  AbortError,
   ConfigError,
   Connection,
+  DEFAULT_CONCURRENCY,
+  DEFAULT_TEXT_LIMIT,
   ENV_VARS,
   Erc1155Abi,
   Erc20Abi,
@@ -4496,9 +4954,11 @@ export {
   SaltMiningError,
   SocialRecoveryModuleAbi,
   StaleProposalError,
+  TokenContract,
   ValidationError,
   Vault,
   VaultContract,
+  ZERO_ADDRESS,
   allowedActions,
   assertQuaiAddress,
   assertQuaiAddresses,
@@ -4507,6 +4967,7 @@ export {
   computeBytecodeHash,
   computeFullSalt,
   connect,
+  createWorkerThreadsStrategy,
   decodeCall,
   decodeMultiSendPayload,
   decodeRevert,
@@ -4529,6 +4990,7 @@ export {
   knownErrorSelectors,
   loadBalances,
   mainnet,
+  mapPooled,
   mineSalt,
   minimumExpiration,
   networks,
@@ -4537,6 +4999,7 @@ export {
   recoveryCall,
   remediationFor,
   resolveConfig,
+  sanitizeText,
   selfCall,
   shardPrefixOf,
   syncStrategy,