@gvnrdao/dh-sdk 0.0.338 → 0.0.340

package/dist/utils/concurrency-limiter.utils.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Concurrency Limiter Utility
+ * Limits the number of concurrent operations to prevent overwhelming external services
+ */
+/**
+ * Concurrency limiter configuration
+ */
+export interface ConcurrencyLimiterConfig {
+    concurrency?: number;
+    timeout?: number;
+    debug?: boolean;
+}
+/**
+ * Concurrency limiter for controlling parallel operations
+ */
+export declare class ConcurrencyLimiter {
+    private concurrency;
+    private timeout;
+    private debug;
+    private running;
+    private queue;
+    constructor(config?: ConcurrencyLimiterConfig);
+    /**
+     * Execute a function with concurrency limiting
+     */
+    execute<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Process the queue of pending operations
+     */
+    private processQueue;
+    /**
+     * Run function with timeout
+     */
+    private runWithTimeout;
+    /**
+     * Get current status
+     */
+    getStatus(): {
+        running: number;
+        queued: number;
+        concurrency: number;
+    };
+    /**
+     * Wait for all operations to complete
+     */
+    waitForAll(): Promise<void>;
+    /**
+     * Clear queue and reject pending operations
+     */
+    clear(): void;
+}
+/**
+ * Create a concurrency limiter with default settings
+ */
+export declare function createConcurrencyLimiter(config?: ConcurrencyLimiterConfig): ConcurrencyLimiter;
+/**
+ * Execute multiple functions with concurrency limiting
+ */
+export declare function executeWithConcurrencyLimit<T>(functions: Array<() => Promise<T>>, config?: ConcurrencyLimiterConfig): Promise<T[]>;

package/dist/utils/lit-action-chain-name.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Chain names the Lit Actions understand, by EVM chainId.
+ *
+ * The name selects the action's policy — address pinning, allowed RPC hosts, whether a dev
+ * Bitcoin provider is honoured — so it is looked up, never guessed. Sepolia uses regtest Bitcoin
+ * (the private dh-btc-faucet), the same convention as lit-ops-server.
+ */
+export declare const LIT_ACTION_CHAIN_NAMES: Readonly<Record<number, string>>;
+/**
+ * The Lit Action chain name for `chainId`. Throws on an unsupported chain rather than falling
+ * back: defaulting to "sepolia" ran Hardhat under Sepolia policy, and signed for any unknown
+ * chain under Sepolia's name.
+ */
+export declare function litActionChainNameForChainId(chainId: number | bigint): string;

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/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/index.d.ts

@@ -7,3 +7,4 @@ export { DELEGATED_OPS, BROADCAST_PATH, type DelegatedOp, type DelegatedOpSpec }
 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.338",
+  "version": "0.0.340",
   "description": "TypeScript SDK for Diamond Hands Protocol",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -94,7 +94,7 @@
   "sideEffects": false,
   "dependencies": {
     "@gvnrdao/dh-lit-actions": "^0.0.322",
-    "@gvnrdao/dh-lit-ops": "^0.0.315",
+    "@gvnrdao/dh-lit-ops": "^0.0.316",
     "@noble/hashes": "^1.5.0",
     "axios": "^1.17.0",
     "bech32": "^2.0.0",
@@ -103,8 +103,7 @@
     "bs58check": "^3.0.1",
     "crypto-js": "^4.2.0",
     "dotenv": "^17.4.2",
-    "ethers": "6.16.0",
-    "valibot": "^1.1.0"
+    "ethers": "6.16.0"
   },
   "devDependencies": {
     "@babel/preset-env": "7.29.7",