@gvnrdao/dh-sdk 0.0.339 → 0.0.341

package/dist/utils/loan-helpers.utils.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Loan Helper Utilities
+ * Extracted common patterns for loan data processing and enrichment
+ */
+import type { LoanData, LoanDataDetail, BitcoinAddresses } from '../interfaces';
+import type { BitcoinProvider } from './bitcoin-provider.utils';
+import type { ConcurrencyLimiter } from './concurrency-limiter.utils';
+/**
+ * Derive Bitcoin addresses for a loan if needed
+ * @param loan Loan data that may need address derivation
+ * @param bitcoinNetwork Target Bitcoin network ("mainnet" | "testnet" | "regtest")
+ * @param getBitcoinAddressesFromPkp Function to derive addresses from PKP
+ * @returns Updated loan with derived addresses
+ */
+export declare function deriveAddressesIfNeeded(loan: LoanData | LoanDataDetail, bitcoinNetwork: "mainnet" | "testnet" | "regtest" | undefined, getBitcoinAddressesFromPkp: (pkpPublicKey: string) => Promise<BitcoinAddresses>): Promise<LoanData | LoanDataDetail>;
+/**
+ * Enrich loans with Bitcoin balance information
+ * Handles the common pattern of fetching and attaching balance data
+ * @param loans Array of loans to enrich
+ * @param bitcoinProvider Bitcoin provider instance
+ * @param concurrencyLimiter Optional concurrency limiter for controlled parallel execution
+ * @param getBalanceWithCache Function to get balance with caching
+ * @returns Enriched loans with balance information
+ */
+export declare function enrichWithBalance(loans: (LoanData | LoanDataDetail)[], bitcoinProvider: BitcoinProvider | null, concurrencyLimiter: ConcurrencyLimiter | null, getBalanceWithCache: (vaultAddress: string) => Promise<any>): Promise<(LoanData | LoanDataDetail)[]>;
+/**
+ * Normalize loan data transformation
+ * Single mapper to avoid subtle divergence across methods
+ * @param rawLoan Raw loan data from contract or graph
+ * @param transformType Type of transformation to apply
+ * @returns Normalized loan data
+ */
+export declare function normalizeLoanTransform(rawLoan: any, transformType?: 'contract' | 'graph'): LoanData | LoanDataDetail;
+/**
+ * Extract vault address from loan collateral
+ * Handles both string and BitcoinAddresses object types
+ * @param loan Loan data
+ * @param preferredNetwork Preferred network to use if multiple addresses available
+ * @returns Vault address string
+ */
+export declare function extractVaultAddress(loan: LoanData | LoanDataDetail, preferredNetwork?: 'mainnet' | 'testnet' | 'regtest'): string;
+/**
+ * Select Bitcoin address for the given network.
+ *
+ * @param addresses Bitcoin addresses object (mainnet/testnet/regtest variants)
+ * @param bitcoinNetwork Target network ("mainnet" | "testnet" | "regtest" | undefined → mainnet)
+ */
+export declare function selectBitcoinAddress(addresses: BitcoinAddresses, bitcoinNetwork: "mainnet" | "testnet" | "regtest" | undefined): string;
+/**
+ * Calculate the expected mint fee for a UCD mint, including the Scenario B tail fee.
+ *
+ * Scenario B applies when:
+ *  - The loan has been renewed (previousExpiryAt > 0), AND
+ *  - The mint occurs before the original term expiry (mintTimestamp < previousExpiryAt)
+ *
+ * In that case, an additional pro-rata tail fee is charged for the remaining time
+ * in the original term, on top of the standard origination fee for the renewal term.
+ *
+ * Formula:
+ *   standardFee = originationFeeBps * mintAmount / 10000
+ *   tailFee     = (tailSeconds / originalTermSeconds) * originationFeeBps * mintAmount / 10000
+ *   totalFee    = standardFee + tailFee   (Scenario B only)
+ *
+ * This function is purely local (no RPC calls) and mirrors ProtocolConstants logic:
+ *   12 months = 365 days; other terms = 30 days/month.
+ *
+ * @param mintAmount     - Amount of UCD to mint (in wei, bigint)
+ * @param mintTimestamp  - Unix timestamp of the mint (seconds)
+ * @param originationFeeBps - Origination fee in basis points (e.g. 50 = 0.5%)
+ * @param expiryAt       - Current loan expiry timestamp after renewal (seconds)
+ * @param previousExpiryAt - Expiry before last renewal; 0 if never renewed (seconds)
+ * @param selectedTerm   - Current term segment in months (e.g. 12)
+ * @param totalTerm      - Total accumulated loan months (e.g. 24 after one renewal); 0 before first renewal
+ */
+export declare function calculateMintFee(params: {
+    mintAmount: bigint;
+    mintTimestamp: number;
+    originationFeeBps: number;
+    expiryAt: number;
+    previousExpiryAt: number;
+    selectedTerm: number;
+    totalTerm: number;
+}): bigint;
+/**
+ * Base origination fee on a principal (wei), `floor(amount * bps / 10000)` —
+ * the same integer arithmetic the Lit validator and TermManager use. Excludes
+ * the post-renewal tail fee, so it is a LOWER bound on the fee the validator
+ * will charge; a pre-check built on it can only be more permissive, never
+ * stricter, than the validator's own fee-inclusive check.
+ */
+export declare function baseMintFeeWei(mintAmountWei: bigint, originationFeeBps: number): bigint;
+/**
+ * The loan cap is fee-INCLUSIVE on-chain: `UCDController._enforceLoanPathPerMintCap`
+ * rejects when `currentDebt + mintAmount + mintFee > maximumLoanValueUcd`
+ * (audit V12 #62230). Mainnet 2026-09-15: a 98 UCD mint + 2.94 fee against a
+ * 100 UCD cap passed every principal-only pre-check, paid for the Lit round-trip
+ * and reverted `MintGuardFailed(1)`. Mirrors the contract exactly — equal to the
+ * cap is allowed.
+ */
+export declare function debtAfterMintExceedsLoanCap(params: {
+    currentDebtWei: bigint;
+    mintAmountWei: bigint;
+    mintFeeWei: bigint;
+    maxLoanWei: bigint;
+}): boolean;
+/**
+ * Largest principal (wei) that still fits under the cap once its base fee is
+ * added: `floor((maxLoan - currentDebt) * 10000 / (10000 + bps))`; zero when
+ * the position is already at or above the cap.
+ */
+export declare function maxPrincipalWithinLoanCap(params: {
+    maxLoanWei: bigint;
+    currentDebtWei: bigint;
+    originationFeeBps: number;
+}): bigint;

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

