@gvnrdao/dh-sdk 0.0.323 → 0.0.327

package/dist/interfaces/chunks/loan-operations.i.d.ts

@@ -2,6 +2,7 @@
  * Loan Operations Interfaces
  */
 import { LoanStatus } from "../../types/loanStatus";
+import type { AuthorizationProvider } from "../../utils/authorization-provider.utils";
 export type BitcoinAddresses = {
     mainnet: string;
     testnet: string;
@@ -176,6 +177,18 @@ export interface UCDMintRequest {
         stubbedAvailableBtcSats?: string;
         stubbedAuthorizedSpendsHash?: string;
     };
+    /**
+     * Supplies the borrower authorization envelope instead of the connected
+     * signer — the seam a delegated Safe uses so its agent signs instantly
+     * rather than the SDK asking for an owner quorum inside a quantum window.
+     *
+     * Omit it and nothing changes: the SDK signs with the connected signer
+     * exactly as before, which is what every EOA borrower does.
+     *
+     * See `utils/authorization-provider.utils.ts` for why this is a callback and
+     * not a `{ timestamp, signature }` value.
+     */
+    authorizationProvider?: AuthorizationProvider;
 }
 /**
  * UCD Mint Result Interface
@@ -213,6 +226,18 @@ export interface RenewPositionResult {
 export interface RenewPositionRequest {
     positionId: string;
     selectedTerm: number;
+    /**
+     * Supplies the borrower authorization envelope instead of the connected
+     * signer — the seam a delegated Safe uses so its agent signs instantly
+     * rather than the SDK asking for an owner quorum inside a quantum window.
+     *
+     * Omit it and nothing changes: the SDK signs with the connected signer
+     * exactly as before, which is what every EOA borrower does.
+     *
+     * See `utils/authorization-provider.utils.ts` for why this is a callback and
+     * not a `{ timestamp, signature }` value.
+     */
+    authorizationProvider?: AuthorizationProvider;
 }
 /**
  * BTC Withdrawal Result Interface
@@ -282,6 +307,18 @@ export interface PartialPaymentRequest {
     positionId: string;
     paymentAmount: number;
     rpcUrl?: string;
+    /**
+     * Supplies the borrower authorization envelope instead of the connected
+     * signer — the seam a delegated Safe uses so its agent signs instantly
+     * rather than the SDK asking for an owner quorum inside a quantum window.
+     *
+     * Omit it and nothing changes: the SDK signs with the connected signer
+     * exactly as before, which is what every EOA borrower does.
+     *
+     * See `utils/authorization-provider.utils.ts` for why this is a callback and
+     * not a `{ timestamp, signature }` value.
+     */
+    authorizationProvider?: AuthorizationProvider;
 }
 /**
  * Confirm Balance Result Interface

package/dist/modules/diamond-hands-sdk.d.ts

@@ -18,6 +18,7 @@ import { SDKError } from "../utils/error-handler";
 import type { CreateLoanRequest, CreateLoanResult, LoanDataDetail, UCDMintRequest, UCDMintResult, PartialPaymentRequest, PartialPaymentResult, BTCWithdrawalResult, RenewPositionRequest, RenewPositionResult, LiquidationRequest, LiquidationResult, ConfirmBalanceRequest, ConfirmBalanceResult, TermsWithFeesResult } from "../interfaces/chunks/loan-operations.i";
 import type { DiamondHandsSDKConfig } from "../interfaces/chunks/config.i";
 import type { PKPData } from "../interfaces/chunks/pkp-integration.i";
+import { type AuthorizationProvider } from "../utils/authorization-provider.utils";
 import type { DhServerLoginPayload } from "../utils/eip712-login";
 import { type ReconciledWithdrawal } from "../utils/withdrawal-reconciliation.utils";
 import { ContractManager } from "./contract/contract-manager.module";
@@ -540,6 +541,24 @@ export declare class DiamondHandsSDK {
      * address strings, query the subgraph `WithdrawalAddressBook`.
      */
     getApprovedWithdrawalAddresses(user?: string): Promise<Result<import("./withdrawal-address/withdrawal-address.module").WithdrawalAddressEntry[], SDKError>>;
