@gvnrdao/dh-sdk 0.0.323 → 0.0.324

package/dist/index.mjs

@@ -1385,30 +1385,30 @@ var require_pkg_src = __commonJS({
         }
       },
       btcTransactionSigner: {
-        cid: "QmPncBUbxN9giWntJcvBMFW9GDAgA3DwgAkUAHxSsY67ic",
+        cid: "QmakWzTce8NH1Jkgv1xwg83Bg9WmF2UG1Mq76pDYDSwwUp",
         authorizedCidHex: cidToHex(
-          "QmPncBUbxN9giWntJcvBMFW9GDAgA3DwgAkUAHxSsY67ic"
+          "QmakWzTce8NH1Jkgv1xwg83Bg9WmF2UG1Mq76pDYDSwwUp"
         ),
         name: "Btc Transaction Signer",
         description: "Production Btc Transaction Signer",
         version: "1.1.1",
         deployed: true,
-        deployedAt: 1785226367707,
-        size: 66624,
-        hash: "9e0d9909519d5133bab03a9491566870b08d8b42c80e2d768bd24f02946cc781"
+        deployedAt: 1786113907707,
+        size: 67999,
+        hash: "83f3644c68819215e05ba8db3225571354a009458fc1437f606df6cb9142d3f9"
       },
       ucdMintValidator: {
-        cid: "QmPRLCfseSWCAS4PpvQWt9aEd6rXqWYG4JyGTn26KYk6xc",
+        cid: "Qmd8jgKRceLvf5aoTtwdXG2JqMoBK5cRJwrvEtQkgvbFbx",
         authorizedCidHex: cidToHex(
-          "QmPRLCfseSWCAS4PpvQWt9aEd6rXqWYG4JyGTn26KYk6xc"
+          "Qmd8jgKRceLvf5aoTtwdXG2JqMoBK5cRJwrvEtQkgvbFbx"
         ),
         name: "Ucd Mint Validator",
         description: "Production Ucd Mint Validator",
         version: "1.2.1",
         deployed: true,
-        deployedAt: 1785226381631,
-        size: 81658,
-        hash: "d8ea21622885c3d26fdb64e2ba9d2f9460753a5cd7934b2928858899537443eb",
+        deployedAt: 1786113908489,
+        size: 82739,
+        hash: "2bdd9aebdaad58a43a4731d5b7284f2531b7a9caaf8caf5719d891c4ed33cb2e",
         validatorWalletAddress: "0x82DB9F515957aA380B596C6eA2Bd30CEF181f236",
         pkp: {
           publicKey: "0x041ab17cd91fc5c0b761eea6092d032807561b621b82c488826776e04a9158d61ba64d809a4729f0501289d980732cb06d8dfd06999dd9c8efd2f495dad78b31bb",
@@ -1416,17 +1416,17 @@ var require_pkg_src = __commonJS({
         }
       },
       processPaymentValidator: {
-        cid: "QmNUzmHQHsaKThGkfZiD3xZrN64qZfn4P6J4MqWgvkeEsX",
+        cid: "QmNXVdysXDhCaQ1uNE2Vgjbuzy6yUEnnVgHzmDfNKXMU6z",
         authorizedCidHex: cidToHex(
-          "QmNUzmHQHsaKThGkfZiD3xZrN64qZfn4P6J4MqWgvkeEsX"
+          "QmNXVdysXDhCaQ1uNE2Vgjbuzy6yUEnnVgHzmDfNKXMU6z"
         ),
         name: "Process Payment Validator",
         description: "Production Process Payment Validator",
         version: "1.2.1",
         deployed: true,
-        deployedAt: 1785226385509,
-        size: 77655,
-        hash: "3c2af3c3e62e8e606d35f81fd7e6f4943f8516a9bef74f4150c8c1767cbd316f",
+        deployedAt: 1786113909138,
+        size: 78736,
+        hash: "17191ecc9c009e0fa5ab52c876330beb2a9a75d30cccb92e7c0c04f169df088b",
         validatorWalletAddress: "0x82DB9F515957aA380B596C6eA2Bd30CEF181f236",
         pkp: {
           publicKey: "0x04cfccb9b6c7addc79469c0e9fafebef4c70801302c62cdb26b610723a9b8527d23f98a40158c7340d83fd0e62d02b5ec74c12f7a86d98e8c6973b4811110f19ad",
@@ -1434,17 +1434,17 @@ var require_pkg_src = __commonJS({
         }
       },
       extendPositionValidator: {
-        cid: "QmY2t41w1maaoDmdRPx6wTfciHPQAydSpLSKwKVFSS2DPM",
+        cid: "QmYwBsyrhGfHWyRKx549G4tKHxsBLAuRUHcecigeUCkFav",
         authorizedCidHex: cidToHex(
-          "QmY2t41w1maaoDmdRPx6wTfciHPQAydSpLSKwKVFSS2DPM"
+          "QmYwBsyrhGfHWyRKx549G4tKHxsBLAuRUHcecigeUCkFav"
         ),
         name: "Extend Position Validator",
         description: "Production Extend Position Validator",
         version: "1.2.1",
         deployed: true,
-        deployedAt: 1785226398291,
-        size: 75434,
-        hash: "ba55532fbeaf6e65d180b869fd69ee06393d574daa0ace524a9e831d846539a5",
+        deployedAt: 1786113909872,
+        size: 76515,
+        hash: "1d4e085335af80f194a663a577876902c83015177e95906a0b461fa93bd5da08",
         validatorWalletAddress: "0x82DB9F515957aA380B596C6eA2Bd30CEF181f236",
         pkp: {
           publicKey: "0x04e52338f6a0c3362800f1a94c4c8f08be5030dde0fa217388c53d1c1a4790f4443c9f2886b2d2d8f4b75a9a156e9b028011b1a1cf7648da0e556aa980ec692836",
@@ -1452,9 +1452,9 @@ var require_pkg_src = __commonJS({
         }
       },
       btcWithdrawal: {
-        cid: "QmcBg8vPXsCmiKDk28bJVTqDpTrwCzSYAGu5V6ABVVPuK5",
+        cid: "QmZuR3qSBajutXfRd91ffpyFrRMgmaMh7fDEHRiQQF8Ljp",
         authorizedCidHex: cidToHex(
-          "QmcBg8vPXsCmiKDk28bJVTqDpTrwCzSYAGu5V6ABVVPuK5"
+          "QmZuR3qSBajutXfRd91ffpyFrRMgmaMh7fDEHRiQQF8Ljp"
         ),
         name: "Btc Withdrawal",
         description: "Production Btc Withdrawal",
@@ -1464,9 +1464,9 @@ var require_pkg_src = __commonJS({
         // than the one it replaced, which a rotation ceremony would treat as a rollback.
         version: "1.2.4",
         deployed: true,
-        deployedAt: 1785226412397,
-        size: 92754,
-        hash: "d3a8ec62e0b1e6d0566a154a884bf7ee4e25ef6dc2dd84fde98211d25c1dede5",
+        deployedAt: 1786113910531,
+        size: 95313,
+        hash: "ce12f11e3b5469953bc919586e4f3b8b5d594224b58b799dd9a3b60e3749559c",
         validatorWalletAddress: "0x82DB9F515957aA380B596C6eA2Bd30CEF181f236",
         pkp: {
           publicKey: "0x043616787c5432415c24378c4ef48de2bcd6bb7b575b837e3cff09171802662da7105d79586c7659677a0ecbaddac4cce06cb2a11f69a16fa0c4d7002ac7d51a4d",
@@ -1577,6 +1577,21 @@ var require_pkg_src = __commonJS({
         size: 1046,
         hash: "03ee5be239c91c735d2c95db89a0d1b77e602cfc18af8eb64b3281fddcd90a72"
       },
+      agentModuleExecutor: {
+        // Bound to the isolated Sepolia agent group 7 ("DH-Agent-Sepolia"), which
+        // holds this action and no PKPs until an agent is minted into it. NOT yet
+        // bound on mainnet — the Base `DH-Agent-Mainnet` group is created at rollout.
+        cid: "QmVgjGXUuxoGf8XyddW8a7btaazT9yEotpKoBgb65oPvcF",
+        authorizedCidHex: cidToHex(
+          "QmVgjGXUuxoGf8XyddW8a7btaazT9yEotpKoBgb65oPvcF"
+        ),
+        name: "Agent Module Executor",
+        description: "Capability gate for multi-sig Safe agent delegation: binds the agent PKP to the AgentDelegationRegistry record before signing (authorize | execute modes)",
+        version: "1.0.0",
+        deployed: true,
+        size: 11785,
+        hash: "fa294e164273c2158f9ef11a0ccfd735c343c0e3759fcb4b37e0f8a5d1ab0d29"
+      },
       staleSpendRecoveryValidator: {
         cid: "QmXQWT8V4wjuvH8BbC7xrkYxsVu5AKfvfWcS7jnYfrexYm",
         authorizedCidHex: cidToHex(
@@ -1596,17 +1611,17 @@ var require_pkg_src = __commonJS({
         }
       },
       btcUtxoInvalidator: {
-        cid: "QmZE422cZsEjYN8pE6AmpkgFoZCK4UAfdDuzoVRRsMJbwm",
+        cid: "Qmf4Ze8yhnQhHbnX5RPgJrC7Jw1aA3gbpfpd52kFg7fd1m",
         authorizedCidHex: cidToHex(
-          "QmZE422cZsEjYN8pE6AmpkgFoZCK4UAfdDuzoVRRsMJbwm"
+          "Qmf4Ze8yhnQhHbnX5RPgJrC7Jw1aA3gbpfpd52kFg7fd1m"
         ),
         name: "Btc Utxo Invalidator",
         description: "Production Btc Utxo Invalidator",
         version: "1.0.0",
         deployed: true,
-        deployedAt: 1785226423791,
-        size: 61472,
-        hash: "75eca528d8ac30ae8f21caaae206ccab162a83a048d622868e60f645f0c475e2"
+        deployedAt: 1786113911948,
+        size: 62553,
+        hash: "1dcea2b49e545c423195be22e072dc5e3039ed1c95a8490b23505956029f5b33"
       }
     };
     function getDeploymentsForNetwork(network) {
@@ -6164,7 +6179,10 @@ import { keccak256, toUtf8Bytes, solidityPackedKeccak256, getBytes, Contract } f
 // src/utils/quantum-timing.ts
 var QUANTUM_WINDOW_SECONDS = 60;
 var DEAD_ZONE_SECONDS = 8;
-var INCLUSION_LATENCY_BUDGET = 16;
+var SLOT_SECONDS = 12;
+var INCLUSION_SLOT_TOLERANCE = 3;
+var INCLUSION_LATENCY_BUDGET = SLOT_SECONDS * INCLUSION_SLOT_TOLERANCE;
+var MAX_GATE_POLLS = 12;
 var POST_BOUNDARY_SKEW_MARGIN = 3;
 function calculateNextQuantumTimestamp() {
   const now = Math.floor(Date.now() / 1e3);
@@ -6197,8 +6215,17 @@ function validateQuantumTiming(signedTimestamp, _bufferSeconds = 30) {
 async function awaitSafeSubmissionWindow(quantumTimestamp, opts = {}) {
   const now = opts.now ?? (() => Math.floor(Date.now() / 1e3));
   const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
-  const nowSec = now();
   const signatureQuantum = Math.floor(quantumTimestamp / QUANTUM_WINDOW_SECONDS) * QUANTUM_WINDOW_SECONDS;
+  if (opts.chainNow) {
+    const chainResult = await awaitSafeSubmissionWindowOnChain(
+      signatureQuantum,
+      opts.chainNow,
+      sleep
+    );
+    if (chainResult)
+      return chainResult;
+  }
+  const nowSec = now();
   const currentQuantum = Math.floor(nowSec / QUANTUM_WINDOW_SECONDS) * QUANTUM_WINDOW_SECONDS;
   const secsToBoundary = QUANTUM_WINDOW_SECONDS - nowSec % QUANTUM_WINDOW_SECONDS;
   const isNextQuantumSig = signatureQuantum === currentQuantum + QUANTUM_WINDOW_SECONDS;
@@ -6215,6 +6242,44 @@ async function awaitSafeSubmissionWindow(quantumTimestamp, opts = {}) {
   }
   return { waited: false, waitedSeconds: 0 };
 }
+async function awaitSafeSubmissionWindowOnChain(signatureQuantum, chainNow, sleep) {
+  let waitedSeconds = 0;
+  for (let poll = 0; poll < MAX_GATE_POLLS; poll++) {
+    let head;
+    try {
+      head = await chainNow();
+    } catch {
+      head = null;
+    }
+    if (head === null || !Number.isFinite(head)) {
+      return waitedSeconds > 0 ? { waited: true, waitedSeconds } : null;
+    }
+    const chainQuantum = Math.floor(head / QUANTUM_WINDOW_SECONDS) * QUANTUM_WINDOW_SECONDS;
+    if (signatureQuantum <= chainQuantum) {
+      return { waited: waitedSeconds > 0, waitedSeconds };
+    }
+    const earliestMine = head + SLOT_SECONDS;
+    const latestMine = head + SLOT_SECONDS * INCLUSION_SLOT_TOLERANCE;
+    const safeBeforeDeadZone = latestMine < signatureQuantum - DEAD_ZONE_SECONDS;
+    const safeAfterBoundary = earliestMine >= signatureQuantum;
+    if (safeBeforeDeadZone || safeAfterBoundary) {
+      return { waited: waitedSeconds > 0, waitedSeconds };
+    }
+    const sleepSeconds = Math.max(
+      1,
+      Math.min(SLOT_SECONDS, signatureQuantum - head)
+    );
+    log.debug(
+      `[Quantum Timing] \u23F3 Deferring send ${sleepSeconds}s to clear the quantum dead zone (sig quantum ${signatureQuantum}, chain head ${head}, insured mine window [${earliestMine}, ${latestMine}])`
+    );
+    await sleep(sleepSeconds * 1e3);
+    waitedSeconds += sleepSeconds;
+  }
+  log.debug(
+    `[Quantum Timing] \u26A0\uFE0F  Dead-zone gate exhausted ${MAX_GATE_POLLS} chain polls (sig quantum ${signatureQuantum}) \u2014 proceeding`
+  );
+  return { waited: waitedSeconds > 0, waitedSeconds };
+}
 
 // src/utils/mint-authorization.utils.ts
 var PKP_NFT_ABI = [
@@ -7171,6 +7236,20 @@ function decodeQuantumRevert(e) {
   }
   return { data, selector, name };
 }
+var RETRYABLE_QUANTUM_ERROR_NAMES = [
+  "DeadZoneViolation",
+  "QuantumOutsideWindow",
+  "QuantumAlreadyUsed",
+  "QuantumExpired"
+];
+function isRetryableQuantumFailure(message) {
+  if (!message)
+    return false;
+  if (message.includes("Transaction timeout") || message.includes("Transaction confirmation failed") || message.includes("Transaction receipt not found")) {
+    return false;
+  }
+  return RETRYABLE_QUANTUM_ERROR_NAMES.some((name) => message.includes(name)) || message.includes("Transaction reverted");
+}
 
 // src/utils/quantum-submission.utils.ts
 var MAX_DEADZONE_RESIMULATIONS = 3;
@@ -7192,9 +7271,14 @@ async function assertSafeQuantumSubmission(opts) {
   const now = opts.now ?? (() => Math.floor(Date.now() / 1e3));
   const onDebug = opts.onDebug ?? (() => {
   });
+  const chainNow = opts.chainNow ?? (typeof provider.getBlock === "function" ? async () => {
+    const block = await provider.getBlock("latest");
+    return typeof block?.timestamp === "number" ? block.timestamp : null;
+  } : void 0);
   const gateOpts = {
     now,
-    ...opts.sleep ? { sleep: opts.sleep } : {}
+    ...opts.sleep ? { sleep: opts.sleep } : {},
+    ...chainNow ? { chainNow } : {}
   };
   await awaitSafeSubmissionWindow(quantumTimestamp, gateOpts);
   const SAME_BLOCK_INTERACTION_SELECTOR = "0x3b53d1db";
@@ -22218,10 +22302,7 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
   isRetryablePaymentQuantumFailure(result) {
     if (result.success || !result.error)
       return false;
-    const e = result.error;
-    if (e.includes("Transaction timeout"))
-      return false;
-    return e.includes("DeadZoneViolation") || e.includes("QuantumOutsideWindow") || e.includes("QuantumAlreadyUsed") || e.includes("QuantumExpired") || e === "Transaction reverted";
+    return isRetryableQuantumFailure(result.error);
   }
   /**
    * One payment attempt: user auth → Lit Action authorization → dead-zone gate →
@@ -22860,6 +22941,37 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
     }
     return this.withdrawalAddressModule.getEntries(target);
   }
+  /**
+   * 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).
+   */
+  async decodeMinedRevert(params) {
+    try {
+      await this.getProviderOrThrow().call({
+        to: params.to,
+        from: params.from,
+        data: params.data,
+        blockTag: params.blockNumber
+      });
+      return null;
+    } catch (replayError) {
+      const decoded = decodeQuantumRevert(replayError);
+      return decoded.name ?? decoded.selector ?? null;
+    }
+  }
   /**
    * Withdraw Bitcoin from a position
    *
@@ -23433,9 +23545,23 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
           txHash: tx.hash
         });
       }
+      const withdrawProvider = this.getProviderOrThrow();
+      const withdrawTimeoutMs = this.config.transactionTimeoutMs || 3e5;
       let receipt;
       try {
-        receipt = await tx.wait();
+        receipt = await Promise.race([
+          withdrawProvider.waitForTransaction(tx.hash, 1),
+          new Promise(
+            (_, reject) => setTimeout(
+              () => reject(
+                new Error(
+                  `Transaction timeout after ${withdrawTimeoutMs}ms. Hash: ${tx.hash}`
+                )
+              ),
+              withdrawTimeoutMs
+            )
+          )
+        ]);
       } catch (waitError) {
         const waitErrorMsg = waitError instanceof Error ? waitError.message : String(waitError);
         if (this.config.debug) {
@@ -23452,7 +23578,26 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
       if (!receipt) {
         return {
           success: false,
-          error: `Transaction confirmation returned no receipt. Hash: ${tx.hash}`
+          error: `Transaction receipt not found for hash: ${tx.hash}`
+        };
+      }
+      if (receipt.status === 0) {
+        const revertName = await this.decodeMinedRevert({
+          to: positionManagerAddress,
+          from: await withdrawSigner.getAddress(),
+          data: withdrawCalldata,
+          blockNumber: receipt.blockNumber
+        });
+        if (this.config.debug) {
+          log.error("\u274C withdrawBTC reverted on-chain", {
+            txHash: receipt.hash,
+            blockNumber: receipt.blockNumber,
+            revert: revertName ?? "undecodable"
+          });
+        }
+        return {
+          success: false,
+          error: `Transaction reverted: ${revertName ?? "unknown reason"} (tx: ${receipt.hash})`
         };
       }
       if (this.config.debug) {
@@ -24580,13 +24725,11 @@ Message: ${causeMessage}${quantumContext}${mintDebtDiagnostics}`
         if (authResult.success) {
           break;
         }
-        const isQuantumError = authResult.error?.includes(
-          "QuantumOutsideWindow"
-        );
+        const isQuantumError = isRetryableQuantumFailure(authResult.error);
         if (isQuantumError && wAttempt < MAX_WITHDRAWAL_QUANTUM_RETRIES) {
           if (this.config.debug) {
             log.warn(
-              `\u26A0\uFE0F  Phase 1 QuantumOutsideWindow (attempt ${wAttempt}/${MAX_WITHDRAWAL_QUANTUM_RETRIES}). LIT action took too long. Retrying with fresh quantum...`
+              `\u26A0\uFE0F  Phase 1 quantum-timing failure (attempt ${wAttempt}/${MAX_WITHDRAWAL_QUANTUM_RETRIES}): ${authResult.error}. Retrying with a fresh quantum...`
             );
           }
           await new Promise((resolve) => setTimeout(resolve, 2e3));

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

@@ -540,6 +540,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
      *

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.324",
   "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.311",
     "@noble/hashes": "^1.5.0",
     "axios": "^1.17.0",
     "bech32": "^2.0.0",