@gvnrdao/dh-sdk 0.0.320 → 0.0.324

package/dist/utils/quantum-revert.utils.d.ts

@@ -39,3 +39,24 @@ export interface DecodedRevert {
 export declare function decodeQuantumRevert(e: any): DecodedRevert;
 /** True iff the error decodes to `DeadZoneViolation()` from any provider nesting. */
 export declare function isDeadZoneViolation(e: any): boolean;
+/**
+ * Whether a failed quantum-signed operation can be safely retried with a fresh
+ * signature. Shared by the payment and BTC-withdrawal retry loops so the two paths
+ * cannot drift apart again (they had: withdrawal recognised only
+ * `QuantumOutsideWindow`, and never decoded a mined revert at all, so the mainnet
+ * `DeadZoneViolation` of 2026-08-07 surfaced as a hard failure on a flow that
+ * payments recover from automatically).
+ *
+ * **Retryable** — the operation provably did not happen:
+ * - a pre-send simulation quantum error (nothing was ever broadcast), or
+ * - a mined revert (`status === 0`): atomic, so no funds moved, no authorization
+ *   was recorded, and the quantum replay lane is untouched. Re-signing is safe.
+ *
+ * **NOT retryable** — the outcome is unknown, so a resubmit risks double-spending:
+ * - a confirmation timeout (the tx may still be pending), or
+ * - a confirmation failure with no receipt (transport died mid-wait).
+ *
+ * Callers MUST therefore only produce a "Transaction reverted" message after
+ * observing a receipt with `status === 0`.
+ */
+export declare function isRetryableQuantumFailure(message: string | null | undefined): boolean;

package/dist/utils/quantum-submission.utils.d.ts

@@ -37,13 +37,21 @@ export declare class QuantumRevertError extends Error {
     constructor(errorName: string | null, selector: string | null, data: string | null, cause: unknown);
 }
 export interface SafeQuantumSubmissionOpts {
-    /** Provider used for the `eth_call` simulation (only `.call` is needed). */
+    /**
+     * Provider used for the `eth_call` simulation and — when it exposes `getBlock`
+     * (every ethers provider does) — for the dead-zone gate's chain clock. Without
+     * `getBlock` the gate silently degrades to the client's local clock, which on the
+     * browser path is exactly the skew we are trying to design out.
+     */
     provider: {
         call(tx: {
             to: string;
             from: string;
             data: string;
         }): Promise<string>;
+        getBlock?(blockTag: string): Promise<{
+            timestamp: number;
+        } | null | undefined>;
     };
     /** Target contract address. */
     to: string;
@@ -59,6 +67,12 @@ export interface SafeQuantumSubmissionOpts {
     now?: () => number;
     /** Sleep seam, forwarded to the gate. */
     sleep?: (ms: number) => Promise<void>;
+    /**
+     * Chain-clock seam (latest mined block timestamp, whole seconds). Defaults to
+     * `provider.getBlock("latest")` when the provider exposes it. Pass explicitly to
+     * override in tests, or `null`-resolving to force the local-clock fallback.
+     */
+    chainNow?: () => Promise<number | null>;
     /** Debug sink; called with human-readable progress lines. */
     onDebug?: (msg: string) => void;
     /**
@@ -79,7 +93,9 @@ export interface SafeQuantumSubmissionOpts {
  * 1. **Gate** (`awaitSafeSubmissionWindow`): a NEXT-quantum signature mined in
  *    the last DEAD_ZONE_SECONDS of the current quantum reverts
  *    `DeadZoneViolation()` on-chain, so defer the send across the boundary
- *    when inclusion could land there.
+ *    when inclusion could land there. Anchored on `provider.getBlock("latest")`
+ *    — the same clock `block.timestamp` comes from — so a skewed client clock
+ *    cannot wave a doomed send through.
  * 2. **Simulate** (`eth_call`) and route the outcome:
  *    - success → safe to broadcast.
  *    - `DeadZoneViolation()` → `eth_call` runs against the LATEST block's
@@ -87,7 +103,11 @@ export interface SafeQuantumSubmissionOpts {
  *      the signature is already the CURRENT quantum in real time it can never
  *      be dead-zoned on-chain — stale-block artifact, proceed. Otherwise the
  *      signature is still NEXT near the boundary: re-gate across it and
- *      re-simulate (bounded by `maxResimulations`).
+ *      re-simulate (bounded by `maxResimulations`). This artifact test must use
+ *      the LOCAL clock, not the chain head: the chain head IS the stale value
+ *      the simulation reverted against, so anchoring it there would classify
+ *      every artifact as real. A fast client clock wrongly reaching "artifact"
+ *      is caught by the chain-anchored final re-gate in step 3.
  *    - any other DECODABLE revert → throw `QuantumRevertError` (fail fast: no
  *      broadcast, no gas burned on a doomed tx).
  *    - UNDECODABLE failure (no revert data: RPC timeout, rate limit, provider

package/dist/utils/quantum-timing.d.ts

@@ -28,13 +28,38 @@
  */
 export declare const QUANTUM_WINDOW_SECONDS = 60;
 export declare const DEAD_ZONE_SECONDS = 8;
+/** Ethereum slot cadence. Block timestamps are multiples of 12s from genesis. */
+export declare const SLOT_SECONDS = 12;
+/**
+ * Slots of inclusion latency we insure against. A broadcast is NOT guaranteed to
+ * land in the very next slot: builders skip low-tip transactions and slots are
+ * missed, so 2–3 slot inclusion is routine on mainnet.
+ *
+ * Sized from a real mainnet failure (tx 0x5933d64d…, 2026-08-07): a NEXT-quantum
+ * withdrawal was broadcast with ~25s to the boundary — outside the old 16s budget,
+ * so the gate let it through — then sat out one near-empty block (0.0007 gwei tip)
+ * and was mined 24s later at second 59, one second inside the trailing dead zone.
+ * `DeadZoneViolation()`. 3 slots (36s) covers that skip with a slot to spare.
+ */
+export declare const INCLUSION_SLOT_TOLERANCE = 3;
 /**
  * Seconds of mainnet inclusion latency we insure against BEFORE the quantum
- * boundary. ~1.3 of Ethereum's 12s slots. A NEXT/PAST-quantum send within
+ * boundary. A NEXT/PAST-quantum send within
  * `DEAD_ZONE_SECONDS + INCLUSION_LATENCY_BUDGET` of the boundary is deferred so it
  * cannot be mined in the trailing dead zone `[boundary - 8, boundary)`.
+ *
+ * Used by the LOCAL-CLOCK fallback path only. When a chain clock is available the
+ * gate reasons in whole slots instead (see `awaitSafeSubmissionWindow`), which is
+ * both tighter and immune to client clock skew.
  */
-export declare const INCLUSION_LATENCY_BUDGET = 16;
+export declare const INCLUSION_LATENCY_BUDGET: number;
+/**
+ * Cap on chain-clock polls while deferring across a boundary. Each poll sleeps at
+ * most one slot, so this bounds a deferral at ~`MAX_GATE_POLLS` slots — comfortably
+ * more than the ~44s worst-case wait, while refusing to spin forever on a stuck or
+ * lying RPC.
+ */
+export declare const MAX_GATE_POLLS = 12;
 /**
  * Seconds of client-clock-vs-chain skew guard we add AFTER the boundary when
  * deferring. A CURRENT-quantum signature is never dead-zoned, so this only needs to
@@ -108,6 +133,16 @@ export interface SafeSubmissionOptions {
     now?: () => number;
     /** Sleeps for `ms` milliseconds. Defaults to `setTimeout`. */
     sleep?: (ms: number) => Promise<void>;
+    /**
+     * Latest MINED block timestamp, in whole seconds — the only clock the on-chain
+     * dead-zone rule is expressed in. Supply this wherever a provider is available:
+     * the local-clock path below cannot see client clock skew, and the primary
+     * consumer of this gate is a browser wallet whose clock is not trustworthy.
+     *
+     * Resolve to `null` (or throw) to fall back to the local clock — a flaky RPC
+     * must never block a valid money-path operation.
+     */
+    chainNow?: () => Promise<number | null>;
 }
 export interface SafeSubmissionResult {
     /** Whether the send was deferred across the quantum boundary. */
@@ -136,6 +171,18 @@ export interface SafeSubmissionResult {
  * acceptance window (`QuantumOutsideWindow`). They must be handled by re-signing
  * upstream. In practice the SDK only ever signs CURRENT/NEXT.
  *
+ * Two implementations, same predicate:
+ *
+ * - **Chain-anchored** (`opts.chainNow` supplied — always prefer this): reasons in
+ *   whole slots off the latest mined block timestamp `H`, the same clock the
+ *   contract's `block.timestamp` comes from. A broadcast issued now can only be
+ *   mined at `H + 12k`, so it is safe iff EVERY plausible `k` lands clear of the
+ *   dead zone. No client clock is consulted at all — only sleep *durations*, which
+ *   are immune to an offset clock.
+ * - **Local-clock fallback** (no `chainNow`, or the chain read failed): the original
+ *   `Date.now()` math with the widened {@link INCLUSION_LATENCY_BUDGET}. Retained so
+ *   a flaky RPC degrades rather than blocks, but it cannot see client clock skew.
+ *
  * @param quantumTimestamp The quantum timestamp embedded in the LIT-signed payload.
  * @returns whether it waited, and for how long.
  */

package/dist/utils/safe-agent-delegation.utils.d.ts

@@ -0,0 +1,154 @@
+/**
+ * "Is this Safe delegated, and to which agent?" — the single implementation.
+ *
+ * Every consumer that needs to know whether a multi-sig Safe can act through an
+ * AgentModule asks this: the frontend gate, the CLI, MCP. It was previously
+ * reimplemented per-consumer, and this session shows what that costs — the same
+ * invariant lived in two places twice, and both times only one copy was fixed
+ * when it turned out to be wrong.
+ *
+ * ── WHAT MAKES A DELEGATION REAL ───────────────────────────────────────────
+ * A module counts only when ALL of these hold:
+ *   - it is enabled on the Safe (`getModulesPaginated`)
+ *   - `safe()` is that Safe and `positionManager()` is this chain's
+ *   - `AgentModuleFactory.isFromFactory(module)` claims it
+ *
+ * That last one is not decoration. The agent-module-executor Lit Action refuses
+ * at its second guard to sign through any module the factory disowns, so an
+ * unprovenanced module is one nothing can ever use. Measured on the Sepolia test
+ * Safe (2026-08-05): it carried a pre-factory module from an old e2e harness,
+ * correctly bound and pointing at an EOA agent nothing could sign with — and
+ * without the provenance check it read as a working delegation.
+ *
+ * ── WHY THE ANSWER IS TRI-STATE ────────────────────────────────────────────
+ * `unknown` is not a rounding error, it is the whole safety property. Callers
+ * act on "not-delegated" by BLOCKING loan creation, so a check that merely
+ * failed to run must never produce it. The distinctions below are load-bearing
+ * and were each learned from a live failure:
+ *
+ *   - `safe()` unreadable        → unknown. Every module here answers it, so a
+ *                                  failure means we could not read, not that the
+ *                                  module is wrong.
+ *   - `positionManager()` absent → EVIDENCE. It is the discriminator (absent on
+ *                                  VaultProvisionerModule), so a revert is a real
+ *                                  answer: not an AgentModule.
+ *   - provenance unreadable      → unknown.
+ *   - no factory on this chain   → unknown, never "not-delegated". Mainnet has
+ *                                  no AgentModuleFactory, and reporting that as
+ *                                  not-delegated blocked vault creation behind a
+ *                                  ceremony that cannot run there at all.
+ *
+ * ── NOT A SUBSTITUTE FOR THE LIT ACTION'S OWN CHECKS ───────────────────────
+ * The executor re-derives provenance and the registry binding itself. It must:
+ * it is the enforcement point and cannot trust anything a caller computed.
+ * Sharing this code with it would weaken it, so it stays independent.
+ */
+import { type Provider } from "ethers";
+export type SafeDelegationStatus = "delegated" | "not-delegated" | "unknown";
+export interface SafeAgentDelegation {
+    /** Lowercased Safe the answer describes. */
+    safeAddress: string;
+    /** Chain the answer describes — a module on one chain says nothing about another. */
+    chainId: number;
+    status: SafeDelegationStatus;
+    /** The AgentModule, or null when there isn't one (or we could not tell). */
+    moduleAddress: string | null;
+    /**
+     * The agent EOA that SIGNS AND PAYS for delegated operations — read from the
+     * module, not the registry. They should agree, but the module's `agent()` is
+     * who `onlyAgent` actually admits, so it is the truth about who needs gas.
+     */
+    agentAddress: string | null;
+    /** Registry expiry for the Safe's agent record, when readable. */
+    validUntil: number | null;
+    /** True when the Safe's module list exceeded one page — the answer may be partial. */
+    truncated: boolean;
+}
+/**
+ * Resolve the Safe's agent delegation from chain state.
+ *
+ * `provider` is the CALLER'S, deliberately: it must read the chain the caller is
+ * actually on. Resolving it internally would let an SDK configured for one chain
+ * answer about another, which is the exact confusion that made a live Sepolia
+ * delegation look absent while the wallet had silently defaulted to mainnet.
+ *
+ * Never throws — every failure resolves to `unknown`.
+ */
+export declare function getSafeAgentDelegation(params: {
+    safeAddress: string;
+    chainId: number;
+    provider: Provider;
+}): Promise<SafeAgentDelegation>;
+/** One entry in a Safe transaction batch. */
+export interface SafeDelegationCall {
+    to: string;
+    data: string;
+    value: string;
+}
+export interface SafeAgentDelegationDisablePlan {
+    /**
+     * The calls, in execution order. They must land ATOMICALLY — see below for
+     * why a half-applied revocation is worse than none.
+     */
+    calls: SafeDelegationCall[];
+    /** The module being removed. */
+    moduleAddress: string;
+    /** The agent being revoked, when the module could name it. */
+    agentAddress: string | null;
+    /** The predecessor `disableModule` needs — SENTINEL when the module heads the list. */
+    prevModule: string;
+}
+/**
+ * Build the calls that undo a Safe's agent delegation.
+ *
+ * THE COUNTERPART TO {@link getSafeAgentDelegation}, and here rather than in any
+ * one consumer for the reason that reader is here: it needs the same module
+ * enumeration, and a second copy of that walk is how the two drift. The
+ * frontend, the CLI and MCP all revoke the same way or none of them can be
+ * trusted to.
+ *
+ * ── WHY TWO CALLS ──────────────────────────────────────────────────────────
+ * Neither alone is a full revocation:
+ *
+ *  - `revokeAgent` flips the registry record to Revoked, which is what the Lit
+ *    Action's `can*` gates read. After it, no mint/repay/renew/withdraw can be
+ *    authorized for this agent.
+ *  - `disableModule` removes the on-chain execution path, and it is the one
+ *    that matters for the calls needing NO validator attestation: with the
+ *    module still enabled, a live agent key can forward `approve` and
+ *    `setPositionDelegate` through the Safe whatever the registry says
+ *    (`AgentModule.execute` checks only `msg.sender == agent` and its own
+ *    selector whitelist).
+ *
+ * Submit them as ONE batch. Revoking the record while leaving the module
+ * enabled reads as "not delegated" everywhere in the UI while those unattested
+ * paths stay open — the worst of both states.
+ *
+ * ── WHAT IT DOES NOT UNDO ──────────────────────────────────────────────────
+ * A `setPositionDelegate` the agent already installed on PositionDelegateRegistry
+ * SURVIVES both calls (vigil C-43). Clearing that is per-position and is not
+ * part of this plan.
+ *
+ * THROWS, unlike `getSafeAgentDelegation` — the asymmetry is deliberate. That
+ * one answers a question and "unknown" is a usable answer. This one produces a
+ * transaction the Safe's owners must gather to sign, so a guess costs them an
+ * approval round on something that must revert. Every failure is loud:
+ *
+ *  - the chain has no AgentDelegationRegistry;
+ *  - the Safe's module list cannot be read (never guess a predecessor: a wrong
+ *    `prevModule` is Safe's GS103, AFTER the owners have signed);
+ *  - the module is not enabled on the Safe (the caller is acting on a stale
+ *    verdict).
+ *
+ * @param params.moduleAddress Optional. Supply the module from a verdict already
+ *        on screen so the transaction describes what the user was looking at;
+ *        omit it and the delegation is resolved here.
+ */
+export declare function buildSafeAgentDelegationDisableCalls(params: {
+    safeAddress: string;
+    chainId: number;
+    provider: Provider;
+    moduleAddress?: string;
+    /** bytes32 recorded against the revocation. Defaults to `bytes32("user-disabled")`. */
+    reason?: string;
+}): Promise<SafeAgentDelegationDisablePlan>;

package/dist/utils/withdrawal-reconciliation.utils.d.ts

@@ -3,23 +3,36 @@
  * (`BTCSpendAuthorizer.getAuthorizedSpends`) against BITCOIN truth before any
  * UI offers "Execute" or any server invokes the TEE signer.
  *
- * Why this exists (incident 2026-07-22, position 0x992d5c…): the contract can
- * never know whether a Phase-2 BTC broadcast happened, and a pre-P6/#8
- * authorization could record a `(vout, satoshis)` pair that never matched the
- * chain (declared 96,049 vs on-chain 33,000). Executing such an entry can only
- * die at the signer's parent-fetch guard; and an entry whose outpoint was
- * already spent paying the target is DONE and must auto-clear — while an
- * entry whose funding tx merely confirmed must NOT be cleared as "complete".
+ * `satoshis` semantics — AGGREGATE, by design: the authorized `satoshis` is
+ * the TOTAL input value the consolidation will consume across the vault's
+ * confirmed UTXO set (btc-withdrawal.ts signs `vaultSatoshis = newCollateral +
+ * totalDeduction`), while `(txid, vout)` pins ONE representative outpoint.
+ * `BTCSpendAuthorizer.sol` enforces `targetAmount < satoshis`
+ * (TargetMustLeaveFeeRoom) — a withdrawal near the vault's full balance could
+ * never be authorized against a single small outpoint's value, so the
+ * aggregate is structurally required. NEVER compare `satoshis` to the
+ * representative outpoint's own value: for any vault holding more than one
+ * UTXO they legitimately differ (incident 2026-08-07, position 0x992d5c…, a
+ * 4-UTXO vault whose valid authorization was misclassified as corrupt).
+ *
+ * What IS invariant, and what this module verifies:
+ * - the funding tx exists and is confirmed (else UNFUNDED);
+ * - the representative `vout` exists on that tx (else CORRUPT);
+ * - the output at `vout` pays the VAULT address, when the caller supplies it
+ *   (else CORRUPT — this is the real 2026-07-20 (vout, satoshis)-decoupling
+ *   bug class: a vout pointing at an output the vault does not own);
+ * - `targetAmount < satoshis`, mirroring the contract invariant (else CORRUPT);
+ * - the outpoint's spend state (EXECUTED / SPENT_MISMATCH / EXECUTABLE).
  *
  * Statuses:
- * - EXECUTABLE      — outpoint confirmed, unspent, values coherent → offer Execute.
+ * - EXECUTABLE      — outpoint confirmed, unspent, record coherent → offer Execute.
  * - EXECUTED        — outpoint spent by a tx that pays the authorized target →
  *                     auto-clear, show `spendingTxid` as the completion proof.
  * - SPENT_MISMATCH  — outpoint spent but the spending tx pays the target
  *                     nothing → unexecutable; recoverStaleSpend clears it.
- * - CORRUPT         — authorization contradicts the chain (declared value ≠
- *                     real output value, targetAmount > real value, or vout
- *                     out of range) → operator recovery (admin clearing path);
+ * - CORRUPT         — authorization contradicts the chain (vout out of range,
+ *                     output not owned by the vault, or targetAmount ≥
+ *                     satoshis) → operator recovery (admin clearing path);
  *                     never Execute.
  * - UNFUNDED        — funding tx unknown/unconfirmed → wait; no Execute yet.
  *
@@ -43,7 +56,11 @@ export interface ReconciledWithdrawal<T extends AuthorizedSpendLike = Authorized
     status: PendingWithdrawalStatus;
     /** Human-readable, single-sentence explanation of the classification. */
     reason: string;
-    /** Real value of the referenced outpoint, when the funding tx is known. */
+    /**
+     * Real value of the referenced outpoint, when the funding tx is known.
+     * Diagnostic only — for a multi-UTXO vault it is legitimately smaller than
+     * the aggregate `satoshis`.
+     */
     onChainOutputValue?: number;
     /** The verified spending tx, for EXECUTED / SPENT_MISMATCH. */
     spendingTxid?: string;
@@ -61,5 +78,14 @@ export type HttpGetJson = (url: string) => Promise<{
     body: unknown;
 }>;
 export declare const defaultHttpGetJson: HttpGetJson;
-/** Classify one authorized spend against the esplora at `esploraBaseUrl`. */
-export declare function reconcileAuthorizedSpend<T extends AuthorizedSpendLike>(spend: T, esploraBaseUrl: string, httpGetJson?: HttpGetJson): Promise<ReconciledWithdrawal<T>>;
+/**
+ * Classify one authorized spend against the esplora at `esploraBaseUrl`.
+ *
+ * `opts.vaultAddress` enables the vault-ownership check (the strongest guard
+ * against the (vout, satoshis)-decoupling bug class). When absent the check is
+ * SKIPPED, not assumed — production callers (lit-ops-server, frontend) must
+ * supply it.
+ */
+export declare function reconcileAuthorizedSpend<T extends AuthorizedSpendLike>(spend: T, esploraBaseUrl: string, httpGetJson?: HttpGetJson, opts?: {
+    vaultAddress?: string;
+}): Promise<ReconciledWithdrawal<T>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gvnrdao/dh-sdk",
-  "version": "0.0.320",
+  "version": "0.0.324",
   "description": "TypeScript SDK for Diamond Hands Protocol - Bitcoin-backed lending with LIT Protocol PKPs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -29,6 +29,11 @@
       "types": "./dist/deployments.d.ts",
       "import": "./dist/deployments.mjs",
       "require": "./dist/deployments.js"
+    },
+    "./safe-delegation": {
+      "types": "./dist/safe-delegation.d.ts",
+      "import": "./dist/safe-delegation.mjs",
+      "require": "./dist/safe-delegation.js"
     }
   },
   "files": [
@@ -82,8 +87,8 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@gvnrdao/dh-lit-actions": "^0.0.319",
-    "@gvnrdao/dh-lit-ops": "^0.0.310",
+    "@gvnrdao/dh-lit-actions": "^0.0.320",
+    "@gvnrdao/dh-lit-ops": "^0.0.311",
     "@noble/hashes": "^1.5.0",
     "axios": "^1.17.0",
     "bech32": "^2.0.0",