@gvnrdao/dh-sdk 0.0.299 → 0.0.301

package/dist/utils/chunks/eip1559-broadcast.utils.d.ts

@@ -4,27 +4,24 @@
  */
 import { type Provider, type Signer, type TransactionResponse } from "ethers";
 /**
- * Cap on mintUCD's gasLimit. mintUCD dynamically sizes gasLimit via
- * estimateContractCallGasWithMargin() (real eth_estimateGas + 25% margin) on
- * mainnet, so this value is NOT normally what gets submitted -- it only
- * becomes the literal gasLimit if (a) the estimate comes back anomalously
- * high, or (b) eth_estimateGas itself fails (some RPCs return bare 0x even
- * for valid txs), in which case — after a static call proves the tx valid —
- * this raw value is used as the gasLimit on any chain.
- * Previously 10,000,000 with a comment claiming "mintUCD + LIT validation
- * can exceed 7M gas" -- no evidence of that was found across 16 real mint
- * transactions checked (1 mainnet, 15 recent Sepolia, 2026-07-02): the
- * dynamically-computed gasLimit actually submitted ranged 388,620-886,988.
- * Lowered to 2,000,000 (~2.25x headroom over the highest real value seen)
- * for consistency with MAKE_PAYMENT_GAS_CEILING/EXTEND_POSITION_GAS_CEILING's
- * ~1.5-2x-headroom convention -- a smaller margin than those because this
- * ceiling is a rarely-hit fallback/cap, not the everyday operating value, so
- * a little extra buffer for cold-storage variance is cheap insurance.
+ * Fixed-gas ceiling for mintUCD's broadcast. Since the gold-standard refactor
+ * (2026-07-08) this IS the everyday submitted gasLimit: mintUCD no longer runs
+ * eth_estimateGas (its round-trip latency re-introduced the quantum-boundary
+ * race the submission gate exists to prevent), matching makePayment /
+ * withdrawBTC / extendPosition. Grounded in 16 real mint transactions
+ * (1 mainnet, 15 recent Sepolia, 2026-07-02): the estimate-derived gasLimit
+ * actually submitted ranged 388,620-886,988, and those limits all succeeded —
+ * so 886,988 is a KNOWN-SUFFICIENT limit, not a bare gasUsed figure.
+ * 1,300,000 gives ~1.47x headroom over it, matching MAKE_PAYMENT_GAS_CEILING's
+ * ~1.5x convention. Deliberately NOT higher: wallets (MetaMask) reject a tx
+ * when balance < gasLimit × maxFeePerGas, so an oversized fixed ceiling
+ * (previously 2M as a rarely-hit cap) would block low-ETH users from an
+ * affordable mint.
  */
 export declare const MINT_UCD_GAS_CEILING: bigint;
 /**
- * Fixed-gas ceiling for the withdrawBTC raw-tx fallback (used when estimateGas
- * is unavailable on the RPC). The on-chain flow now spans PositionManager →
+ * Fixed-gas ceiling for withdrawBTC's broadcast (the everyday submitted
+ * gasLimit — no estimateGas runs on this path). The on-chain flow now spans PositionManager →
  * CollateralManager → LoanOperationsManager → BTCSpendAuthorizer plus the audit
  * #3 Chainlink feed-staleness gate and the BitcoinWithdrawalAddressRegistry
  * allowlist STATICCALL; observed end-to-end cost is ~1.0–1.3M gas, so the prior
@@ -89,12 +86,6 @@ export declare const LIQUIDATION_COMMIT_GAS_CEILING: bigint;
  * provisional until re-measured against a real liquidation.
  */
 export declare const LIQUIDATION_REVEAL_GAS_CEILING: bigint;
