@quaivault/sdk 0.2.0 → 0.2.1

package/README.md

@@ -164,9 +164,11 @@ qv.indexerHealth()
 ```ts
 vault.info() / owners() / threshold() / balance() / modules() / delegatecallTargets()
 vault.isOwner(a) / isModuleEnabled(m) / isDelegatecallAllowed(t) / isValidSignature(hash)
-vault.transaction(txHash) / pendingTransactions(page?) / transactionHistory(page?)
-vault.transactionHash(to, value, data, nonce?)
-vault.affordances(txHash, caller?) / describe(txHash, caller?)
+vault.transaction(txHash) / transactions(txHashes) / pendingTransactions(page?)
+vault.transactionHistory(page?) / transactionHash(to, value, data, nonce?)
+vault.hasApproved(txHash, owner)
+vault.affordances(txHash, caller?, at?) / describe(txHash, caller?)
+vault.view() / pinned(view)                       // explicit owners+threshold snapshot
 vault.balances(opts?) / deposits(page?) / tokenTransfers(page?) / signedMessages()
 vault.waitForExecutable(txHash, opts?)
 vault.watch(handler, opts?)                       // Supabase Realtime
@@ -335,6 +337,38 @@ nonce and funds errors are permanent by definition, and anything unrecognised is
 permanent too — so a genuine bug surfaces immediately instead of hiding behind three slow
 attempts. Rate limits, 5xx and raw transport failures are retried.
 
+## Clock skew
+
+The contracts decide with `block.timestamp`. Everything the SDK derives locally — a
+transaction's `ready` vs `timelocked`, what a caller may do next, whether a recovery period
+has elapsed — predicts that, and a machine whose clock is wrong predicts wrongly.
+Containers, CI runners and VMs resumed from a snapshot drift in ways a desktop usually
+does not.
+
+If you have measured the offset, feed it back in:
+
+```ts
+const block = await qv.provider.getBlock('latest');
+const skew = Date.now() / 1000 - Number(block.timestamp);   // positive: local clock ahead
+
+const qv = connect({ network: 'mainnet', now: () => Date.now() / 1000 - skew });
+```
+
+A function rather than a scalar offset on purpose: an offset needs a sign convention, and
+getting it backwards doubles the error instead of cancelling it, silently. Here the
+arithmetic sits in your code, where it reads as what it means.
+
+Detection is deliberately yours. Deriving the offset costs an RPC call the SDK should not
+make on your behalf, and caching one has no clear invalidation.
+
+**This never touches elapsed-time measurement** — retry backoff, timeouts, poll intervals
+and cache TTLs stay on the raw local clock. A clock being 12 seconds fast does not make 30
+seconds of backoff into 18.
+
+Nothing here can change an on-chain outcome; the chain is the authority and a wrong local
+time fails safe into a revert or a refusal. What it changes is what the SDK *tells* you,
+which is most of what the SDK is for.
+
 ## Development
 
 ```bash

package/dist/index.cjs

@@ -3647,6 +3647,36 @@ function normalizeTxHash(value, label = "transaction hash") {
 // src/config/resolve.ts
 var import_quais2 = require("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";
@@ -3846,6 +3876,9 @@ function resolveConfig(options = {}) {
     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 } : {},
@@ -4520,7 +4553,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;
 }
 
@@ -5202,14 +5235,19 @@ function toNumber(value, fallback = 0) {
 }
 
 // src/indexer/client.ts
-var SDK_VERSION = true ? "0.2.0" : "dev";
+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;
@@ -5817,36 +5855,6 @@ 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 RecoveryModule = class {
   constructor(ctx) {
@@ -5876,6 +5884,10 @@ var RecoveryModule = class {
    * 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);
   }
@@ -5963,7 +5975,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: (0, import_quais9.getAddress)(row.initiator_address),
       source: "indexer"
@@ -6072,7 +6084,7 @@ 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()}.`,
@@ -6117,7 +6129,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) {
@@ -6133,7 +6145,7 @@ var RecoveryModule = class {
       this.isEnabled(),
       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;
@@ -6230,13 +6242,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,
@@ -6277,7 +6286,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."
       });
@@ -7039,8 +7048,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",
@@ -7082,7 +7092,8 @@ var Vault = class _Vault {
       connection: ctx.connection,
       queries: ctx.queries,
       vaultAddress: this.address,
-      moduleAddress: ctx.contracts.socialRecovery
+      moduleAddress: ctx.contracts.socialRecovery,
+      ...ctx.now ? { now: ctx.now } : {}
     });
   }
   // =========================================================================
@@ -7128,6 +7139,15 @@ var Vault = class _Vault {
     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);
   }
@@ -7178,7 +7198,7 @@ var Vault = class _Vault {
       owners,
       threshold,
       ...indexedAtBlock !== void 0 ? { indexedAtBlock } : {},
-      capturedAt: nowSeconds(),
+      capturedAt: this.now(),
       source: fromIndexer ? "indexer" : "chain"
     };
   }
@@ -7221,6 +7241,21 @@ var Vault = class _Vault {
   async isOwner(address2) {
     return this.contract().isOwner((0, import_quais14.getAddress)(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), (0, import_quais14.getAddress)(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;
@@ -7444,7 +7479,7 @@ var Vault = class _Vault {
       approvalCount,
       threshold,
       failed: row.status === "failed"
-    });
+    }, this.now());
     const failedReturnData = row.failed_return_data ?? void 0;
     return {
       hash: row.tx_hash,
@@ -7527,7 +7562,7 @@ var Vault = class _Vault {
         approvedAt,
         approvalCount: approvals.length,
         threshold: Number(threshold)
-      }),
+      }, this.now()),
       approvals,
       approvalCount: approvals.length,
       threshold: Number(threshold),
@@ -7545,9 +7580,9 @@ var Vault = class _Vault {
    * 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);
+    return this.resolveAffordances(hash, this.transaction(hash), caller, at);
   }
   /**
    * Shared body of {@link affordances}, taking the transaction either as a value or as
@@ -7558,7 +7593,7 @@ var Vault = class _Vault {
    * passes the unawaited promise so the transaction read still overlaps the two
    * ownership probes rather than serialising behind them.
    */
-  async resolveAffordances(hash, transaction, caller) {
+  async resolveAffordances(hash, transaction, caller, at) {
     const who = caller ?? await this.ctx.connection.addressOrNull();
     if (!who) {
       throw new ValidationError(
@@ -7571,7 +7606,13 @@ var Vault = class _Vault {
       vault2.isOwner((0, import_quais14.getAddress)(who)),
       vault2.hasApproved(hash, (0, import_quais14.getAddress)(who))
     ]);
-    return computeAffordances({ tx, caller: (0, import_quais14.getAddress)(who), isOwner, hasApproved });
+    return computeAffordances({
+      tx,
+      caller: (0, import_quais14.getAddress)(who),
+      isOwner,
+      hasApproved,
+      at: at ?? this.now()
+    });
   }
   // =========================================================================
   // Proposals
@@ -7782,11 +7823,11 @@ var Vault = class _Vault {
     }
     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.`
         );
       }
     }
@@ -8125,7 +8166,7 @@ var Vault = class _Vault {
           { 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(
@@ -8155,7 +8196,7 @@ var Vault = class _Vault {
       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)")
       );
@@ -8200,6 +8241,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.
@@ -8212,6 +8258,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 } : {}
@@ -8247,7 +8294,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. */