@gvnrdao/dh-sdk 0.0.305 → 0.0.307

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 ReconciledWithdrawal } from "../utils/withdrawal-reconciliation.utils";
 import { ContractManager } from "./contract/contract-manager.module";
 import { WithdrawalAddressModule } from "./withdrawal-address/withdrawal-address.module";
 import { BitcoinOperations } from "./bitcoin/bitcoin-operations.module";
@@ -475,6 +476,18 @@ export declare class DiamondHandsSDK {
      * @param request - Execution request with positionId, utxoIdentifier, and networkFee
      * @returns Execution result with Bitcoin txid
      */
+    /**
+     * STANDALONE Phase 2: sign + broadcast the withdrawal Bitcoin transaction
+     * in-process — the same orchestration lit-ops-server performs, composed
+     * from the same primitives (`litOps.signBTCTransaction`, which has always
+     * had a standalone path, and `broadcastSignedBitcoinTransaction`).
+     * Both modes must support withdrawal execution (Master mandate 2026-07-21).
+     *
+     * The service path's post-broadcast CRIT-2 re-verification exists to catch
+     * a LYING SERVER; here the broadcast happens locally from the signatures we
+     * just obtained, so the esplora-returned txid is already first-hand.
+     */
+    private executeBTCWithdrawalStandalonePhase2;
     executeBTCWithdrawal(request: {
         positionId: string;
         utxoIdentifier: string;
@@ -544,6 +557,27 @@ export declare class DiamondHandsSDK {
         authorizedAt: number;
         utxoKey: string;
     }>>;
+    /**
+     * Reconcile every pending withdrawal against BITCOIN truth (incident
+     * 2026-07-22): `getPendingWithdrawals` only reflects on-chain
+     * authorizations, and the contract can never know whether the Phase-2 BTC
+     * broadcast happened. Callers MUST use the returned `status` to decide what
+     * to offer:
+     * - EXECUTABLE      → offer Execute (the only status that may).
+     * - EXECUTED        → auto-clear; `spendingTxid` is the completion proof.
+     * - SPENT_MISMATCH  → unexecutable; offer cancelPendingWithdrawal.
+     * - CORRUPT         → authorization contradicts the chain (e.g. declared
+     *                     satoshis ≠ real output value); offer Cancel &
+     *                     re-request — Execute can only die at the signer guard.
+     * - UNFUNDED        → funding tx unknown/unconfirmed; wait.
+     *
+     * @param opts.esploraBaseUrl Esplora API base (e.g. the api proxy
+     *   `/v1/proxy/esplora/<network>`). Falls back to
+     *   `config.bitcoinProviders[0].url`; throws when neither is configured.
+     */
+    reconcilePendingWithdrawals(positionId: string, opts?: {
+        esploraBaseUrl?: string;
+    }): Promise<Array<ReconciledWithdrawal<Awaited<ReturnType<DiamondHandsSDK["getPendingWithdrawals"]>>[number]>>>;
     /**
      * Cancel a pending BTC withdrawal
      *
@@ -944,6 +978,13 @@ export declare class DiamondHandsSDK {
      * Check if running on production network
      */
     private isProductionNetwork;
+    /**
+     * Local-lane activation, verified against the LIVE node at call time (not
+     * the chainId cached at init — a provider that switched networks after
+     * init fails the fresh probe). Zero RPC cost outside a lane process tree:
+     * without LIT_LANE_GUARD=1 this short-circuits to false before any probe.
+     */
+    private isLocalLaneGuardActive;
     /**
      * Get Bitcoin network based on chain.
      *

package/dist/utils/lane-guard.utils.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Local-verification-lane guard — the ONLY file in the SDK allowed to read
+ * the `LIT_LANE_*` environment (enforced by
+ * `contracts/tests/unit/lane-guard-env-allowlist.unit.test.ts`).
+ *
+ * The lane hooks (quantum-phase alignment before mint authorization, the
+ * simulated-SameBlockInteraction tolerance) exist solely to absorb local
+ * hardhat artifacts: tunnel latency and automine's stale-latest-block
+ * simulation. They are never correct on a live network, so activation is
+ * TRIPLY bound, verified against the live node at the moment of use:
+ *
+ *   1. `LIT_LANE_GUARD=1` — exported only by `scripts/lane-env-guard.sh`
+ *      for the detached local lane's process tree, AND
+ *   2. a fresh `eth_chainId` probe (NOT ethers' init-time network cache, so a
+ *      provider that switched networks after init cannot keep the hooks
+ *      alive) returns a hardhat chainId (1337 `npx hardhat node`, 31337
+ *      in-process default), AND
+ *   3. the node self-identifies as Hardhat via `web3_clientVersion` — a
+ *      live/private network that merely reuses chainId 1337/31337 does not.
+ *
+ * Any probe failure, missing `send` capability, or unexpected answer is
+ * treated as NOT the lane — fail closed. The on-chain guards remain fully
+ * authoritative in every mode regardless.
+ */
+/** Minimal raw-RPC seam — satisfied by ethers v6 JsonRpcApiProvider. */
+export interface RawRpcSender {
+    send?(method: string, params: unknown[]): Promise<unknown>;
+}
+/** The env half of the guard: is the lane environment exported at all? */
+export declare function laneGuardEnvEnabled(): boolean;
+/**
+ * Full lane-guard check against the LIVE node. Cheap short-circuit (no RPC)
+ * when the lane env is not exported — the two probes only ever run inside a
+ * lane process tree.
+ */
+export declare function isLaneGuardActiveOnProvider(provider: RawRpcSender | undefined | null): Promise<boolean>;

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

@@ -61,6 +61,14 @@ export interface SafeQuantumSubmissionOpts {
     sleep?: (ms: number) => Promise<void>;
     /** Debug sink; called with human-readable progress lines. */
     onDebug?: (msg: string) => void;
+    /**
+     * Local-lane activation, computed by the caller at submission time via
+     * `isLaneGuardActiveOnProvider` (lane env exported + live node probes as a
+     * hardhat chain/client). Only consulted by the local-lane
+     * SameBlockInteraction tolerance; omitted or false keeps the fail-fast
+     * behavior on every decodable revert.
+     */
+    laneGuardActive?: boolean;
 }
 /**
  * Gate + pre-send simulation loop. Resolves when it is safe to broadcast;

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

@@ -0,0 +1,64 @@
+/**
+ * Pending-withdrawal reconciliation — classify each on-chain authorized spend
+ * (`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".
+ *
+ * Statuses:
+ * - EXECUTABLE      — outpoint confirmed, unspent, values 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; surface Cancel.
+ * - CORRUPT         — authorization contradicts the chain (declared value ≠
+ *                     real output value, targetAmount > real value, or vout
+ *                     out of range) → surface Cancel & re-request; never Execute.
+ * - UNFUNDED        — funding tx unknown/unconfirmed → wait; no Execute yet.
+ *
+ * Esplora `spent: true` claims are only trusted when the spending tx can be
+ * fetched AND provably includes this outpoint among its inputs — the regtest
+ * faucet's esplora answers `spent: true` for arbitrary txids, and a false
+ * "executed" here would silently dismiss a withdrawal the user was never paid
+ * for. Unverifiable claims classify as EXECUTABLE (chain truth: no proven
+ * spend); a genuinely-spent outpoint then simply fails downstream, safely.
+ */
+export type PendingWithdrawalStatus = "EXECUTABLE" | "EXECUTED" | "SPENT_MISMATCH" | "CORRUPT" | "UNFUNDED";
+export interface AuthorizedSpendLike {
+    txid: string;
+    vout: number;
+    satoshis: number;
+    targetAddress: string;
+    targetAmount: number;
+}
+export interface ReconciledWithdrawal<T extends AuthorizedSpendLike = AuthorizedSpendLike> {
+    spend: T;
+    status: PendingWithdrawalStatus;
+    /** Human-readable, single-sentence explanation of the classification. */
+    reason: string;
+    /** Real value of the referenced outpoint, when the funding tx is known. */
+    onChainOutputValue?: number;
+    /** The verified spending tx, for EXECUTED / SPENT_MISMATCH. */
+    spendingTxid?: string;
+    /** Sats the verified spending tx pays to `targetAddress` (EXECUTED only). */
+    paidToTargetSats?: number;
+}
+/**
+ * HTTP seam: GET `url`, resolve `{ status, body }` (body null on non-JSON).
+ * Injectable for tests; the default uses global `fetch` (node ≥18 + browsers).
+ * Transport failures throw — reconciliation must fail LOUD, never classify on
+ * missing data.
+ */
+export type HttpGetJson = (url: string) => Promise<{
+    status: number;
+    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>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gvnrdao/dh-sdk",
-  "version": "0.0.305",
+  "version": "0.0.307",
   "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.315",
-    "@gvnrdao/dh-lit-ops": "^0.0.305",
+    "@gvnrdao/dh-lit-actions": "0.0.315",
+    "@gvnrdao/dh-lit-ops": "0.0.306",
     "@noble/hashes": "^1.5.0",
     "axios": "^1.17.0",
     "bech32": "^2.0.0",
@@ -92,7 +92,7 @@
     "bs58check": "^3.0.1",
     "crypto-js": "^4.2.0",
     "dotenv": "^17.4.2",
-    "ethers": "^6.16.0",
+    "ethers": "6.16.0",
     "valibot": "^1.1.0"
   },
   "devDependencies": {