+    /**
+     * Recover the revert reason of an already-mined, already-reverted transaction.
+     *
+     * A status-0 receipt carries no revert data, and ethers does not re-fetch it, so
+     * the reason has to be recovered by replaying the exact calldata as an `eth_call`
+     * pinned to the block that mined it — the only block whose `block.timestamp`
+     * reproduces a timing-dependent revert such as `DeadZoneViolation()`.
+     *
+     * Caveat: the replay runs against end-of-block state rather than the state at the
+     * transaction's own index, so for a state-dependent revert the recovered name is
+     * diagnostic, not proof. Timing reverts (the case this exists for) are unaffected —
+     * they depend only on the block timestamp.
+     *
+     * @returns the decoded error name, its raw selector if unknown, or `null` when the
+     *          replay yields no revert data at all (never throws — a failed diagnosis
+     *          must not mask the underlying failure).
+     */
+    private decodeMinedRevert;
     /**
      * Withdraw Bitcoin from a position
      *
@@ -563,7 +582,15 @@ export declare class DiamondHandsSDK {
      * @param customBitcoinRpcUrl - Optional custom Bitcoin RPC URL (for local testing)
      * @returns Withdrawal result with transaction details
      */
-    withdrawBTC(positionId: string, withdrawalAddress: string, withdrawalAmount: number): Promise<BTCWithdrawalResult>;
+    withdrawBTC(positionId: string, withdrawalAddress: string, withdrawalAmount: number, 
+    /**
+     * An options bag rather than a fifth positional argument: this method is
+     * already three positional strings/numbers deep, and the next caller to
+     * add one would have to guess the order.
+     */
+    options?: {
+        authorizationProvider?: AuthorizationProvider;
+    }): Promise<BTCWithdrawalResult>;
     /**
      * TEMPORARY (multi-UTXO withdrawal fix, Phase A): fetch the vault's confirmed
      * UTXO set from lit-ops-server (`GET /api/lit/vault-utxos`) so the caller can
@@ -721,6 +748,11 @@ export declare class DiamondHandsSDK {
      *      (`MAX_ATTESTATION_AGE = 1 hour`) and replay-protects via
      *      `authorizedAt` binding.
      *
+     * WHO PAYS: in **service mode** lit-ops-server performs BOTH steps and its
+     * relayer funds the transaction — the borrower is never prompted, because the
+     * Bitcoin withdrawal this cleans up after has already settled. In **direct
+     * mode** (CLI / tests / hardhat) the SDK's own signer submits step 2.
+     *
      * `invalidatorTxid` is either:
      *   - the borrower's own authorized broadcast (classified "consumed-as-authorized"
      *     by the LIT validator), once it has ≥6 confirmations on the BTC
@@ -1053,6 +1085,16 @@ export declare class DiamondHandsSDK {
         agentActive: boolean | null;
         /** Agent expiry (unix seconds) — the ONLY time bound on every grant. Null without `user`. */
         agentValidUntil: number | null;
+        /** SCOPE_WITHDRAW granted. Always false where the registry predates v2.1.0. */
+        withdrawEnabled: boolean;
+        /** Does the DEPLOYED registry honour SCOPE_WITHDRAW at all (v2.1.0+)? */
+        withdrawScopeSupported: boolean;
+        /**
+         * Grant's post-withdrawal collateral floor in bps; 0 when WITHDRAW is not granted.
+         * INERT AT ZERO DEBT — a ratio cannot bound a withdrawal once debt is 0. Never present this
+         * as a cap on how much an agent may withdraw.
+         */
+        minWithdrawRatioBps: number;
     }>;
     /** Governance floor-of-floors for agent mints (bps). The UI's minimum for the floor editor. */
     getAgentMintFloorMinBps(): Promise<number>;
@@ -1143,7 +1185,56 @@ export declare class DiamondHandsSDK {
         hash: string;
         blockNumber: number;
     }>;
