@gvnrdao/dh-sdk 0.0.332 → 0.0.334

package/dist/modules/withdrawal-address/withdrawal-address.module.d.ts

@@ -85,6 +85,29 @@ export declare class WithdrawalAddressModule {
      * hard guarantee).
      */
     assertApprovedForWithdrawal(borrower: string, btcAddress: string): Promise<Result<void, SDKError>>;
+    /**
+     * Ask the node for the reason a failed write did not carry.
+     *
+     * A failing `eth_estimateGas` frequently answers with NOTHING to decode — ethers renders that
+     * as `missing revert data ... data=null, reason=null, revert=null`, which names no cause and
+     * cannot distinguish "the contract rejected this" from "the RPC hiccuped". An `eth_call` of the
+     * same calldata usually does carry the revert reason or custom-error selector, so this runs one
+     * and folds the answer into the reported error.
+     *
+     * Three deliberate properties:
+     *
+     * 1. It runs ONLY after the write has already failed. Gating the write on a static call would
+     *    let a flaky endpoint — precisely the condition this exists to diagnose — block an add that
+     *    would otherwise have succeeded.
+     * 2. It costs NO extra signature. `staticCall` is `eth_call`: a node read, never a wallet prompt.
+     * 3. It can never throw. A diagnostic that escapes would replace the real cause with itself.
+     *    (The `try/catch` here is the authorized exception to CLAUDE.md's forbidden-patterns rule;
+     *    it swallows nothing — every branch returns text that is reported alongside the original.)
+     *
+     * A static call that SUCCEEDS is itself a finding: the contract accepts this call, so the
+     * failure lay outside contract logic (RPC, gas, or nonce).
+     */
+    private staticCallDiagnostic;
     private txFailure;
 }
 export declare function createWithdrawalAddressModule(config: WithdrawalAddressModuleConfig): WithdrawalAddressModule;

package/dist/utils/borrower-authorization-712.d.ts

