@gvnrdao/dh-sdk 0.0.274 → 0.0.276

package/dist/index.mjs

@@ -3677,7 +3677,8 @@ var init_deployment_addresses = __esm({
         mockUsdcToken: "0x96409A98e0D322d6566b7F44a0fAbD1BD4ce2AEc",
         mockUsdtToken: "0xF8b7fB38b17a310960E47805Be9adba0b0e0394D",
         PositionDelegateRegistry: "0x482369De283622E7b05731875ec137d4E3D208F9",
-        FeeRecipientRegistry: "0x95795F8403DDb629E8527B2934C4e71f5fC0C374"
+        FeeRecipientRegistry: "0x95795F8403DDb629E8527B2934C4e71f5fC0C374",
+        BitcoinWithdrawalAddressRegistry: "0x6376D392097F0A81e51BD83960A97EA20eaf1dbe"
       },
       upgraded: {
         PositionManager: {
@@ -3688,11 +3689,11 @@ var init_deployment_addresses = __esm({
           reason: "Shared upgrade script: PositionManager implementation update"
         },
         LoanOperationsManagerModule: {
-          previousImplementation: "0x291B412c573a4F52410f09D7Ba82eead17D9a674",
-          newImplementation: "0x9DA8d69d7BcF9Fa3ba5734580e8C32618aB52D36",
-          upgradedAt: "2026-05-17T20:02:12.883Z",
+          previousImplementation: "0x9DA8d69d7BcF9Fa3ba5734580e8C32618aB52D36",
+          newImplementation: "0x8c20e9Edf44146718F2EF15eEF47A201CaC229B8",
+          upgradedAt: "2026-06-05T10:52:25.179Z",
           upgradedBy: "0xF20986F02420EF443AE9BE5092FB8A4975cF3aA6",
-          reason: "Shared upgrade script: LoanOperationsManagerModule implementation update"
+          reason: "audit #3 v1.6.0: LoanOperationsManagerModule \u2014 Chainlink feed-staleness gate (maxBtcFeedAgeBorrow / maxBtcFeedAgeLiquidation)"
         },
         UCDController: {
           previousImplementation: "0x30d0458bE846f4C5D231242eB5a9e9Db68e7232F",
@@ -3751,9 +3752,9 @@ var init_deployment_addresses = __esm({
           reason: "Shared upgrade script: PositionManagerCoreModule implementation update"
         },
         CollateralManagerModule: {
-          previousImplementation: "0x428982fCC9A0455c56881B8e21C96B220CC1506B",
-          newImplementation: "0x124e61aBff60CC70c4B81ab3019A8A7D35B412d4",
-          upgradedAt: "2026-05-17T19:17:01.129Z",
+          previousImplementation: "0x124e61aBff60CC70c4B81ab3019A8A7D35B412d4",
+          newImplementation: "0xd47FE9126daE9A1e0fFdaCf539BE7345D3642bcb",
+          upgradedAt: "2026-06-05T09:14:12.892Z",
           upgradedBy: "0xF20986F02420EF443AE9BE5092FB8A4975cF3aA6",
           reason: "Shared upgrade script: CollateralManagerModule implementation update"
         },
@@ -3897,7 +3898,7 @@ var init_deployment_addresses = __esm({
         CIRCUIT_BREAKER_MODULE: "0x3D0B2cAE481821E57BA9CC3807bCC0d0D7F18bd8",
         ADMIN_MODULE: "0xAcd1f07915b17CA3727e7fE89BdF618A1545a1ed",
         UCD_CONTROLLER_IMPL: "0x30d0458bE846f4C5D231242eB5a9e9Db68e7232F",
-        LOAN_OPERATIONS_MANAGER_MODULE_IMPL: "0x9DA8d69d7BcF9Fa3ba5734580e8C32618aB52D36",
+        LOAN_OPERATIONS_MANAGER_MODULE_IMPL: "0x8c20e9Edf44146718F2EF15eEF47A201CaC229B8",
         TERM_MANAGER_MODULE_IMPL: "0x358d6A7A864853beAA3E157fEB83dCEb1628E8eB",
         CIRCUIT_BREAKER_MODULE_IMPL: "0xF6277dEF72D51312CC99616B5380f34Eb7603D75",
         ADMIN_MODULE_IMPL: "0xBBA86246169f81a307Fafff02C1e3D8456aab973",
@@ -3929,7 +3930,9 @@ var init_deployment_addresses = __esm({
         AGENT_MODULE: "0xefb8C29C1e7e92ed7d81a52dbedaed74e37fe380",
         FEE_RECIPIENT_REGISTRY: "0x95795F8403DDb629E8527B2934C4e71f5fC0C374",
         FEE_RECIPIENT_REGISTRY_IMPL: "0xd08513a7cB2dd354B26cDDf549616F12054c34c9",
-        OPERATION_AUTHORIZATION_REGISTRY_IMPL: "0x9f8072d4672d643e39d8638478e900Fea1f2c81D"
+        OPERATION_AUTHORIZATION_REGISTRY_IMPL: "0x9f8072d4672d643e39d8638478e900Fea1f2c81D",
+        BITCOIN_WITHDRAWAL_ADDRESS_REGISTRY: "0x6376D392097F0A81e51BD83960A97EA20eaf1dbe",
+        BITCOIN_WITHDRAWAL_ADDRESS_REGISTRY_IMPL: "0xFF270BC4470dBA80430Bd1a3a66EB691599354fA"
       }
     };
     SEPOLIA_CONTRACTS = {
@@ -3956,7 +3959,8 @@ var init_deployment_addresses = __esm({
       mockUsdcToken: "0x96409A98e0D322d6566b7F44a0fAbD1BD4ce2AEc",
       mockUsdtToken: "0xF8b7fB38b17a310960E47805Be9adba0b0e0394D",
       PositionDelegateRegistry: "0x482369De283622E7b05731875ec137d4E3D208F9",
-      FeeRecipientRegistry: "0x95795F8403DDb629E8527B2934C4e71f5fC0C374"
+      FeeRecipientRegistry: "0x95795F8403DDb629E8527B2934C4e71f5fC0C374",
+      BitcoinWithdrawalAddressRegistry: "0x6376D392097F0A81e51BD83960A97EA20eaf1dbe"
     };
     LOCALHOST_DEPLOYMENT = {
       network: "localhost",
@@ -7272,7 +7276,7 @@ var require_abstract_coder = __commonJS({
     function toObject2(names2, items, deep) {
       if (names2.indexOf(null) >= 0) {
         return items.map((item, index) => {
-          if (item instanceof Result10) {
+          if (item instanceof Result11) {
             return toObject2(getNames2(item), item, deep);
           }
           return item;
@@ -7281,7 +7285,7 @@ var require_abstract_coder = __commonJS({
       return names2.reduce((accum, name, index) => {
         let item = items.getValue(name);
         if (!(name in accum)) {
-          if (deep && item instanceof Result10) {
+          if (deep && item instanceof Result11) {
             item = toObject2(getNames2(item), item, deep);
           }
           accum[name] = item;
@@ -7289,7 +7293,7 @@ var require_abstract_coder = __commonJS({
         return accum;
       }, {});
     }
-    var Result10 = class _Result extends Array {
+    var Result11 = class _Result extends Array {
       // No longer used; but cannot be removed as it will remove the
       // #private field from the .d.ts which may break backwards
       // compatibility
@@ -7493,7 +7497,7 @@ var require_abstract_coder = __commonJS({
         return new _Result(_guard5, items, keys);
       }
     };
-    exports2.Result = Result10;
+    exports2.Result = Result11;
     function checkResultErrors2(result) {
       const errors2 = [];
       const checkErrors = function(path2, object2) {
@@ -20184,9 +20188,9 @@ var require_contract = __commonJS({
     function _ContractBase2() {
       return BaseContract2;
     }
-    var Contract2 = class extends _ContractBase2() {
+    var Contract3 = class extends _ContractBase2() {
     };
-    exports2.Contract = Contract2;
+    exports2.Contract = Contract3;
   }
 });
 
@@ -31451,17 +31455,17 @@ var require_pkg_src = __commonJS({
         }
       },
       btcWithdrawal: {
-        cid: "QmbsmTg6RuE6SGUkXqkcXSaWy99ydUtyLoFCBxiHuqpSKC",
+        cid: "QmNqErzpgDUair9bPK7oPQczjKjRcsmcej37izponrEcqp",
         authorizedCidHex: cidToHex(
-          "QmbsmTg6RuE6SGUkXqkcXSaWy99ydUtyLoFCBxiHuqpSKC"
+          "QmNqErzpgDUair9bPK7oPQczjKjRcsmcej37izponrEcqp"
         ),
         name: "Btc Withdrawal",
         description: "Production Btc Withdrawal",
         version: "1.0.0",
         deployed: true,
-        deployedAt: 1780400560069,
-        size: 74485,
-        hash: "dc62aa5f52c8ad3c86f8c99f9f08519d036e716554682ccb1f7227ca969df118",
+        deployedAt: 1780651980768,
+        size: 75137,
+        hash: "368f9aea32cf2e660b0f75b88b6ee043cf5956319d7b3c6c695d4b984b3bd555",
         validatorWalletAddress: "0xbb137fbda353199e9419b698c57a742124d4987d",
         pkp: {
           publicKey: "0x043616787c5432415c24378c4ef48de2bcd6bb7b575b837e3cff09171802662da7105d79586c7659677a0ecbaddac4cce06cb2a11f69a16fa0c4d7002ac7d51a4d",
@@ -32334,7 +32338,7 @@ ${errorReport}`);
     }
     init_debug_logger();
     init_session_signature_cache();
-    var import_ethers13 = require_lib2();
+    var import_ethers14 = require_lib2();
     var EXPIRED_LOAN_MIN_LIQUIDATION_THRESHOLD_BPS = 11e3;
     var GRACE_PERIOD_DAYS = 30;
     var SATOSHIS_PER_BITCOIN = 100000000n;
@@ -34486,12 +34490,12 @@ ${errorReport}`);
     }
     async function executeVaultSnapshot(params) {
       global.ethers = {
-        ...import_ethers13.ethers,
+        ...import_ethers14.ethers,
         providers: {
-          StaticJsonRpcProvider: import_ethers13.ethers.JsonRpcProvider
+          StaticJsonRpcProvider: import_ethers14.ethers.JsonRpcProvider
         },
-        Contract: import_ethers13.ethers.Contract,
-        utils: import_ethers13.ethers
+        Contract: import_ethers14.ethers.Contract,
+        utils: import_ethers14.ethers
         // v6 moved utils to top level
       };
       global.Lit = {
@@ -34759,7 +34763,8 @@ function getSepoliaConfig() {
       bitcoinProviderRegistry: SEPOLIA_CONTRACTS.BitcoinProviderRegistry || "",
       contractVersionRegistry: SEPOLIA_CONTRACTS.ContractVersionRegistry || "",
       feeRecipientRegistry: SEPOLIA_CONTRACTS.FeeRecipientRegistry || "",
-      positionDelegateRegistry: SEPOLIA_CONTRACTS.PositionDelegateRegistry || ""
+      positionDelegateRegistry: SEPOLIA_CONTRACTS.PositionDelegateRegistry || "",
+      bitcoinWithdrawalAddressRegistry: SEPOLIA_CONTRACTS.BitcoinWithdrawalAddressRegistry || ""
     },
     subgraphs: {
       // Lazy getter for the same module-init snapshot reason as serviceEndpoint.
@@ -37203,9 +37208,9 @@ var require_ToPrimitive = __commonJS({
   }
 });
 
-// node_modules/es-abstract/2024/ToString.js
+// node_modules/es-abstract/2025/ToString.js
 var require_ToString = __commonJS({
-  "node_modules/es-abstract/2024/ToString.js"(exports2, module2) {
+  "node_modules/es-abstract/2025/ToString.js"(exports2, module2) {
     "use strict";
     var GetIntrinsic = require_get_intrinsic();
     var $String = GetIntrinsic("%String%");
@@ -37226,13 +37231,20 @@ var require_implementation3 = __commonJS({
     var RequireObjectCoercible = require_RequireObjectCoercible();
     var ToString = require_ToString();
     var callBound = require_call_bound();
+    var safeRegexTester = require_safe_regex_test();
     var $replace = callBound("String.prototype.replace");
+    var $charAt = callBound("String.prototype.charAt");
+    var $slice = callBound("String.prototype.slice");
     var mvsIsWS = /^\s$/.test("\u180E");
     var leftWhitespace = mvsIsWS ? /^[\x09\x0A\x0B\x0C\x0D\x20\xA0\u1680\u180E\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200A\u202F\u205F\u3000\u2028\u2029\uFEFF]+/ : /^[\x09\x0A\x0B\x0C\x0D\x20\xA0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200A\u202F\u205F\u3000\u2028\u2029\uFEFF]+/;
-    var rightWhitespace = mvsIsWS ? /[\x09\x0A\x0B\x0C\x0D\x20\xA0\u1680\u180E\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200A\u202F\u205F\u3000\u2028\u2029\uFEFF]+$/ : /[\x09\x0A\x0B\x0C\x0D\x20\xA0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200A\u202F\u205F\u3000\u2028\u2029\uFEFF]+$/;
+    var isWhitespace = safeRegexTester(mvsIsWS ? /[\x09\x0A\x0B\x0C\x0D\x20\xA0\u1680\u180E\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200A\u202F\u205F\u3000\u2028\u2029\uFEFF]$/ : /[\x09\x0A\x0B\x0C\x0D\x20\xA0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200A\u202F\u205F\u3000\u2028\u2029\uFEFF]$/);
     module2.exports = function trim() {
-      var S = ToString(RequireObjectCoercible(this));
-      return $replace($replace(S, leftWhitespace, ""), rightWhitespace, "");
+      var S = $replace(ToString(RequireObjectCoercible(this)), leftWhitespace, "");
+      var end = S.length;
+      while (end > 0 && isWhitespace($charAt(S, end - 1))) {
+        end -= 1;
+      }
+      return $slice(S, 0, end);
     };
   }
 });
@@ -37485,6 +37497,22 @@ var require_ToObject = __commonJS({
   }
 });
 
+// node_modules/es-abstract/2024/ToString.js
+var require_ToString2 = __commonJS({
+  "node_modules/es-abstract/2024/ToString.js"(exports2, module2) {
+    "use strict";
+    var GetIntrinsic = require_get_intrinsic();
+    var $String = GetIntrinsic("%String%");
+    var $TypeError = require_type();
+    module2.exports = function ToString(argument) {
+      if (typeof argument === "symbol") {
+        throw new $TypeError("Cannot convert a Symbol value to a string");
+      }
+      return $String(argument);
+    };
+  }
+});
+
 // node_modules/array.prototype.findindex/implementation.js
 var require_implementation4 = __commonJS({
   "node_modules/array.prototype.findindex/implementation.js"(exports2, module2) {
@@ -37495,7 +37523,7 @@ var require_implementation4 = __commonJS({
     var LengthOfArrayLike = require_LengthOfArrayLike();
     var ToBoolean = require_ToBoolean();
     var ToObject = require_ToObject();
-    var ToString = require_ToString();
+    var ToString = require_ToString2();
     module2.exports = function findIndex(predicate) {
       var O = ToObject(this);
       var len = LengthOfArrayLike(O);
@@ -94255,6 +94283,13 @@ var ZeroAddress = "0x0000000000000000000000000000000000000000";
 // node_modules/ethers/lib.esm/constants/hashes.js
 var ZeroHash = "0x0000000000000000000000000000000000000000000000000000000000000000";
 
+// node_modules/ethers/lib.esm/constants/numbers.js
+var N = BigInt("0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141");
+var WeiPerEther = BigInt("1000000000000000000");
+var MaxUint256 = BigInt("0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff");
+var MinInt256 = BigInt("0x8000000000000000000000000000000000000000000000000000000000000000") * BigInt(-1);
+var MaxInt256 = BigInt("0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff");
+
 // node_modules/ethers/lib.esm/crypto/signature.js
 var BN_04 = BigInt(0);
 var BN_13 = BigInt(1);
@@ -108788,6 +108823,15 @@ function safeValidateBitcoinAddress(address, network = "regtest") {
   }
   return address;
 }
+function normalizeBitcoinAddress(address) {
+  if (!address || typeof address !== "string")
+    return address;
+  const trimmed = address.trim();
+  if (/^(bc1|tb1|bcrt1)/i.test(trimmed)) {
+    return trimmed.toLowerCase();
+  }
+  return trimmed;
+}
 
 // src/protocol/protocol-pause.ts
 var GET_PROTOCOL_PAUSE_STATUS_ABI = [
@@ -108979,6 +109023,21 @@ var LIQUIDATION_MANAGER_ABI = [
   "function canLiquidate(bytes32 positionId) external view returns (bool)",
   "function vrfSeeds(bytes32 positionId) external view returns (uint256)"
 ];
+var BITCOIN_WITHDRAWAL_ADDRESS_REGISTRY_ABI = [
+  "function addAddress(string btcAddress) external",
+  "function removeAddress(string btcAddress) external",
+  "function removeAddressByHash(bytes32 addrHash) external",
+  "function isApproved(address user, string btcAddress) external view returns (bool)",
+  "function isApprovedByHash(address user, bytes32 addrHash) external view returns (bool)",
+  "function isPresent(address user, bytes32 addrHash) external view returns (bool)",
+  "function getAddedAt(address user, bytes32 addrHash) external view returns (uint64)",
+  "function getUsableAt(address user, bytes32 addrHash) external view returns (uint256)",
+  "function getAddressHashes(address user) external view returns (bytes32[])",
+  "function addressCount(address user) external view returns (uint256)",
+  "function addressDelay() external view returns (uint256)",
+  "event AddressAdded(address indexed user, bytes32 indexed addrHash, string btcAddress, uint64 addedAt, uint256 usableAt)",
+  "event AddressRemoved(address indexed user, bytes32 indexed addrHash, string btcAddress)"
+];
 var ContractManager = class {
   config;
   contracts = null;
@@ -109039,6 +109098,11 @@ var ContractManager = class {
           contractAddresses.liquidationManager || ZeroAddress,
           LIQUIDATION_MANAGER_ABI,
           contractRunner
+        ),
+        bitcoinWithdrawalAddressRegistry: new Contract(
+          contractAddresses.bitcoinWithdrawalAddressRegistry || ZeroAddress,
+          BITCOIN_WITHDRAWAL_ADDRESS_REGISTRY_ABI,
+          contractRunner
         )
       };
       this.contracts = contracts;
@@ -109069,7 +109133,16 @@ var ContractManager = class {
       "loanOperationsManager",
       "termManager",
       "circuitBreaker",
-      "liquidationManager"
+      "liquidationManager",
+      // INTENTIONALLY OPTIONAL — do not promote to requiredAddresses.
+      // The on-chain CollateralManager gate is inert while its registry is
+      // address(0) (staged rollout), so pre-v1.3 deployments, browser/default
+      // configs, and tests legitimately omit this address. The SDK's layer-1
+      // early-reject (WithdrawalAddressModule.assertApprovedForWithdrawal)
+      // already no-ops via isConfigured() when the address is absent/ZeroAddress,
+      // and the contract instance defaults to ZeroAddress. Making this required
+      // would throw at init for every config that hasn't deployed the registry.
+      "bitcoinWithdrawalAddressRegistry"
     ];
     const missing = [];
     const invalid = [];
@@ -109182,6 +109255,16 @@ var ContractManager = class {
     }
     return success(contractsResult.value.liquidationManager);
   }
+  /**
+   * Get the BitcoinWithdrawalAddressRegistry contract (per-wallet approved-address allowlist).
+   */
+  getBitcoinWithdrawalAddressRegistry() {
+    const contractsResult = this.getContracts();
+    if (!contractsResult.success) {
+      return contractsResult;
+    }
+    return success(contractsResult.value.bitcoinWithdrawalAddressRegistry);
+  }
   /**
    * Get the provider instance
    */
@@ -111271,6 +111354,168 @@ function createLoanQuery(config) {
   }
 }
 
+// src/modules/withdrawal-address/withdrawal-address.module.ts
+var WithdrawalAddressModule = class {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  /** Resolve the registry contract, or fail if it isn't configured for this network. */
+  getRegistry() {
+    const res = this.config.contractManager.getBitcoinWithdrawalAddressRegistry();
+    if (!res.success)
+      return res;
+    const target = res.value.target;
+    if (!target || target === ZeroAddress) {
+      return failure(
+        new SDKError({
+          code: "SDK_WITHDRAWAL_REGISTRY_NOT_CONFIGURED",
+          message: "BitcoinWithdrawalAddressRegistry address is not configured for this network",
+          category: "CONFIGURATION" /* CONFIGURATION */,
+          severity: "MEDIUM" /* MEDIUM */
+        })
+      );
+    }
+    return success(res.value);
+  }
+  /** True iff the registry is wired for this network (enforcement is active). */
+  isConfigured() {
+    return this.getRegistry().success;
+  }
+  /** keccak256 of the canonicalized address — matches the on-chain key. */
+  static addressHash(btcAddress) {
+    return keccak256(toUtf8Bytes(normalizeBitcoinAddress(btcAddress)));
+  }
+  /**
+   * Add a Bitcoin address to the caller's allowlist. It becomes usable only
+   * after the registry's delay elapses. Returns the submitted tx.
+   */
+  async addAddress(btcAddress) {
+    const reg = this.getRegistry();
+    if (!reg.success)
+      return reg;
+    try {
+      const tx = await reg.value.addAddress(
+        normalizeBitcoinAddress(btcAddress)
+      );
+      return success(tx);
+    } catch (error2) {
+      return this.txFailure("addAddress", error2, btcAddress);
+    }
+  }
+  /** Remove a Bitcoin address from the caller's allowlist (effective immediately). */
+  async removeAddress(btcAddress) {
+    const reg = this.getRegistry();
+    if (!reg.success)
+      return reg;
+    try {
+      const tx = await reg.value.removeAddress(
+        normalizeBitcoinAddress(btcAddress)
+      );
+      return success(tx);
+    } catch (error2) {
+      return this.txFailure("removeAddress", error2, btcAddress);
+    }
+  }
+  /**
+   * Authoritative contract read: is `btcAddress` approved (present AND past its
+   * delay) for `user`?
+   */
+  async isApproved(user, btcAddress) {
+    const reg = this.getRegistry();
+    if (!reg.success)
+      return reg;
+    try {
+      const ok = await reg.value.isApproved(
+        user,
+        normalizeBitcoinAddress(btcAddress)
+      );
+      return success(ok);
+    } catch (error2) {
+      return this.txFailure("isApproved", error2, btcAddress);
+    }
+  }
+  /**
+   * 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.
+   */
+  async getEntries(user) {
+    const reg = this.getRegistry();
+    if (!reg.success)
+      return reg;
+    try {
+      const hashes = await reg.value.getAddressHashes(user);
+      const entries = [];
+      for (const addrHash of hashes) {
+        const addedAt = Number(await reg.value.getAddedAt(user, addrHash));
+        const usableAt = Number(await reg.value.getUsableAt(user, addrHash));
+        const approved = await reg.value.isApprovedByHash(
+          user,
+          addrHash
+        );
+        entries.push({ addrHash, addedAt, usableAt, approved });
+      }
+      return success(entries);
+    } catch (error2) {
+      return this.txFailure("getEntries", error2, user);
+    }
+  }
+  /** The current global delay (seconds) before a newly-added address is usable. */
+  async getAddressDelay() {
+    const reg = this.getRegistry();
+    if (!reg.success)
+      return reg;
+    try {
+      const delay = await reg.value.addressDelay();
+      return success(Number(delay));
+    } catch (error2) {
+      return this.txFailure("addressDelay", error2, "");
+    }
+  }
+  /**
+   * 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).
+   */
+  async assertApprovedForWithdrawal(borrower, btcAddress) {
+    if (!this.isConfigured())
+      return success(void 0);
+    const res = await this.isApproved(borrower, btcAddress);
+    if (!res.success)
+      return res;
+    if (!res.value) {
+      return failure(
+        new SDKError({
+          code: "SDK_WITHDRAWAL_ADDRESS_NOT_APPROVED",
+          message: `Bitcoin address ${btcAddress} is not an approved withdrawal destination for ${borrower} (not on the allowlist, or its time-lock has not elapsed). Add it and wait for the delay first.`,
+          category: "VALIDATION" /* VALIDATION */,
+          severity: "MEDIUM" /* MEDIUM */,
+          context: { borrower, btcAddress }
+        })
+      );
+    }
+    return success(void 0);
+  }
+  txFailure(op, error2, context) {
+    const msg = error2 instanceof Error ? error2.message : String(error2);
+    return failure(
+      new SDKError({
+        code: `SDK_WITHDRAWAL_REGISTRY_${op.toUpperCase()}_FAILED`,
+        message: `WithdrawalAddressRegistry.${op} failed: ${msg}`,
+        category: "CONTRACT" /* CONTRACT */,
+        severity: "MEDIUM" /* MEDIUM */,
+        originalError: error2 instanceof Error ? error2 : new Error(String(error2)),
+        context: { op, context }
+      })
+    );
+  }
+};
+function createWithdrawalAddressModule(config) {
+  return new WithdrawalAddressModule(config);
+}
+
 // src/types/branded/domain-values.ts
 var UCD_BRAND = Symbol.for("diamond-hands.UCD");
 var SATOSHIS_BRAND = Symbol.for("diamond-hands.Satoshis");
@@ -117103,6 +117348,7 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
   loanCreator;
   loanQuery;
   bitcoinOperations;
+  withdrawalAddressModule;
   mockTokenManager;
   graphClient;
   /**
@@ -117286,6 +117532,10 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
       );
     }
     this.contractManager = contractManagerResult.value;
+    this.withdrawalAddressModule = createWithdrawalAddressModule({
+      contractManager: this.contractManager,
+      debug: config.debug
+    });
     this.litOps = new LitOps({
       mode: config.mode || "standalone",
       network: config.litNetwork || DEFAULT_LIT_NETWORK,
@@ -117360,6 +117610,11 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
       );
     }
     const graphHeaders = !serviceMode && config.graphApiKey ? { Authorization: `Bearer ${config.graphApiKey}` } : void 0;
+    if (graphHeaders && typeof window !== "undefined" && typeof window.document !== "undefined") {
+      log.warn(
+        "graphApiKey is being used in standalone mode inside a browser \u2014 the key will be exposed to end users. Use service mode (serviceEndpoint + session auth) for any user-facing app so GRAPH_API_KEY stays server-side."
+      );
+    }
     this.graphClient = new DiamondHandsGraph(
       {
         endpoint: graphEndpoint,
@@ -118171,7 +118426,7 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
           );
         }
         const chain = this.config.chain || (Number(network2.chainId) === 1 ? "ethereum" : "sepolia");
-        const devBitcoinProviderUrl = void 0;
+        const devBitcoinProviderUrl = request.customBitcoinRpcUrl || this.config.bitcoinProviders?.[0]?.url;
         if (this.config.debug) {
           log.info(`   Network: ${chain} (chainId: ${network2.chainId})`);
         }
@@ -118217,7 +118472,17 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
               contractAddresses: contracts
             },
             userSignature: auth.signature,
-            ...devBitcoinProviderUrl ? { devBitcoinProviderUrl } : {},
+            // lit-ops reads `bitcoinProviderUrl` (request field) and maps it to the
+            // validator's `devBitcoinProviderUrl` jsParam on Hardhat.
+            ...devBitcoinProviderUrl ? { bitcoinProviderUrl: devBitcoinProviderUrl } : {},
+            // Optional override of the mint validator PKP/wallet (e.g. an on-chain-multisig-authorized
+            // validator) — applied to a local copy in lit-ops, never mutating the registry singleton.
+            // When set, authorization is by the on-chain ACTION CID, so the posted code must stay
+            // byte-identical to the registry code (no cache-bust nonce) or the derived CID won't match.
+            ...this.config.mintValidatorOverride ? {
+              validatorOverride: this.config.mintValidatorOverride,
+              disableCacheBust: true
+            } : {},
             rpcUrl: request.rpcUrl || this.config.ethRpcUrl,
             // Pass RPC URL to LIT Action (ngrok for Hardhat)
             ...request.debugOverrides && {
@@ -121233,6 +121498,40 @@ Error data: ${errorData || "none"}`
       this.releaseWriteLock(request.positionId);
     }
   }
+  /**
+   * 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() {
+    return this.withdrawalAddressModule;
+  }
+  /**
+   * Add a Bitcoin address to the connected wallet's approved-withdrawal allowlist.
+   * Usable only after the registry's delay (default 24h) elapses.
+   */
+  async addApprovedWithdrawalAddress(btcAddress) {
+    return this.withdrawalAddressModule.addAddress(btcAddress);
+  }
+  /** Remove a Bitcoin address from the connected wallet's allowlist (immediate). */
+  async removeApprovedWithdrawalAddress(btcAddress) {
+    return this.withdrawalAddressModule.removeAddress(btcAddress);
+  }
+  /**
+   * 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`.
+   */
+  async getApprovedWithdrawalAddresses(user) {
+    let target = user;
+    if (!target) {
+      const signerRes = this.contractManager.getSigner();
+      if (!signerRes.success)
+        return signerRes;
+      target = await signerRes.value.getAddress();
+    }
+    return this.withdrawalAddressModule.getEntries(target);
+  }
   /**
    * Withdraw Bitcoin from a position
    *
@@ -121317,6 +121616,48 @@ Error data: ${errorData || "none"}`
         if (this.config.debug) {
           log.info(`   Position PKP ID: ${position.pkpId}`);
         }
+        if (this.withdrawalAddressModule.isConfigured()) {
+          const rawStatus = position.status;
+          const isLiquidated = Number(rawStatus) === 5 || String(rawStatus).toUpperCase() === "LIQUIDATED";
+          let controller;
+          if (isLiquidated) {
+            const litValidatorAddr = this.getContractAddressesOrThrow().litActionValidator;
+            const pkpId = position.pkpId;
+            if (litValidatorAddr && pkpId) {
+              try {
+                const litValidator = new Contract(
+                  litValidatorAddr,
+                  ["function pkpOwners(bytes32) view returns (address)"],
+                  this.getProviderOrThrow()
+                );
+                const owner = await litValidator.pkpOwners(
+                  pkpId
+                );
+                if (owner && owner !== ZeroAddress) {
+                  controller = owner;
+                }
+              } catch {
+              }
+            }
+          } else {
+            controller = position.borrower;
+            if (!controller) {
+              const signerRes = this.contractManager.getSigner();
+              if (signerRes.success) {
+                controller = await signerRes.value.getAddress();
+              }
+            }
+          }
+          if (controller) {
+            const approval = await this.withdrawalAddressModule.assertApprovedForWithdrawal(
+              controller,
+              withdrawalAddress.trim()
+            );
+            if (!approval.success) {
+              return { success: false, error: approval.error.message };
+            }
+          }
+        }
         let pkpPublicKey;
         let pkpEthAddress;
         const pkpCache = this.cacheManager.getCache("pkp-data", {
@@ -122631,6 +122972,78 @@ Error data: ${errorData || "none"}`
     );
     return psm.getAvailableReserves(stablecoinAddress);
   }
+  /**
+   * 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
+   */
+  async psmSwap(params) {
+    const psmAddress = this.config.contractAddresses?.simplePsmV2;
+    if (!psmAddress) {
+      throw new Error(
+        "SimplePSMV2 address not configured \u2014 provide contractAddresses.simplePsmV2"
+      );
+    }
+    const signerAddress = await params.signer.getAddress();
+    const erc20Abi = [
+      "function allowance(address owner, address spender) view returns (uint256)",
+      "function approve(address spender, uint256 amount) returns (bool)"
+    ];
+    const stablecoin = new Contract(params.stablecoinAddress, erc20Abi, params.signer);
+    const allowance = await stablecoin.allowance(signerAddress, psmAddress);
+    if (allowance < params.amountWei) {
+      const approveTx = await stablecoin.approve(psmAddress, MaxUint256);
+      await approveTx.wait();
+    }
+    const psm = SimplePSMV2__factory.connect(psmAddress, params.signer);
+    const tx = await psm.swap(params.stablecoinAddress, params.amountWei, params.minUcdOutWei);
+    const receipt = await tx.wait();
+    if (!receipt)
+      throw new Error("PSM swap transaction receipt unavailable");
+    return { hash: tx.hash, blockNumber: receipt.blockNumber };
+  }
+  /**
+   * 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
+   */
+  async psmRedeem(params) {
+    const psmAddress = this.config.contractAddresses?.simplePsmV2;
+    const ucdAddress = this.config.contractAddresses?.ucdToken;
+    const ucdControllerAddress = this.config.contractAddresses?.ucdController;
+    if (!psmAddress)
+      throw new Error("SimplePSMV2 address not configured \u2014 provide contractAddresses.simplePsmV2");
+    if (!ucdAddress)
+      throw new Error("UCDToken address not configured \u2014 provide contractAddresses.ucdToken");
+    if (!ucdControllerAddress)
+      throw new Error("UCDController address not configured \u2014 provide contractAddresses.ucdController");
+    const signerAddress = await params.signer.getAddress();
+    const erc20Abi = [
+      "function allowance(address owner, address spender) view returns (uint256)",
+      "function approve(address spender, uint256 amount) returns (bool)"
+    ];
+    const ucdToken = new Contract(ucdAddress, erc20Abi, params.signer);
+    const allowance = await ucdToken.allowance(signerAddress, ucdControllerAddress);
+    if (allowance < params.ucdAmountWei) {
+      const approveTx = await ucdToken.approve(ucdControllerAddress, MaxUint256);
+      await approveTx.wait();
+    }
+    const psm = SimplePSMV2__factory.connect(psmAddress, params.signer);
+    const tx = await psm.redeem(params.stablecoinAddress, params.ucdAmountWei, params.minStablecoinOutWei);
+    const receipt = await tx.wait();
+    if (!receipt)
+      throw new Error("PSM redeem transaction receipt unavailable");
+    return { hash: tx.hash, blockNumber: receipt.blockNumber };
+  }
   /**
    * 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.
@@ -123819,6 +124232,7 @@ export {
   UCDConversions,
   VALID_LIT_NETWORKS,
   WeiConversions,
+  WithdrawalAddressModule,
   andThen,
   assertProtocolNotPaused,
   assertSafeServiceEndpoint,
@@ -123833,6 +124247,7 @@ export {
   createLoanQuery,
   createMockTokenManager,
   createPKPManager,
+  createWithdrawalAddressModule,
   DiamondHandsSDK as default,
   failure,
   fetchProtocolPauseStatus,