-/** Headroom on eth_estimateGas (25%). */
-export declare const MINT_UCD_ESTIMATE_MARGIN_BPS = 2500;
-/**
- * Returns gas limit with margin, capped, or null if estimateGas reverts/fails.
- */
-export declare function estimateContractCallGasWithMargin(provider: Provider, from: string, to: string, data: string, marginBps: number, ceiling: bigint): Promise<bigint | null>;
 export declare function resolveEip1559FeeFields(provider: Provider): Promise<{
     maxFeePerGas: bigint;
     maxPriorityFeePerGas: bigint;

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

@@ -0,0 +1,41 @@
+/**
+ * Shared decoder for custom-error reverts surfaced by quantum-signed operations
+ * (mintUCD / makePayment / withdrawBTC / extendPosition / liquidation).
+ *
+ * Consolidates what used to be three hand-rolled selector maps + ad-hoc error-data
+ * extraction scattered across diamond-hands-sdk.ts. The extraction probes EVERY
+ * nesting ethers v6 uses across provider types — notably `info.error.data`, which
+ * `BrowserProvider` (MetaMask) uses and the older per-site extractors missed, so a
+ * browser-provider DeadZoneViolation could slip through undetected and wrongly throw.
+ */
+/** `DeadZoneViolation()` selector — the stale-latest-block artifact we tolerate. */
+export declare const DEAD_ZONE_VIOLATION_SELECTOR = "0xbe4b82c1";
+/** Solidity `Error(string)` (require/revert with a message). */
+export declare const ERROR_STRING_SELECTOR = "0x08c379a0";
+/** Solidity `Panic(uint256)` (assert failures, overflow, div-by-zero, …). */
+export declare const PANIC_SELECTOR = "0x4e487b71";
+/**
+ * Union of the custom-error selectors the mint/payment/quantum paths decode. Keep in
+ * sync with OperationAuthorizationRegistry / PositionManager / LoanOperationsManager.
+ */
+export declare const QUANTUM_REVERT_NAMES: Record<string, string>;
+export interface DecodedRevert {
+    /** Raw revert data (`0x…`) if any provider nesting carried it, else null. */
+    data: string | null;
+    /** 4-byte custom-error selector (`0x…`) if the data is a valid custom error. */
+    selector: string | null;
+    /** Human-readable error name if the selector is known, else null. */
+    name: string | null;
+}
+/**
+ * Extract the revert data / custom-error selector / known name from an ethers error,
+ * probing every provider nesting (JsonRpc, Browser/MetaMask, wrapped `error.error`).
+ *
+ * Besides the custom-error selector map, decodes the two standard Solidity revert
+ * shapes so require-message reverts stay actionable when call sites rely solely on
+ * this decoder: `Error(string)` yields `name = 'Error("<message>")'` and
+ * `Panic(uint256)` yields `name = "Panic(0x<code>)"`.
+ */
+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;

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

@@ -0,0 +1,93 @@
+/**
+ * Shared submission-time safety for quantum-signed broadcasts
+ * (makePayment / mintUCD / withdrawBTC / extendPosition).
+ *
+ * One helper owns the dead-zone gate AND the pre-send simulate/re-simulate loop
+ * that used to exist as three subtly different inline copies in
+ * diamond-hands-sdk.ts. Callers encode calldata, call
+ * `assertSafeQuantumSubmission`, then broadcast ONCE with a fixed gas ceiling
+ * (`sendEip1559Transaction`) — never `estimateGas`, whose latency re-introduces
+ * the boundary race the gate exists to prevent, and never a re-broadcast.
+ *
+ * See docs/sdk-quantum-goldstandard-refactor-plan-2026-07-08.md.
+ */
+/** Default cap on dead-zone-triggered re-simulations (mirrors old makePayment). */
+export declare const MAX_DEADZONE_RESIMULATIONS = 3;
+/**
+ * Thrown when the pre-send simulation proves the transaction would revert.
+ * Carries everything a caller needs to enrich the failure without re-probing
+ * the provider error itself:
+ *
+ * - `errorName`  — decoded name, e.g. `"QuantumExpired()"` or `Error("msg")`
+ *                  (named to avoid shadowing `Error.name`).
+ * - `selector`   — 4-byte selector, e.g. `"0x131d9a21"`.
+ * - `data`       — FULL revert data (mintUCD decodes
+ *                  `DebtUpdateVerificationFailedDetailed` args from it).
+ * - `cause`      — the original provider error (`reason` / `shortMessage`
+ *                  fallbacks, empty-data detection → `diagnoseMintUCD`).
+ *
+ * Only thrown for DECODABLE reverts (revert data present). Transport-level
+ * `eth_call` failures never raise this — see `assertSafeQuantumSubmission`.
+ */
+export declare class QuantumRevertError extends Error {
+    readonly errorName: string | null;
+    readonly selector: string | null;
+    readonly data: string | null;
+    readonly cause: unknown;
+    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: {
+        call(tx: {
+            to: string;
+            from: string;
+            data: string;
+        }): Promise<string>;
+    };
+    /** Target contract address. */
+    to: string;
+    /** Sender address — `eth_call` must run as the real sender (auth checks). */
+    from: string;
+    /** Encoded calldata; broadcast MUST send these exact bytes. */
+    data: string;
+    /** The quantum timestamp embedded in the LIT-signed payload. */
+    quantumTimestamp: number;
+    /** Cap on dead-zone re-simulations (default {@link MAX_DEADZONE_RESIMULATIONS}). */
+    maxResimulations?: number;
+    /** Clock seam (whole seconds). Drives BOTH the gate and the artifact test. */
+    now?: () => number;
+    /** Sleep seam, forwarded to the gate. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Debug sink; called with human-readable progress lines. */
+    onDebug?: (msg: string) => void;
+}
+/**
+ * Gate + pre-send simulation loop. Resolves when it is safe to broadcast;
+ * throws {@link QuantumRevertError} on a real (non-artifact) decodable revert.
+ * Never broadcasts anything itself.
+ *
+ * Sequence:
+ * 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.
+ * 2. **Simulate** (`eth_call`) and route the outcome:
+ *    - success → safe to broadcast.
+ *    - `DeadZoneViolation()` → `eth_call` runs against the LATEST block's
+ *      (slightly stale) timestamp while the on-chain rule uses MINE time. If
+ *      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`).
+ *    - 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
+ *      quirk) → log and proceed. The fixed-ceiling broadcast degrades to the
+ *      pre-refactor blind-broadcast behavior instead of letting a flaky RPC
+ *      block a valid money-path operation.
+ * 3. **Final re-gate**: the sim loop adds RPC round-trips after step 1; this
+ *    closes the drift with pure clock math (no RPC). If it waits, the
+ *    signature is CURRENT afterward and needs no further simulation.
+ */
+export declare function assertSafeQuantumSubmission(opts: SafeQuantumSubmissionOpts): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gvnrdao/dh-sdk",
-  "version": "0.0.299",
+  "version": "0.0.301",
   "description": "TypeScript SDK for Diamond Hands Protocol - Bitcoin-backed lending with LIT Protocol PKPs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -82,8 +82,8 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@gvnrdao/dh-lit-actions": "^0.0.312",
-    "@gvnrdao/dh-lit-ops": "^0.0.302",
+    "@gvnrdao/dh-lit-actions": "^0.0.313",
+    "@gvnrdao/dh-lit-ops": "^0.0.303",
     "@noble/hashes": "^1.5.0",
     "axios": "^1.17.0",
     "bech32": "^2.0.0",