@@ -0,0 +1,81 @@
+/**
+ * EIP-712 type definitions for borrower authorization messages — SDK copy.
+ *
+ * ## Why this is a copy, and why that is safe
+ *
+ * The single source of truth lives in `@gvnrdao/dh-lit-actions`
+ * (`lit-actions/src/constants/borrower-authorization-types.ts`), which the LIT
+ * Actions' dual-accept verifier reads. The SDK cannot import it yet: the
+ * published `dh-lit-actions@0.0.321` predates those constants, and bumping this
+ * package's dependency to an unpublished version makes `npm ci` fail with E404
+ * (proven 2026-08-27). So this module re-declares the four field lists — with a
+ * **pinned-vector parity suite**
+ * (`sdk/tests/shared/unit/borrower-authorization-712.test.ts`) asserting the
+ * domain separator, every typehash and every digest are byte-identical to the
+ * pins in `lit-actions/tests/unit/borrower-authorization-types.unit.test.ts`.
+ * Drift breaks a test suite before it can break a production signature — the
+ * same cross-package discipline as `recovery-auth-hash-parity`.
+ *
+ * **Fold this back into a re-export when `dh-lit-actions@>=0.0.322` publishes**
+ * (the deferred publish follow-up); the parity suite then becomes redundant
+ * protection rather than the only protection.
+ *
+ * ## What these are
+ *
+ * The wallet prompt fired BEFORE every loan transaction. Encoding it as typed
+ * data (instead of `personal_sign` over a precomputed keccak digest) is what
+ * lets MetaMask render `RepayRequest { positionId, paymentAmount,
+ * quantumTimestamp }` instead of an opaque 32-byte hex string. The ERC-7730
+ * descriptor (`clear-signing/pending/eip712-LoanOperationsManager.json`) keys
+ * its formats by these `encodeType` strings verbatim.
+ *
+ * No Solidity contract recomputes these digests: the borrower signature is
+ * consumed entirely inside the LIT Actions' `AuthorizationModule`. The
+ * `verifyingContract` (the LoanOperationsManager proxy) is truthful as the
+ * module that owns the operations, not as a `_hashTypedDataV4` call site.
+ */
+import { type Signer, type TypedDataField } from 'ethers';
+/** Shared with the LIT runtime — see `PROTOCOL_EIP712_DOMAIN_NAME` there. */
+export declare const BORROWER_AUTHORIZATION_712_DOMAIN_NAME = "DiamondHands.Protocol";
+export declare const BORROWER_AUTHORIZATION_712_DOMAIN_VERSION = "1";
+export type BorrowerAuthorization712PrimaryType = 'MintRequest' | 'RepayRequest' | 'RenewRequest' | 'WithdrawRequest';
+/**
+ * Field lists per primary type. **Order is part of the digest** — any change
+ * here must land in the same coordinated step as the lit-actions constants,
+ * the descriptor, and a CID rotation (EIP712_DOMAIN_SPEC.md §4.1).
+ */
+export declare const BORROWER_AUTHORIZATION_712_FIELDS: Readonly<Record<BorrowerAuthorization712PrimaryType, readonly TypedDataField[]>>;
+export interface BorrowerAuthorization712Domain {
+    readonly name: string;
+    readonly version: string;
+    readonly chainId: number;
+    readonly verifyingContract: string;
+}
+/**
+ * The `types` argument for `signer.signTypedData(domain, types, message)`.
+ * Returns ONLY the requested primary type — handing the signer all four would
+ * let a mis-shaped message encode as a different operation without complaint.
+ */
+export declare function borrowerAuthorization712Types(primaryType: BorrowerAuthorization712PrimaryType): Record<string, TypedDataField[]>;
+/**
+ * Build the EIP-712 domain for a chain.
+ *
+ * `verifyingContract` is the LoanOperationsManagerModule proxy from the SDK's
+ * own synced deployment constants (`scripts/sync-deployments.js` — the same
+ * generator that feeds the LIT Actions' pinned map, so the two sides of the
+ * digest cannot desync on a redeploy). Throws for a chain with no known LOM —
+ * there is no legitimate borrower authorization to build there.
+ */
+export declare function buildBorrowerAuthorization712Domain(chainId: number): BorrowerAuthorization712Domain;
+/** Compute the EIP-712 digest — the precomputed-signature path's hash. */
+export declare function borrowerAuthorization712Digest(primaryType: BorrowerAuthorization712PrimaryType, chainId: number, message: Record<string, unknown>): string;
+/**
+ * Sign a borrower authorization as typed data.
+ *
+ * Fails fast on a signer without `signTypedData` — no capability fallback to
+ * `personal_sign`: a signer that cannot produce typed data must go through an
+ * `authorizationProvider` (the Safe/agent seam), where the signature is
+ * produced by a party that can. A silent downgrade here would quietly
+ * reintroduce the opaque-hash prompt this whole change removes.
+ */
+export declare function signBorrowerAuthorization712(signer: Signer, primaryType: BorrowerAuthorization712PrimaryType, chainId: number, message: Record<string, unknown>): Promise<string>;

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

@@ -24,9 +24,14 @@ export declare const MINT_UCD_GAS_CEILING: bigint;
  * 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
- * hardcoded 1,000,000 limit caused a nested out-of-gas. 3M gives ~2x headroom
- * while staying well under the block gas limit.
+ * allowlist STATICCALL; observed end-to-end cost was ~1.0–1.3M gas when this
+ * was sized, so the prior hardcoded 1,000,000 limit caused a nested out-of-gas.
+ * A mainnet withdrawBTC measured 750,919 gas on 2026-09-04 (2 vault inputs,
+ * 1 prior reservation; tx 0xa244a184…) — recorded as a data point, NOT a new
+ * ceiling basis: cost grows with the number of open reservations
+ * (`_computeAuthorizedSpendsHash` is O(N)), so the ceiling stays sized to the
+ * observed MAX. 3M gives ~2x headroom over it while staying well under the
+ * block gas limit.
  */
 export declare const WITHDRAW_BTC_GAS_CEILING: bigint;
 /**
@@ -86,12 +91,60 @@ export declare const LIQUIDATION_COMMIT_GAS_CEILING: bigint;
  * provisional until re-measured against a real liquidation.
  */
 export declare const LIQUIDATION_REVEAL_GAS_CEILING: bigint;