-    /** Pre-flight the registry's `FloorBelowProtocolMin` guard with a message a user can act on. */
+    /**
+     * Grant the agent the WITHDRAW scope for a position (registry v2.1.0+). Borrower-signed.
+     *
+     * CONTRACT WALLETS ONLY, and this is enforced here rather than on-chain. The withdrawal
+     * validator's only non-borrower arm is `checkSafeAgentWithdrawAuthorization`, which requires a
+     * factory-provenanced `AgentModule` whose `safe()` is the borrower — something an EOA cannot
+     * have. The registry deliberately does NOT check wallet type ("Callable by any borrower (this
+     * function does not itself require a Safe)"), so an EOA can record a grant that no code path
+     * will ever satisfy. Refusing here keeps the supported path from writing a dead record.
+     *
+     * That refusal is ergonomics, NOT enforcement — `enableAutoWithdraw` is `external` and reachable
+     * from any wallet. The real reason delegated withdrawal is closed to EOAs is that they can sign
+     * inside the ~44s window themselves, so delegating buys them nothing and only adds risk.
+     *
+     * @param minWithdrawRatioBps Post-withdrawal collateral-ratio floor for AGENT withdrawals.
+     *        Clamped by the same governance minimum as the mint floor. **Inert at zero debt** — it
+     *        is a ratio, and the post-withdrawal ratio is infinite for any amount once debt is 0.
+     *        The operative bound there is the quorum-gated destination allowlist. Do not surface
+     *        this to users as a cap on how much an agent may withdraw.
+     *        There is no in-place raise: changing it means disable-then-re-enable, deliberately —
+     *        on the one scope that moves custodied BTC, incident response can only disable outright.
+     */
+    enableAutoWithdraw(positionId: string, minWithdrawRatioBps: number, options?: {
+        agentValiditySeconds?: number;
+    }): Promise<{
+        hash: string;
+        blockNumber: number;
+        agentAddress?: string;
+    }>;
+    /**
+     * Revoke the WITHDRAW scope for a position (also zeroes its withdraw floor). Borrower-signed.
+     *
+     * No wallet-type check: revoking is the safe direction, and an EOA that recorded a grant before
+     * this guard existed must be able to clear it.
+     */
+    disableAutoWithdraw(positionId: string): Promise<{
+        hash: string;
+        blockNumber: number;
+    }>;
+    /**
+     * Layer 2 of the withdrawal-delegation gating: refuse to write a grant that could never be
+     * satisfied. See `enableAutoWithdraw` for why this lives here and not in the registry.
+     */
+    private assertBorrowerIsContractWallet;
+    /**
+     * Pre-flight the registry's `FloorBelowProtocolMin` guard with a message a user can act on.
+     *
+     * `agentMintFloorMinBps` is the governance floor-of-floors for BOTH the mint and withdraw
+     * grants — one lever, one invariant — so `scope` only shapes the message.
+     */
     private assertMintFloorAtOrAboveProtocolMin;
     /**
      * Get Bitcoin balance for an address

package/dist/safe-delegation.js

@@ -326,7 +326,7 @@ var SEPOLIA_DEPLOYMENT = {
     CARRY_AGENT_REGISTRY: "0x5595CB538D44E6Cf179D20364fD631D0477e69f7",
     CARRY_AGENT_REGISTRY_IMPL: "0x1b11a3D5e46F3672E643c997f0d569DFf0b64a01",
     AGENT_DELEGATION_REGISTRY: "0x6AE7fc6bE0925126b9D25b1B7Ce5AD5d127ec025",
-    AGENT_DELEGATION_REGISTRY_IMPL: "0x80C47350274513688e348D02506477A96B4afCCb",
+    AGENT_DELEGATION_REGISTRY_IMPL: "0xE931E4b9ceF2A48Ac7D57192da4B523756cFC310",
     DH_AGENT_DELEGATE: "0xa5A14489ae883960df6E1463A41a47aBE9Ecc5AF"
   }
 };
@@ -538,7 +538,7 @@ var MAINNET_DEPLOYMENT = {
 var LOCALHOST_DEPLOYMENT = {
   network: "localhost",
   chainId: 1337,
-  timestamp: "2026-07-23T17:13:42.777Z",
+  timestamp: "2026-07-20T19:45:58.514Z",
   deployer: "",
   contracts: {
     MessageHashBuilder: "0xa82fF9aFd8f496c3d6ac40E2a0F282E47488CFc9",
@@ -558,30 +558,6 @@ var LOCALHOST_DEPLOYMENT = {
     PositionManager: "0x851356ae760d987E095750cCeb3bC6014560891C",
     OperationAuthorizationRegistry: "0xc96304e3c037f81dA488ed9dEa1D8F2a48278a75",
     PKPValidation: "0xD0141E899a65C95a556fE2B27e5982A6DE7fDD7A"
-  },
-  latestEnv: {
-    UCD_TOKEN: "0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512",
-    UCD_CONTROLLER: "0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9",
-    POSITION_MANAGER: "0x851356ae760d987E095750cCeb3bC6014560891C",
-    PKP_VALIDATION_REGISTRY: "0xD0141E899a65C95a556fE2B27e5982A6DE7fDD7A",
-    PKP_VALIDATION_CID_V1: "0x12203af2054b0ab6e18d898ddfc7985593439fb82d22336133387c1169f98d3702ab",
-    PKP_VALIDATION_CID_V3: "0x12203af2054b0ab6e18d898ddfc7985593439fb82d22336133387c1169f98d3702ab",
-    PKP_ETH_ADDRESS: "0x406f6a9855de2f5577b1525f0600461f02859bd0",
-    OPERATION_AUTHORIZATION_REGISTRY: "0xc96304e3c037f81dA488ed9dEa1D8F2a48278a75",
-    UCD_MINT_VALIDATOR_ADDRESS: "0x406f6a9855de2f5577b1525f0600461f02859bd0",
-    UCD_MINT_VALIDATOR_VERSION: 1,
-    BTC_WITHDRAWAL_VALIDATOR_ADDRESS: "0x406f6a9855de2f5577b1525f0600461f02859bd0",
-    BTC_WITHDRAWAL_VALIDATOR_VERSION: 3,
-    UPDATE_BALANCE_VALIDATOR_ADDRESS: "0x406f6a9855de2f5577b1525f0600461f02859bd0",
-    UPDATE_BALANCE_VALIDATOR_VERSION: 1,
-    PROCESS_PAYMENT_VALIDATOR_ADDRESS: "0x406f6a9855de2f5577b1525f0600461f02859bd0",
-    PROCESS_PAYMENT_VALIDATOR_VERSION: 1,
-    EXTEND_POSITION_VALIDATOR_ADDRESS: "0x406f6a9855de2f5577b1525f0600461f02859bd0",
-    EXTEND_POSITION_VALIDATOR_VERSION: 1,
-    POSITION_MANAGER_CORE_MODULE: "0xB7f8BC63BbcaD18155201308C8f3540b07f84F5e",
-    LOAN_OPERATIONS_MANAGER_MODULE: "0x68B1D87F95878fE05B998F19b66F4baba5De1aed",
-    TERM_MANAGER_MODULE: "0x0DCd1Bf9A1b36cE34237eEaFef220932846BCD82",
-    COMMUNITY_MANAGER_MODULE: ""
   }
 };
 var ALL_DEPLOYMENTS = {

package/dist/safe-delegation.mjs

@@ -299,7 +299,7 @@ var SEPOLIA_DEPLOYMENT = {
     CARRY_AGENT_REGISTRY: "0x5595CB538D44E6Cf179D20364fD631D0477e69f7",
     CARRY_AGENT_REGISTRY_IMPL: "0x1b11a3D5e46F3672E643c997f0d569DFf0b64a01",
     AGENT_DELEGATION_REGISTRY: "0x6AE7fc6bE0925126b9D25b1B7Ce5AD5d127ec025",
-    AGENT_DELEGATION_REGISTRY_IMPL: "0x80C47350274513688e348D02506477A96B4afCCb",
+    AGENT_DELEGATION_REGISTRY_IMPL: "0xE931E4b9ceF2A48Ac7D57192da4B523756cFC310",
     DH_AGENT_DELEGATE: "0xa5A14489ae883960df6E1463A41a47aBE9Ecc5AF"
   }
 };
@@ -511,7 +511,7 @@ var MAINNET_DEPLOYMENT = {
 var LOCALHOST_DEPLOYMENT = {
   network: "localhost",
   chainId: 1337,
-  timestamp: "2026-07-23T17:13:42.777Z",
+  timestamp: "2026-07-20T19:45:58.514Z",
   deployer: "",
   contracts: {
     MessageHashBuilder: "0xa82fF9aFd8f496c3d6ac40E2a0F282E47488CFc9",
@@ -531,30 +531,6 @@ var LOCALHOST_DEPLOYMENT = {
     PositionManager: "0x851356ae760d987E095750cCeb3bC6014560891C",
     OperationAuthorizationRegistry: "0xc96304e3c037f81dA488ed9dEa1D8F2a48278a75",
     PKPValidation: "0xD0141E899a65C95a556fE2B27e5982A6DE7fDD7A"
-  },
-  latestEnv: {
-    UCD_TOKEN: "0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512",
-    UCD_CONTROLLER: "0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9",
-    POSITION_MANAGER: "0x851356ae760d987E095750cCeb3bC6014560891C",
-    PKP_VALIDATION_REGISTRY: "0xD0141E899a65C95a556fE2B27e5982A6DE7fDD7A",
-    PKP_VALIDATION_CID_V1: "0x12203af2054b0ab6e18d898ddfc7985593439fb82d22336133387c1169f98d3702ab",
-    PKP_VALIDATION_CID_V3: "0x12203af2054b0ab6e18d898ddfc7985593439fb82d22336133387c1169f98d3702ab",
-    PKP_ETH_ADDRESS: "0x406f6a9855de2f5577b1525f0600461f02859bd0",
-    OPERATION_AUTHORIZATION_REGISTRY: "0xc96304e3c037f81dA488ed9dEa1D8F2a48278a75",
-    UCD_MINT_VALIDATOR_ADDRESS: "0x406f6a9855de2f5577b1525f0600461f02859bd0",
-    UCD_MINT_VALIDATOR_VERSION: 1,
-    BTC_WITHDRAWAL_VALIDATOR_ADDRESS: "0x406f6a9855de2f5577b1525f0600461f02859bd0",
-    BTC_WITHDRAWAL_VALIDATOR_VERSION: 3,
-    UPDATE_BALANCE_VALIDATOR_ADDRESS: "0x406f6a9855de2f5577b1525f0600461f02859bd0",
-    UPDATE_BALANCE_VALIDATOR_VERSION: 1,
-    PROCESS_PAYMENT_VALIDATOR_ADDRESS: "0x406f6a9855de2f5577b1525f0600461f02859bd0",
-    PROCESS_PAYMENT_VALIDATOR_VERSION: 1,
-    EXTEND_POSITION_VALIDATOR_ADDRESS: "0x406f6a9855de2f5577b1525f0600461f02859bd0",
-    EXTEND_POSITION_VALIDATOR_VERSION: 1,
-    POSITION_MANAGER_CORE_MODULE: "0xB7f8BC63BbcaD18155201308C8f3540b07f84F5e",
-    LOAN_OPERATIONS_MANAGER_MODULE: "0x68B1D87F95878fE05B998F19b66F4baba5De1aed",
-    TERM_MANAGER_MODULE: "0x0DCd1Bf9A1b36cE34237eEaFef220932846BCD82",
-    COMMUNITY_MANAGER_MODULE: ""
   }
 };
 var ALL_DEPLOYMENTS = {

package/dist/utils/authorization-provider.utils.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Borrower authorization, supplied by something other than the connected signer.
+ *
+ * WHY THIS EXISTS. Every loan operation carries an envelope the validator
+ * recovers a signer from, and the SDK builds it by calling
+ * `signer.signMessage()`. For an EOA that is one instant prompt. For a k-of-n
+ * Safe it is an EIP-1271 signature — a full owner quorum — and the operation
+ * also needs a second quorum to send the transaction, both inside a quantum
+ * window of 180s (~44s for withdrawals). That cannot be gathered, so a genuine
+ * multi-owner Safe could not complete a loan operation at all.
+ *
+ * The fix is for something that CAN sign instantly to sign the envelope: the
+ * Safe's delegated agent. This is the seam that lets a caller supply it.
+ *
+ * A PROVIDER, NOT A VALUE. The obvious API — hand in `{ timestamp, signature }`
+ * — is wrong, and the reason is the retry loops. Every operation re-signs on
+ * retry precisely because a quantum window can lapse between building the
+ * envelope and landing the transaction. A fixed value would be replayed on
+ * attempt 2 carrying attempt 1's timestamp, so the envelope would already be
+ * dead: a recoverable timing miss turned into a hard failure. A provider is
+ * called again per attempt and returns a fresh signature over a fresh window.
+ *
+ * THE SDK OWNS THE TIMESTAMP. It computes the quantum-aligned value and hands
+ * it to the provider, rather than accepting one back unseen, because the same
+ * value must be embedded in the protocol call that follows. Likewise `amount`
+ * is the SDK's own computed wei — a caller re-deriving it and differing by one
+ * wei produces a signature that recovers to a different address, which surfaces
+ * as an opaque authorization failure with nothing to point at.
+ */
+/** Everything the authorization envelope binds, as the SDK computed it. */
+export interface AuthorizationContext {
+    positionId: string;
+    /** Quantum-aligned, and the value the protocol call will carry. */
+    timestamp: number;
+    /** Wei, as a decimal string. The SDK's own value — never re-derive it. */
+    amount: string;
+    /** Renewals only: the term the envelope binds instead of an amount. */
+    selectedTerm?: number;
+    /** Withdrawals only: the destination the envelope binds. */
+    destinationAddress?: string;
+}
+/**
+ * Returns a signature over the envelope described by `ctx`. The returned
+ * `timestamp` is echoed back rather than assumed so a provider that had to
+ * re-align it can say so — but it SHOULD be the one it was given.
+ */
+export type AuthorizationProvider = (ctx: AuthorizationContext) => Promise<{
+    timestamp: number;
+    signature: string;
+}>;
+/**
+ * Resolve what the `generate*Authorization` helpers should be handed: either a
+ * precomputed `{ timestamp, signature }` from the provider, or the live signer
+ * exactly as before.
+ *
+ * Call this INSIDE a retry loop, never above one — that is the whole point.
+ *
+ * @param nextQuantumTimestamp The SDK's quantum-aligned timestamp for THIS
+ *        attempt. Passed in rather than computed here so the caller keeps a
+ *        single source for the value it will also send on-chain.
+ */
+export declare function resolveAuthorizationInput<TSigner>(provider: AuthorizationProvider | undefined, signer: TSigner, ctx: AuthorizationContext): Promise<TSigner | {
+    timestamp: number;
+    signature: string;
+}>;

