@quaivault/sdk 0.2.0 → 0.2.1

package/dist/index.js

@@ -219,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";
@@ -418,6 +448,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 } : {},
@@ -1092,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;
 }
 
@@ -1774,14 +1807,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;
@@ -2389,36 +2427,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) {
@@ -2448,6 +2456,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);
   }
@@ -2535,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"
@@ -2644,7 +2656,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()}.`,
@@ -2689,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) {
@@ -2705,7 +2717,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;
@@ -2802,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,
@@ -2849,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."
       });
@@ -3611,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",
@@ -3654,7 +3664,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 } : {}
     });
   }
   // =========================================================================
@@ -3700,6 +3711,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);
   }
@@ -3750,7 +3770,7 @@ var Vault = class _Vault {
       owners,
       threshold,
       ...indexedAtBlock !== void 0 ? { indexedAtBlock } : {},
-      capturedAt: nowSeconds(),
+      capturedAt: this.now(),
       source: fromIndexer ? "indexer" : "chain"
     };
   }
@@ -3793,6 +3813,21 @@ var Vault = class _Vault {
   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;
@@ -4016,7 +4051,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,
@@ -4099,7 +4134,7 @@ var Vault = class _Vault {
         approvedAt,
         approvalCount: approvals.length,
         threshold: Number(threshold)
-      }),
+      }, this.now()),
       approvals,
       approvalCount: approvals.length,
       threshold: Number(threshold),
@@ -4117,9 +4152,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
@@ -4130,7 +4165,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(
@@ -4143,7 +4178,13 @@ var Vault = class _Vault {
       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
@@ -4354,11 +4395,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.`
         );
       }
     }
@@ -4697,7 +4738,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(
@@ -4727,7 +4768,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)")
       );
@@ -4772,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.
@@ -4784,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 } : {}
@@ -4819,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. */