-export declare function resolveEip1559FeeFields(provider: Provider): Promise<{
+/**
+ * Priority-fee (tip) policy for every timing-sensitive broadcast in this file.
+ *
+ * History that sizes these numbers (docs/withdraw-btc-gas-cost-recommendations-2026-09-05.md):
+ * - 2026-07-02: a 0 gwei tip (the read RPC reported a real 0n
+ *   eth_maxPriorityFeePerGas) sat unmined 119–143 s → QuantumOutsideWindow.
+ * - 2026-08-07: a 0.0007 gwei tip was skipped by one NEAR-EMPTY block, mined
+ *   24 s later → DeadZoneViolation (see quantum-timing.ts).
+ * - 2026-09-04: a mainnet withdrawBTC went out with ethers' hardcoded 1 gwei
+ *   fallback tip (the wallet provider did not answer eth_maxPriorityFeePerGas)
+ *   while the market p50 tip was ~0.03 gwei — 93% of a $1.99 tx was tip.
+ *
+ * So the tip is read from the market (eth_feeHistory on the app's READ RPC,
+ * never the wallet provider) at a percentile that buys next-block inclusion,
+ * then clamped: the floor keeps builders from skipping us (a quantum miss
+ * wastes the Lit signatures, the Chipotle spend and the reverted tx's base
+ * fee — far more than the tip), the cap stops a spiking feeHistory from
+ * overpaying. At ~751k gas the floor costs ≈ $0.18 (ETH $2,458).
+ */
+export declare const PRIORITY_FEE_FLOOR_WEI: bigint;
+export declare const PRIORITY_FEE_CAP_WEI: bigint;
+/** Blocks of eth_feeHistory sampled; the median across them absorbs a single spike block. */
+export declare const FEE_HISTORY_BLOCK_COUNT = 20;
+/**
+ * Reward percentile per block. p75 (not p50) because these sends are
+ * quantum-bounded: paying above the median tip buys inclusion in the next
+ * slot or two, which is what the 60 s window actually needs.
+ */
+export declare const FEE_HISTORY_REWARD_PERCENTILE = 75;
+/** The subset of ethers' JsonRpcApiProvider these helpers need — raw JSON-RPC access. */
+export interface JsonRpcSendable {
+    send(method: string, params: unknown[]): Promise<unknown>;
+}
+/**
+ * Resolve EIP-1559 fee fields from the app's READ RPC.
+ *
+ * `feeProvider` must be a JSON-RPC provider (ethers `JsonRpcProvider` or any
+ * object exposing `send`), NOT the wallet's `BrowserProvider`: wallet
+ * providers routinely fail `eth_maxPriorityFeePerGas`, and ethers'
+ * `getFeeData()` then silently substitutes a 1 gwei tip — the 2026-09-04
+ * overpayment. This helper never calls `getFeeData()`.
+ *
+ * One `eth_feeHistory` round-trip replaces the three RPC calls `getFeeData()`
+ * made (block, gasPrice, priorityFee), so it is also faster on the
+ * quantum-gated path that runs right before the send.
+ */
+export declare function resolveEip1559FeeFields(feeProvider: Provider): Promise<{
     maxFeePerGas: bigint;
     maxPriorityFeePerGas: bigint;
 }>;
 export declare function sendEip1559Transaction(params: {
     signer: Signer;
+    /** The SDK READ provider (JSON-RPC). Fee fields come from here, never from `signer.provider`. */
+    feeProvider: Provider;
     to: string;
     data: string;
     gasLimit: bigint;

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

@@ -18,14 +18,18 @@ export interface ExtendOwnerAuthorization {
     callerAddress: string;
 }
 /**
- * Build the extend authorization message hash without signing.
+ * Build the extend authorization digest without signing.
  *
  * Use this when signing with a smart contract wallet (e.g. Safe) that
- * needs to wrap the hash in its own domain before signing.
+ * needs to wrap the digest in its own domain before signing.
+ *
+ * Since the EIP-712 cutover this is the TYPED-DATA digest
+ * (`RenewRequest(bytes32 positionId,uint256 selectedTerm,uint256
+ * quantumTimestamp)`) — same shape, different hash (plan step 18).
  *
  * @param positionId - Position identifier
  * @param newTerm - Extension term in months (number)
- * @param chainId - Chain ID for cross-chain replay protection
+ * @param chainId - Chain ID (selects the EIP-712 domain)
  * @returns { hash, timestamp } — pass these to Safe for signing
  */
 export declare function buildExtendAuthorizationHash(positionId: string, newTerm: number, chainId: number): {
@@ -35,19 +39,16 @@ export declare function buildExtendAuthorizationHash(positionId: string, newTerm
 /**
  * Generate extend position authorization signature
  *
- * Creates a signature that matches the format expected by
- * AuthorizationModule.verifyExtendAuthorization in lit-actions.
- *
- * Message structure:
- * solidityKeccak256(
- *   ["bytes32", "uint256", "uint256", "uint256", "bytes32"],
- *   [positionId, timestamp, chainId, newTerm, actionHash]
- * )
+ * Creates an EIP-712 signature the dual-accept
+ * AuthorizationModule.verifyExtendAuthorization verifies on its typed arm —
+ * rendered by the wallet as `RenewRequest { positionId, selectedTerm,
+ * quantumTimestamp }` under the DiamondHands.Protocol/LOM domain
+ * (see utils/borrower-authorization-712.ts).
  *
- * Where:
- * - actionHash = keccak256("extend-position")
- * - Signer address is recovered from signature by LIT Action
- * - LIT Action validates recovered address === position owner
+ * The WIRE OBJECT IS UNCHANGED (plan step 19): the transported fields keep
+ * their legacy names (`timestamp`, `newTerm`, `action: "extend-position"`) so
+ * every server hop and the validator's legacy arm keep working — only the
+ * signature's encoding differs, and the verifier tries both.
  *
  * @param positionId - Position identifier
  * @param newTerm - Extension term in months (number)

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

@@ -18,17 +18,23 @@ export interface MintOwnerAuthorization {
     signature: string;
 }
 /**
- * Build the mint authorization message hash without signing.
+ * Build the mint authorization digest without signing.
  *
  * Use this when signing with a smart contract wallet (e.g. Safe) that
- * needs to wrap the hash in its own domain before signing.
+ * needs to wrap the digest in its own domain before signing.
  *
- * Returns the raw hash AND the timestamp so both can be passed to
+ * Since the EIP-712 cutover this is the TYPED-DATA digest
+ * (`MintRequest(bytes32 positionId,uint256 mintAmount,uint256 quantumTimestamp)`
+ * under the DiamondHands.Protocol/LOM domain) — same shape, different hash
+ * (plan step 18). The LIT Action's dual-accept verifier resolves EIP-1271
+ * queries against this digest on the typed arm.
+ *
+ * Returns the digest AND the timestamp so both can be passed to
  * generateMintAuthorization via the pre-computed signature overload.
  *
  * @param positionId - Position identifier
  * @param amount - Amount to mint in wei (bigint)
- * @param chainId - Chain ID for cross-chain replay protection
+ * @param chainId - Chain ID (selects the EIP-712 domain)
  * @returns { hash, timestamp } — pass these to Safe for signing
  */
 export declare function buildMintAuthorizationHash(positionId: string, amount: bigint, chainId: number): {
@@ -38,19 +44,22 @@ export declare function buildMintAuthorizationHash(positionId: string, amount: b
 /**
  * Generate mint authorization signature
  *
- * Creates a signature that matches the format expected by
- * AuthorizationModule.verifyMintAuthorization in lit-actions.
+ * Creates an EIP-712 signature the dual-accept
+ * AuthorizationModule.verifyMintAuthorization in lit-actions verifies on its
+ * typed arm — and, unlike the legacy `personal_sign`-over-a-digest form, one
+ * the wallet can RENDER: MetaMask shows
+ * `MintRequest { positionId, mintAmount, quantumTimestamp }` instead of an
+ * opaque 32-byte hex string.
  *
- * Message structure:
- * solidityKeccak256(
- *   ["bytes32", "uint256", "uint256", "uint256", "bytes32"],
- *   [positionId, timestamp, chainId, amount, actionHash]
- * )
+ * Typed message (see utils/borrower-authorization-712.ts):
+ *   MintRequest(bytes32 positionId,uint256 mintAmount,uint256 quantumTimestamp)
+ * under domain { name: "DiamondHands.Protocol", version: "1", chainId,
+ * verifyingContract: LoanOperationsManagerModule }.
  *
- * Where:
- * - actionHash = keccak256("mint-ucd")
- * - Signer address is recovered from signature by LIT Action
- * - LIT Action validates recovered address === position owner
+ * The WIRE OBJECT IS UNCHANGED (plan step 19): the transported fields
+ * (positionId, timestamp, chainId, amount, action) keep their names and
+ * values so the LIT Action's legacy arm and every server hop keep working —
+ * only the signature's encoding differs, and the verifier tries both.
  *
  * @param positionId - Position identifier
  * @param amount - Amount to mint in wei (bigint)
@@ -99,19 +108,14 @@ export interface BalanceConfirmationAuthorization {
 /**
  * Generate payment authorization signature
  *
- * Creates a signature that matches the format expected by
- * process-payment-validator LIT Action.
- *
- * Message structure:
- * solidityKeccak256(
- *   ["bytes32", "uint256", "uint256", "uint256", "bytes32"],
- *   [positionId, timestamp, chainId, amount, actionHash]
- * )
+ * Creates an EIP-712 signature the dual-accept process-payment-validator
+ * verifies on its typed arm — rendered by the wallet as
+ * `RepayRequest { positionId, paymentAmount, quantumTimestamp }` under the
+ * DiamondHands.Protocol/LOM domain (see utils/borrower-authorization-712.ts).
  *
- * Where:
- * - actionHash = keccak256("make-payment")
- * - Signer address is recovered from signature by LIT Action
- * - LIT Action validates recovered address === position owner
+ * The WIRE OBJECT IS UNCHANGED (plan step 19): fields keep their legacy names
+ * (`timestamp`, `amount`, `action: "make-payment"`) so every server hop and the
+ * validator's legacy arm keep working; only the signature's encoding differs.
  */
 export declare function generatePaymentAuthorization(positionId: string, amount: bigint, chainId: number, signerOrPrecomputed: Signer | {
     timestamp: number;
@@ -173,14 +177,19 @@ export interface WithdrawOwnerAuthorization {
     signature: string;
 }
 /**
- * Build the withdraw authorization message hash without signing.
+ * Build the withdraw authorization digest without signing.
  *
  * Use this when signing with a smart contract wallet (e.g. Safe) that
- * needs to wrap the hash in its own domain before signing.
+ * needs to wrap the digest in its own domain before signing.
+ *
+ * Since the EIP-712 cutover this is the TYPED-DATA digest
+ * (`WithdrawRequest(bytes32 positionId,uint256 totalDeduction,string
+ * withdrawalAddress,uint256 quantumTimestamp)`) — same shape, different hash
+ * (plan step 18).
  *
  * @param positionId - Position identifier
  * @param amount - Amount to withdraw in satoshis (bigint)
- * @param chainId - Chain ID for cross-chain replay protection
+ * @param chainId - Chain ID (selects the EIP-712 domain)
  * @param destinationAddress - Bitcoin destination address
  * @returns { hash, timestamp } — pass these to Safe for signing
  */
@@ -191,19 +200,17 @@ export declare function buildWithdrawAuthorizationHash(positionId: string, amoun
 /**
  * Generate withdrawal authorization signature
  *
- * Creates a signature that matches the format expected by
- * AuthorizationModule.verifyWithdrawAuthorization in lit-actions.
- *
- * Message structure:
- * solidityKeccak256(
- *   ["bytes32", "uint256", "uint256", "uint256", "string", "bytes32"],
- *   [positionId, timestamp, chainId, amount, destinationAddress, actionHash]
- * )
- *
- * Where:
- * - actionHash = keccak256("withdraw-btc")
- * - Signer address is recovered from signature by LIT Action
- * - LIT Action validates recovered address === position owner
+ * Creates an EIP-712 signature the dual-accept
+ * AuthorizationModule.verifyWithdrawAuthorization verifies on its typed arm —
+ * rendered by the wallet as `WithdrawRequest { positionId, totalDeduction,
+ * withdrawalAddress, quantumTimestamp }`, which puts the actual Bitcoin
+ * destination on the confirmation screen. A frontend that silently substitutes
+ * a different destination is contradicted by the user's own wallet.
+ *
+ * The WIRE OBJECT IS UNCHANGED (plan step 19): the transported fields keep
+ * their legacy names (`amount`, `action: "withdraw-btc"`; `destinationAddress`
+ * is re-attached by the caller as `withdrawalAddress`) — only the signature's
+ * encoding differs, and the verifier tries both.
  *
  * @param positionId - Position identifier
  * @param amount - Amount to withdraw in satoshis (bigint)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gvnrdao/dh-sdk",
-  "version": "0.0.332",
+  "version": "0.0.334",
   "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.321",
-    "@gvnrdao/dh-lit-ops": "^0.0.314",
+    "@gvnrdao/dh-lit-actions": "^0.0.322",
+    "@gvnrdao/dh-lit-ops": "^0.0.315",
     "@noble/hashes": "^1.5.0",
     "axios": "^1.17.0",
     "bech32": "^2.0.0",