package/dist/utils/mint-authorization.utils.d.ts

@@ -113,25 +113,19 @@ export interface BalanceConfirmationAuthorization {
  * - Signer address is recovered from signature by LIT Action
  * - LIT Action validates recovered address === position owner
  */
-export declare function generatePaymentAuthorization(positionId: string, amount: bigint, chainId: number, signer: Signer): Promise<PaymentOwnerAuthorization>;
+export declare function generatePaymentAuthorization(positionId: string, amount: bigint, chainId: number, signerOrPrecomputed: Signer | {
+    timestamp: number;
+    signature: string;
+}): Promise<PaymentOwnerAuthorization>;
 /**
- * Generate extend position authorization signature
- *
- * Creates a signature that matches the format expected by
- * extend-position-validator LIT Action.
- *
- * Message structure:
- * solidityKeccak256(
- *   ["bytes32", "uint256", "uint256", "uint256", "bytes32"],
- *   [positionId, timestamp, chainId, selectedTerm, actionHash]
- * )
+ * NOTE: `generateExtendAuthorization` does NOT live here.
  *
- * Where:
- * - actionHash = keccak256("extend-position")
- * - Signer address is recovered from signature by LIT Action
- * - LIT Action validates recovered address === position owner
+ * It used to — a second copy, without the precomputed-signature union, whose
+ * import in `diamond-hands-sdk.ts` was commented out ("Not used yet"). The live
+ * one is `utils/extend-authorization.utils.ts`, and that is the only one. The
+ * duplicate is removed rather than left dormant because an edit landing in the
+ * wrong copy is a silent no-op: the code looks changed, the behaviour does not.
  */
-export declare function generateExtendAuthorization(positionId: string, selectedTerm: number, chainId: number, signer: Signer): Promise<ExtendOwnerAuthorization>;
 /**
  * Optional Chipotle service fallback for `getPKPPublicKeyFromTokenId`.
  *

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gvnrdao/dh-sdk",
-  "version": "0.0.323",
+  "version": "0.0.327",
   "description": "TypeScript SDK for Diamond Hands Protocol - Bitcoin-backed lending with LIT Protocol PKPs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -87,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.312",
     "@noble/hashes": "^1.5.0",
     "axios": "^1.17.0",
     "bech32": "^2.0.0",