@gvnrdao/dh-sdk 0.0.274 → 0.0.276

package/dist/interfaces/chunks/config.i.d.ts

@@ -34,6 +34,8 @@ export interface ContractAddresses {
     feeRecipientRegistry?: string;
     /** PositionDelegateRegistry proxy; consumed by LIT Action authorization verifier as the third recovery arm for Safe-as-borrower flows. */
     positionDelegateRegistry?: string;
+    /** BitcoinWithdrawalAddressRegistry proxy; per-wallet allowlist that gates borrower-initiated BTC withdrawal destinations (24h time-lock). */
+    bitcoinWithdrawalAddressRegistry?: string;
     mockUsdcToken?: string;
     mockUsdcOwner?: string;
     mockUsdtToken?: string;

package/dist/modules/contract/contract-manager.module.d.ts

@@ -10,7 +10,7 @@
  * This module centralizes all contract interaction setup and provides
  * a clean interface for other modules to access contracts.
  */
-import { type Provider, type Signer } from "ethers";
+import { Contract, type Provider, type Signer } from "ethers";
 import type { ContractAddresses } from "../../interfaces/chunks/config.i";
 import { type DeploymentContracts } from "../../constants/chunks/deployment-addresses";
 import { Result } from "../../types/result";
@@ -56,6 +56,8 @@ export interface ManagedContracts {
     termManager: ITermManager;
     circuitBreaker: CircuitBreakerModule;
     liquidationManager: ILiquidationManager;
+    /** Per-wallet approved-withdrawal-address allowlist. Untyped ethers Contract — methods accessed via WithdrawalAddressModule. */
+    bitcoinWithdrawalAddressRegistry: Contract;
 }
 /**
  * Contract Manager Module
@@ -108,6 +110,10 @@ export declare class ContractManager {
      * Get Liquidation Manager contract
      */
     getLiquidationManager(): Result<ILiquidationManager, SDKError>;
+    /**
+     * Get the BitcoinWithdrawalAddressRegistry contract (per-wallet approved-address allowlist).
+     */
+    getBitcoinWithdrawalAddressRegistry(): Result<Contract, SDKError>;
     /**
      * Get the provider instance
      */

package/dist/modules/diamond-hands-sdk.d.ts

@@ -11,6 +11,7 @@
  * - Dependency injection pattern
  * - Result-based error handling
  */
+import { type Signer, type TransactionResponse } from "ethers";
 import { Result } from "../types/result";
 import { Satoshis } from "../types/branded/domain-values";
 import { SDKError } from "../utils/error-handler";
@@ -18,6 +19,7 @@ import type { CreateLoanRequest, CreateLoanResult, LoanDataDetail, UCDMintReques
 import type { DiamondHandsSDKConfig } from "../interfaces/chunks/config.i";
 import type { PKPData } from "../interfaces/chunks/pkp-integration.i";
 import { ContractManager } from "./contract/contract-manager.module";
+import { WithdrawalAddressModule } from "./withdrawal-address/withdrawal-address.module";
 import { BitcoinOperations } from "./bitcoin/bitcoin-operations.module";
 import type { SupportedStablecoinData } from "../graphs/diamond-hands";
 type PositionDetailsView = {
@@ -69,6 +71,7 @@ export declare class DiamondHandsSDK {
     private readonly loanCreator;
     private readonly loanQuery;
     private readonly bitcoinOperations;
+    private readonly withdrawalAddressModule;
     private readonly mockTokenManager?;
     private readonly graphClient;
     /**
@@ -370,6 +373,25 @@ export declare class DiamondHandsSDK {
      * @returns Payment result with transaction details
      */
     makePayment(request: PartialPaymentRequest): Promise<PartialPaymentResult>;
+    /**
+     * Access the approved-withdrawal-address allowlist module (self-service
+     * add/remove + reads). The connected wallet manages its OWN addresses; a
+     * newly-added address is only usable after the registry's time-lock delay.
+     */
+    get withdrawalAddresses(): WithdrawalAddressModule;
+    /**
+     * Add a Bitcoin address to the connected wallet's approved-withdrawal allowlist.
+     * Usable only after the registry's delay (default 24h) elapses.
+     */
+    addApprovedWithdrawalAddress(btcAddress: string): Promise<Result<TransactionResponse, SDKError>>;
+    /** Remove a Bitcoin address from the connected wallet's allowlist (immediate). */
+    removeApprovedWithdrawalAddress(btcAddress: string): Promise<Result<TransactionResponse, SDKError>>;
+    /**
+     * Read the connected wallet's (or `user`'s) approved-address entries from the
+     * contract (hashes + timestamps + derived approval state). For human-readable
+     * address strings, query the subgraph `WithdrawalAddressBook`.
+     */
+    getApprovedWithdrawalAddresses(user?: string): Promise<Result<import("./withdrawal-address/withdrawal-address.module").WithdrawalAddressEntry[], SDKError>>;
     /**
      * Withdraw Bitcoin from a position
      *
@@ -650,6 +672,43 @@ export declare class DiamondHandsSDK {
      * @param stablecoinAddress - EVM address of the stablecoin to query.
      */
     getPSMAvailableReserves(stablecoinAddress: string): Promise<bigint>;
+    /**
+     * Execute a PSM stablecoin → UCD swap.
+     * Handles stablecoin approval to the PSM contract if the current allowance is insufficient.
+     *
+     * @param params.stablecoinAddress - ERC-20 address of the stablecoin to swap in
+     * @param params.amountWei - Stablecoin amount in native decimals (bigint)
+     * @param params.minUcdOutWei - Minimum UCD to receive; reverts if below this (1% slippage guard)
+     * @param params.signer - Connected signer for the approval and swap transactions
+     */
+    psmSwap(params: {
+        stablecoinAddress: string;
+        amountWei: bigint;
+        minUcdOutWei: bigint;
+        signer: Signer;
+    }): Promise<{
+        hash: string;
+        blockNumber: number;
+    }>;
+    /**
+     * Execute a PSM UCD → stablecoin redeem.
+     * Handles UCD approval to UCDController (not PSM) to satisfy the M-4 burn allowance guard:
+     * UCDToken.burn(from, amount) calls _spendAllowance(from, msg.sender=ucdController, amount).
+     *
+     * @param params.stablecoinAddress - ERC-20 address of the stablecoin to receive
+     * @param params.ucdAmountWei - UCD amount to redeem (18 decimals, bigint)
+     * @param params.minStablecoinOutWei - Minimum stablecoin to receive (slippage guard)
+     * @param params.signer - Connected signer
+     */
+    psmRedeem(params: {
+        stablecoinAddress: string;
+        ucdAmountWei: bigint;
+        minStablecoinOutWei: bigint;
+        signer: Signer;
+    }): Promise<{
+        hash: string;
+        blockNumber: number;
+    }>;
     /**
      * Wait for the subgraph to index up to (and including) the given block number.
      * Call after on-chain actions (createLoan, mintUCD, etc.) before querying the subgraph.

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

@@ -0,0 +1,78 @@
+/**
+ * Withdrawal Address Module
+ *
+ * Self-service management of a connected wallet's approved Bitcoin withdrawal
+ * destinations (BitcoinWithdrawalAddressRegistry). A user adds an address —
+ * usable only after the registry's time-lock delay (default 24h) — and may
+ * remove it immediately. Withdrawals to non-approved (or still-pending)
+ * addresses are rejected on-chain; this module also powers the SDK's
+ * early-reject so a doomed withdrawal never reaches the Lit Action.
+ *
+ * Display lists (with the original address strings) come from the subgraph —
+ * the contract stores only keccak256(address). This module exposes the
+ * authoritative contract reads (isApproved / hashes / timestamps) and the
+ * mutating txs.
+ */
+import { type TransactionResponse } from "ethers";
+import type { ContractManager } from "../contract/contract-manager.module";
+import { Result } from "../../types/result";
+import { SDKError } from "../../utils/error-handler";
+export interface WithdrawalAddressModuleConfig {
+    contractManager: ContractManager;
+    debug?: boolean;
+}
+/** A single approved-address entry as read from the contract (no raw string — see subgraph for that). */
+export interface WithdrawalAddressEntry {
+    /** keccak256(bytes(normalizedAddress)). */
+    addrHash: string;
+    /** Unix seconds when the address was added (0 if absent). */
+    addedAt: number;
+    /** Unix seconds when the address becomes usable (addedAt-at-add-time + delay). */
+    usableAt: number;
+    /**
+     * Authoritative approval from the contract's own `isApprovedByHash` (chain
+     * `block.timestamp` + CURRENT delay) — NOT derived from the client clock or
+     * the cached `usableAt`, so it stays correct even if the admin changes the
+     * delay after this entry was added.
+     */
+    approved: boolean;
+}
+export declare class WithdrawalAddressModule {
+    private readonly config;
+    constructor(config: WithdrawalAddressModuleConfig);
+    /** Resolve the registry contract, or fail if it isn't configured for this network. */
+    private getRegistry;
+    /** True iff the registry is wired for this network (enforcement is active). */
+    isConfigured(): boolean;
+    /** keccak256 of the canonicalized address — matches the on-chain key. */
+    static addressHash(btcAddress: string): string;
+    /**
+     * Add a Bitcoin address to the caller's allowlist. It becomes usable only
+     * after the registry's delay elapses. Returns the submitted tx.
+     */
+    addAddress(btcAddress: string): Promise<Result<TransactionResponse, SDKError>>;
+    /** Remove a Bitcoin address from the caller's allowlist (effective immediately). */
+    removeAddress(btcAddress: string): Promise<Result<TransactionResponse, SDKError>>;
+    /**
+     * Authoritative contract read: is `btcAddress` approved (present AND past its
+     * delay) for `user`?
+     */
+    isApproved(user: string, btcAddress: string): Promise<Result<boolean, SDKError>>;
+    /**
+     * Read the user's allowlist from the contract: hashes + timestamps + derived
+     * approval state. NOTE: the raw address strings are NOT on-chain — use the
+     * subgraph (WithdrawalAddressBook) to render human-readable addresses.
+     */
+    getEntries(user: string): Promise<Result<WithdrawalAddressEntry[], SDKError>>;
+    /** The current global delay (seconds) before a newly-added address is usable. */
+    getAddressDelay(): Promise<Result<number, SDKError>>;
+    /**
+     * Early-reject guard used by `withdrawBTC`. Resolves to a typed error if the
+     * destination is not approved for `borrower`. When the registry is not
+     * configured for the network, this is a no-op (the on-chain gate remains the
+     * hard guarantee).
+     */
+    assertApprovedForWithdrawal(borrower: string, btcAddress: string): Promise<Result<void, SDKError>>;
+    private txFailure;
+}
+export declare function createWithdrawalAddressModule(config: WithdrawalAddressModuleConfig): WithdrawalAddressModule;

package/dist/utils/address-conversion.utils.d.ts

@@ -30,6 +30,18 @@ export declare function safeGetBitcoinAddressesFromPkp(pkpId: string, maxRetries
  * @throws Clear error message if validation fails
  */
 export declare function safeValidateBitcoinAddress(address: string, network?: 'mainnet' | 'testnet' | 'regtest'): string;
+/**
+ * Canonicalize a Bitcoin address so that the SAME string is used on both the
+ * approve path (registry.addAddress) and the withdraw path. The on-chain
+ * allowlist is keyed by keccak256(bytes(address)), so the two strings MUST
+ * byte-match. Bech32 (bc1/tb1/bcrt1) is lower-case canonical, so we lower-case
+ * it; Base58 (1.../3.../m.../n.../2...) is case-sensitive and is returned
+ * unchanged.
+ *
+ * @param address Bitcoin address to canonicalize
+ * @returns The canonical form to store/compare
+ */
+export declare function normalizeBitcoinAddress(address: string): string;
 /**
  * Safely parse and validate a position ID
  * @param positionId Position ID to validate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gvnrdao/dh-sdk",
-  "version": "0.0.274",
+  "version": "0.0.276",
   "description": "TypeScript SDK for Diamond Hands Protocol - Bitcoin-backed lending with LIT Protocol PKPs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -81,10 +81,10 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@gvnrdao/dh-lit-actions": "^0.0.306",
-    "@gvnrdao/dh-lit-ops": "^0.0.293",
+    "@gvnrdao/dh-lit-actions": "^0.0.307",
+    "@gvnrdao/dh-lit-ops": "^0.0.294",
     "@noble/hashes": "^1.5.0",
-    "axios": "^1.15.2",
+    "axios": "^1.17.0",
     "bech32": "^2.0.0",
     "bip66": "^2.0.0",
     "bitcoinjs-lib": "^6.1.0",
@@ -98,7 +98,7 @@
     "viem": "^2.48.4"
   },
   "devDependencies": {
-    "@babel/preset-env": "7.29.0",
+    "@babel/preset-env": "7.29.7",
     "@safe-global/protocol-kit": "^7.1.0",
     "@types/crypto-js": "^4.2.2",
     "@types/jest": "^29.0.0",