@@ -15,8 +15,20 @@ 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.
+ * The custom-error selectors the mint/payment/quantum paths decode.
+ *
+ * EVERY row is an error some contract declares, and
+ * `tests/shared/unit/contract-error-decoder.test.ts` proves it against the committed ABIs —
+ * because six rows here were fiction, and fiction on this path is read by a borrower:
+ *
+ *  - `InDeadZone()`, `QuantumExpired()`, `UnauthorizedSigner()` and a no-argument
+ *    `InvalidSignature()` are declared by NO contract (the real ones are
+ *    `DeadZoneViolation()`, and `InvalidSignature(string reason)`);
+ *  - `0x48f5c3ed` was labelled `Unauthorized()`, which is really `0x82b42900`;
+ *  - `0x3ee5aeb5` was labelled `OperationNotAuthorized()` — it is
+ *    `ReentrancyGuardReentrantCall()`, and `0xd92e233d`, labelled `ValidationFailed()`, is
+ *    really `ZeroAddress()` (`ValidationFailed()` is `0x0a0b0d79`). Both are reachable
+ *    reverts that were being reported to users under another error's name.
  */
 export declare const QUANTUM_REVERT_NAMES: Record<string, string>;
 export interface DecodedRevert {

package/dist/utils/sign-guard/errors.d.ts

@@ -5,5 +5,9 @@
  * `instanceof` checks in consumers cannot split across two module realms.
  */
 export declare class TxValidationError extends Error {
-    constructor(msg: string);
+    /**
+     * @param subject What is being refused. Defaults to the server-returned transaction the
+     *   validator exists for; client-built flows (the PSM exchange) name themselves instead.
+     */
+    constructor(msg: string, subject?: string);
 }

package/dist/utils/sign-guard/fee-ceiling.d.ts

@@ -16,6 +16,22 @@
 export declare const MAX_GAS_LIMIT = 5000000n;
 export declare const MAX_FEE_PER_GAS_WEI = 2000000000000n;
 export declare const DEFAULT_MAX_TX_FEE_WEI = 250000000000000000n;
+/**
+ * The priority-fee (tip) band for a quantum-bounded send, in wei.
+ *
+ * These live HERE, beside the ceilings, because they are the same kind of fact — what a
+ * client may pay — and every client needs them: the SDK's EIP-1559 broadcaster clamps the
+ * market tip into this band, and the CLI and MCP price their own sends. They were
+ * previously reachable only from a deep SDK path (`utils/chunks/eip1559-broadcast.utils`),
+ * which a consumer taking only `./sign-guard` cannot import, so each client wrote its own
+ * numbers instead.
+ *
+ * Floor: builders skip a tip that is too low, and a missed quantum wastes the Lit
+ * signatures, the Chipotle spend and the reverted transaction's base fee — all far more
+ * than the tip. Cap: a spiking `eth_feeHistory` must not turn into an overpaid send.
+ */
+export declare const PRIORITY_FEE_FLOOR_WEI = 100000000n;
+export declare const PRIORITY_FEE_CAP_WEI = 3000000000n;
 export interface FeeCeiling {
     maxGasLimit: bigint;
     maxFeePerGasWei: bigint;

package/dist/utils/sign-guard/index.d.ts

@@ -1,9 +1,10 @@
 export { TxValidationError } from "./errors";
 export { SIGNABLE_FUNCTIONS, encodeSignable, decodeSignable, signableFunctionName, signableSelectors, } from "./signable-functions";
-export { MAX_GAS_LIMIT, MAX_FEE_PER_GAS_WEI, DEFAULT_MAX_TX_FEE_WEI, DEFAULT_FEE_CEILING, worstCaseFeeWei, assertFeeCeiling, type FeeCeiling, } from "./fee-ceiling";
+export { MAX_GAS_LIMIT, MAX_FEE_PER_GAS_WEI, DEFAULT_MAX_TX_FEE_WEI, PRIORITY_FEE_FLOOR_WEI, PRIORITY_FEE_CAP_WEI, DEFAULT_FEE_CEILING, worstCaseFeeWei, assertFeeCeiling, type FeeCeiling, } from "./fee-ceiling";
 export { validateUnsignedTx, buildValidationContext, describeUnsignedTx, readTxFeeFields, type ExpectedAction, type ContractRegistry, type ValidationContext, } from "./tx-validator";
 export { QUANTUM_SECONDS, AUTH_VALIDITY_WINDOWS, authValiditySec, nextQuantumTimestamp, isAuthFresh, isStrictCurrentQuantum, modeForChainId, randomNonceHex, OP_ENVELOPE_LAYOUT, OP_ENVELOPE_TYPES, OP_ENVELOPE_FIELD_ORDER, stampOpEnvelope, buildAuthEnvelope, type OpEnvelopeInput, type StampedOpEnvelope, type AuthEnvelope, } from "./op-envelope";
 export { DELEGATED_OPS, BROADCAST_PATH, type DelegatedOp, type DelegatedOpSpec } from "./op-specs";
 export { REQUEST_TIMEOUT_MS, LitOpsHttpError, LitOpsTransportError, fetchWithTimeout, postJson, asEnvelope, authorizeWithServer, broadcastSignedTx, type FetchOptions, type ExecuteEnvelope, type BroadcastEnvelope, type ExecuteOutcome, type BroadcastOutcome, } from "./lit-ops-client";
 export { signAndBroadcast, type SignGuardSigner } from "./sign-and-broadcast";
 export { computeExtendFeeUpperBound, type ExtendFeeBound } from "./extend-fee-bound";
+export { buildPsmApproveTx, buildPsmSwapTx, buildPsmRedeemTx, planPsmExchange, executePsmPlan, psmExchangeReadsFromProvider, type PsmUnsignedTx, type PsmLeg, type PsmExchangeAddresses, type PsmExchangeReads, type PsmExchangePlan, } from "./psm-exchange";

package/dist/utils/sign-guard/psm-exchange.d.ts

@@ -0,0 +1,122 @@
+import { ethers } from "ethers";
+import { type ExpectedAction, type ValidationContext } from "./tx-validator";
+/**
+ * The PSM exchange pair — stablecoin → UCD (`swap`) and UCD → stablecoin (`redeem`) — built and
+ * validated in ONE place, for every client.
+ *
+ * Exact-amount approvals only. The SDK's old `psmSwap` / `psmRedeem` approved `MaxUint256`, so a
+ * single swap left an unlimited allowance behind; the MCP refused to use them and built its own
+ * exact-amount flow. This module is that flow, lifted into the SDK.
+ *
+ * Deliberately split in two:
+ *  - `planPsmExchange` builds every leg and runs `validateUnsignedTx` on each before returning;
+ *  - `executePsmPlan` sends the legs through an ethers `Signer` — the path a browser wallet can
+ *    take (`sendTransaction`). Clients with their own signing pipeline (the MCP's keystore and
+ *    approval cards) take the validated legs from the plan and submit them their own way.
+ */
+/** An unsigned tx exactly as `validateUnsignedTx` consumes it. */
+export interface PsmUnsignedTx {
+    to: string;
+    data: string;
+    value: "0x0";
+    chainId: number;
+}
+export interface PsmLeg {
+    /** What this leg is — for progress reporting, cards and error messages. */
+    step: "reset-approve" | "approve" | "swap" | "redeem";
+    tx: PsmUnsignedTx;
+    /** The sign-guard expectation this leg was validated against. Re-check any populated form with it. */
+    expected: ExpectedAction;
+}
+export interface PsmExchangeAddresses {
+    /** SimplePSMV2 proxy. */
+    psm: string;
+    /** The stablecoin swapped in (swap) or received (redeem). */
+    stablecoin: string;
+    /** Required for redeem: UCD is the token approved. */
+    ucdToken?: string;
+    /** Required for redeem: UCDToken.burn spends the allowance as the UCDController (audit M-4). */
+    ucdController?: string;
+}
+/** The two on-chain facts the plan depends on. Injected so the planner stays pure. */
+export interface PsmExchangeReads {
+    isStablecoinSupported(stablecoin: string): Promise<boolean>;
+    allowance(token: string, owner: string, spender: string): Promise<bigint>;
+}
+export interface PsmExchangePlan {
+    direction: "swap" | "redeem";
+    owner: string;
+    /** The token approved: the stablecoin for swap, UCD for redeem. */
+    token: string;
+    /** Its spender: the PSM for swap, the UCDController for redeem. */
+    spender: string;
+    amountIn: bigint;
+    minOut: bigint;
+    /** The allowance read when the plan was made. */
+    allowanceBefore: bigint;
+    /** Zero, one (approve) or two (reset to zero, then approve) legs — in send order. */
+    approvals: PsmLeg[];
+    exec: PsmLeg;
+}
+export declare function buildPsmApproveTx(p: {
+    token: string;
+    spender: string;
+    amount: bigint;
+    chainId: number;
+}): PsmUnsignedTx;
+export declare function buildPsmSwapTx(p: {
+    psm: string;
+    stablecoin: string;
+    amountIn: bigint;
+    minOut: bigint;
+    chainId: number;
+}): PsmUnsignedTx;
+export declare function buildPsmRedeemTx(p: {
+    psm: string;
+    stablecoin: string;
+    ucdAmount: bigint;
+    minOut: bigint;
+    chainId: number;
+}): PsmUnsignedTx;
+/** Provider-backed reads for the planner. */
+export declare function psmExchangeReadsFromProvider(provider: ethers.Provider, psmAddress: string): PsmExchangeReads;
+/**
+ * Build and validate every leg of one PSM exchange. Throws before anything is signed when:
+ * the amount or the minimum-out floor is zero (the contract refuses a zero floor); an address
+ * is missing — a redeem refuses rather than guess its spender; or the stablecoin is not
+ * supported by the PSM ON-CHAIN (an index or a config can lag a governance removal).
+ *
+ * Approvals, against the allowance read now:
+ *  - `allowance >= amountIn` → no approve leg;
+ *  - `allowance == 0`        → approve exactly `amountIn`;
+ *  - otherwise               → approve 0, then approve exactly `amountIn`. Some tokens (USDT)
+ *    revert a non-zero → non-zero approve, and a failed exchange can leave exactly this partial
+ *    residue. Resetting first is correct for every ERC-20, so it is not token-sniffed.
+ */
+export declare function planPsmExchange(params: {
+    direction: "swap" | "redeem";
+    owner: string;
+    addresses: PsmExchangeAddresses;
+    amountIn: bigint;
+    minOut: bigint;
+    vctx: ValidationContext;
+    reads: PsmExchangeReads;
+}): Promise<PsmExchangePlan>;
+/**
+ * Send a plan's legs through an ethers `Signer`, in order, each confirmed before the next.
+ *
+ * Each leg's request — exactly `{to, data, value: 0, chainId}` — is validated again immediately
+ * before it is handed over. Nonce, gas and fees are NOT populated here: the signer populates them
+ * when the leg's turn comes (a swap cannot be gas-estimated until its approve is mined), so a
+ * browser wallet shows the user its own fee and a Safe signer applies its own nonce, exactly as
+ * before. Blind signers that need the fee ceiling on the signed form (CLI, MCP) take the
+ * validated legs from the plan into their own pipeline instead.
+ *
+ * A leg that reverts or fails throws, naming the step; when an approve already landed, the error
+ * says so, because an exact allowance then stands.
+ */
+export declare function executePsmPlan(plan: PsmExchangePlan, signer: ethers.Signer, vctx: ValidationContext): Promise<{
+    hash: string;
+    blockNumber: number;
+    approvalHashes: string[];
+}>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gvnrdao/dh-sdk",
-  "version": "0.0.339",
+  "version": "0.0.341",
   "description": "TypeScript SDK for Diamond Hands Protocol",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -39,6 +39,11 @@
       "types": "./dist/sign-guard.d.ts",
       "import": "./dist/sign-guard.mjs",
       "require": "./dist/sign-guard.js"
+    },
+    "./contract-errors": {
+      "types": "./dist/contract-errors.d.ts",
+      "import": "./dist/contract-errors.mjs",
+      "require": "./dist/contract-errors.js"
     }
   },
   "files": [
@@ -50,8 +55,9 @@
   "scripts": {
     "build": "npm run sync:deployments && npm run validate:contracts && npm run build:node",
     "build:all": "npm run sync:deployments && npm run validate:contracts && npm run build:node && npm run build:browser",
-    "build:node": "npm run sync:deployments && tsup && npm run build:types",
+    "build:node": "npm run sync:deployments && tsup && npm run build:types && npm run check:bundle-externals",
     "build:types": "tsc -p tsconfig.build.json",
+    "check:bundle-externals": "node scripts/check-bundle-externals.mjs",
     "build:browser": "cd browser && npm install && npm run build",
     "sync:deployments": "node scripts/sync-deployments.js",
     "sync:typechain": "cd ../contracts && npm run compile",
@@ -74,7 +80,8 @@
     "lint": "eslint src --ext .ts && npm run lint:server-boundary && npm run lint:sign-guard",
     "lint:server-boundary": "node scripts/check-pkp-mint-server-imports.mjs",
     "lint:sign-guard": "node scripts/check-sign-guard-imports.mjs",
-    "clean": "rm -rf dist && rm -rf browser/dist"
+    "clean": "rm -rf dist && rm -rf browser/dist",
+    "gen:contract-errors": "node scripts/gen-contract-errors.mjs"
   },
   "keywords": [
     "bitcoin",
@@ -93,18 +100,22 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@gvnrdao/dh-lit-actions": "^0.0.322",
-    "@gvnrdao/dh-lit-ops": "^0.0.316",
     "@noble/hashes": "^1.5.0",
     "axios": "^1.17.0",
     "bech32": "^2.0.0",
     "bip66": "^2.0.0",
     "bitcoinjs-lib": "^6.1.0",
+    "bn.js": "^5.2.3",
     "bs58check": "^3.0.1",
     "crypto-js": "^4.2.0",
     "dotenv": "^17.4.2",
+    "elliptic": "^6.6.1",
     "ethers": "6.16.0",
-    "valibot": "^1.1.0"
+    "uuid": "^9.0.1"
+  },
+  "optionalDependencies": {
+    "@gvnrdao/dh-lit-actions": "^0.0.322",
+    "@gvnrdao/dh-lit-ops": "^0.0.316"
   },
   "devDependencies": {
     "@babel/preset-env": "7.29.7",
@@ -151,6 +162,9 @@
       ],
       "sign-guard": [
         "./dist/sign-guard.d.ts"
+      ],
+      "contract-errors": [
+        "./dist/contract-errors.d.ts"
       ]
     }
   }