@gvnrdao/dh-sdk 0.0.339 → 0.0.341

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

@@ -984,11 +984,12 @@ export declare class DiamondHandsSDK {
     getPSMAvailableReserves(stablecoinAddress: string): Promise<bigint>;
     /**
      * Execute a PSM stablecoin → UCD swap.
-     * Handles stablecoin approval to the PSM contract if the current allowance is insufficient.
+     * Approves EXACTLY `amountWei` to the PSM when the current allowance is short (resetting a
+     * partial allowance to zero first); every leg is validated by the sign-guard before it is sent.
      *
      * @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.minUcdOutWei - Minimum UCD to receive; must be > 0 (reverts on-chain if below)
      * @param params.signer - Connected signer for the approval and swap transactions
      */
     psmSwap(params: {
@@ -1002,12 +1003,13 @@ export declare class DiamondHandsSDK {
     }>;
     /**
      * 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).
+     * Approves EXACTLY `ucdAmountWei` of UCD to the UCDController (not the 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.minStablecoinOutWei - Minimum stablecoin to receive; must be > 0
      * @param params.signer - Connected signer
      */
     psmRedeem(params: {
@@ -1019,6 +1021,11 @@ export declare class DiamondHandsSDK {
         hash: string;
         blockNumber: number;
     }>;
+    /**
+     * Shared PSM path: plan + validate every leg against the chain the SIGNER is on, then send.
+     * The signer's chain must match the SDK's configured chain — the addresses came from it.
+     */
+    private runPsmExchange;
     /**
      * 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/sign-guard.js

@@ -32,6 +32,8 @@ __export(sign_guard_exports, {
   OP_ENVELOPE_FIELD_ORDER: () => OP_ENVELOPE_FIELD_ORDER,
   OP_ENVELOPE_LAYOUT: () => OP_ENVELOPE_LAYOUT,
   OP_ENVELOPE_TYPES: () => OP_ENVELOPE_TYPES,
+  PRIORITY_FEE_CAP_WEI: () => PRIORITY_FEE_CAP_WEI,
+  PRIORITY_FEE_FLOOR_WEI: () => PRIORITY_FEE_FLOOR_WEI,
   QUANTUM_SECONDS: () => QUANTUM_SECONDS,
   REQUEST_TIMEOUT_MS: () => REQUEST_TIMEOUT_MS,
   SIGNABLE_FUNCTIONS: () => SIGNABLE_FUNCTIONS,
@@ -42,17 +44,23 @@ __export(sign_guard_exports, {
   authorizeWithServer: () => authorizeWithServer,
   broadcastSignedTx: () => broadcastSignedTx,
   buildAuthEnvelope: () => buildAuthEnvelope,
+  buildPsmApproveTx: () => buildPsmApproveTx,
+  buildPsmRedeemTx: () => buildPsmRedeemTx,
+  buildPsmSwapTx: () => buildPsmSwapTx,
   buildValidationContext: () => buildValidationContext,
   computeExtendFeeUpperBound: () => computeExtendFeeUpperBound,
   decodeSignable: () => decodeSignable,
   describeUnsignedTx: () => describeUnsignedTx,
   encodeSignable: () => encodeSignable,
+  executePsmPlan: () => executePsmPlan,
   fetchWithTimeout: () => fetchWithTimeout,
   isAuthFresh: () => isAuthFresh,
   isStrictCurrentQuantum: () => isStrictCurrentQuantum,
   modeForChainId: () => modeForChainId,
   nextQuantumTimestamp: () => nextQuantumTimestamp,
+  planPsmExchange: () => planPsmExchange,
   postJson: () => postJson,
+  psmExchangeReadsFromProvider: () => psmExchangeReadsFromProvider,
   randomNonceHex: () => randomNonceHex,
   readTxFeeFields: () => readTxFeeFields,
   signAndBroadcast: () => signAndBroadcast,
@@ -66,8 +74,12 @@ module.exports = __toCommonJS(sign_guard_exports);
 
 // src/utils/sign-guard/errors.ts
 var TxValidationError = class extends Error {
-  constructor(msg) {
-    super(`Refusing to sign server-returned transaction: ${msg}`);
+  /**
+   * @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, subject = "server-returned transaction") {
+    super(`Refusing to sign ${subject}: ${msg}`);
     this.name = "TxValidationError";
   }
 };
@@ -150,6 +162,8 @@ var import_ethers2 = require("ethers");
 var MAX_GAS_LIMIT = 5000000n;
 var MAX_FEE_PER_GAS_WEI = 2000000000000n;
 var DEFAULT_MAX_TX_FEE_WEI = 250000000000000000n;
+var PRIORITY_FEE_FLOOR_WEI = 100000000n;
+var PRIORITY_FEE_CAP_WEI = 3000000000n;
 var DEFAULT_FEE_CEILING = {
   maxGasLimit: MAX_GAS_LIMIT,
   maxFeePerGasWei: MAX_FEE_PER_GAS_WEI,
@@ -962,6 +976,129 @@ async function computeExtendFeeUpperBound(provider, contracts, positionId, selec
   const upperBoundFeeWei = ucdDebt * extensionFeeRateBps / 10000n;
   return { ucdDebt, extensionFeeRateBps, upperBoundFeeWei };
 }
+
+// src/utils/sign-guard/psm-exchange.ts
+var import_ethers6 = require("ethers");
+function buildPsmApproveTx(p) {
+  return {
+    to: p.token,
+    data: encodeSignable("approve", [p.spender, p.amount]),
+    value: "0x0",
+    chainId: p.chainId
+  };
+}
+function buildPsmSwapTx(p) {
+  return {
+    to: p.psm,
+    data: encodeSignable("swap", [p.stablecoin, p.amountIn, p.minOut]),
+    value: "0x0",
+    chainId: p.chainId
+  };
+}
+function buildPsmRedeemTx(p) {
+  return {
+    to: p.psm,
+    data: encodeSignable("redeem", [p.stablecoin, p.ucdAmount, p.minOut]),
+    value: "0x0",
+    chainId: p.chainId
+  };
+}
+var PSM_READS_ABI = ["function supportedStablecoins(address) view returns (bool)"];
+var ERC20_READS_ABI = ["function allowance(address owner, address spender) view returns (uint256)"];
+function psmExchangeReadsFromProvider(provider, psmAddress) {
+  const psm = new import_ethers6.ethers.Contract(psmAddress, PSM_READS_ABI, provider);
+  return {
+    isStablecoinSupported: async (stablecoin) => await psm.getFunction("supportedStablecoins")(stablecoin),
+    allowance: async (token, owner, spender) => await new import_ethers6.ethers.Contract(token, ERC20_READS_ABI, provider).getFunction("allowance")(owner, spender)
+  };
+}
+var refuse = (direction, msg) => new TxValidationError(msg, `PSM ${direction}`);
+function requireAddress(direction, label, value) {
+  if (!value || !import_ethers6.ethers.isAddress(value)) {
+    throw refuse(direction, `${label} address is missing or invalid (${String(value)})`);
+  }
+  return import_ethers6.ethers.getAddress(value);
+}
+async function planPsmExchange(params) {
+  const { direction, amountIn, minOut, vctx, reads } = params;
+  const chainId = vctx.chainId;
+  if (amountIn <= 0n) {
+    throw refuse(direction, `amount must be greater than zero (got ${amountIn})`);
+  }
+  if (minOut <= 0n) {
+    throw refuse(direction, `minimum-out floor must be greater than zero (got ${minOut}) \u2014 a zero floor is refused on-chain`);
+  }
+  const owner = requireAddress(direction, "owner", params.owner);
+  const psm = requireAddress(direction, "SimplePSMV2", params.addresses.psm);
+  const stablecoin = requireAddress(direction, "stablecoin", params.addresses.stablecoin);
+  const isSwap = direction === "swap";
+  const token = isSwap ? stablecoin : requireAddress(direction, "UCDToken", params.addresses.ucdToken);
+  const spender = isSwap ? psm : requireAddress(direction, "UCDController", params.addresses.ucdController);
+  if (!await reads.isStablecoinSupported(stablecoin)) {
+    throw refuse(direction, `stablecoin ${stablecoin} is not supported by the PSM at ${psm}`);
+  }
+  const approveExpected = (amount) => isSwap ? { kind: "stablecoin-approve", tokenAddress: token, spender, amountUnits: amount.toString() } : { kind: "ucd-approve-controller", ucdTokenAddress: token, spender, amountWei: amount.toString() };
+  const allowanceBefore = await reads.allowance(token, owner, spender);
+  const approvals = [];
+  if (allowanceBefore < amountIn) {
+    if (allowanceBefore > 0n) {
+      approvals.push({
+        step: "reset-approve",
+        tx: buildPsmApproveTx({ token, spender, amount: 0n, chainId }),
+        expected: approveExpected(0n)
+      });
+    }
+    approvals.push({
+      step: "approve",
+      tx: buildPsmApproveTx({ token, spender, amount: amountIn, chainId }),
+      expected: approveExpected(amountIn)
+    });
+  }
+  const exec = isSwap ? {
+    step: "swap",
+    tx: buildPsmSwapTx({ psm, stablecoin, amountIn, minOut, chainId }),
+    expected: { kind: "psm-swap", psmAddress: psm, stablecoin, amountIn: amountIn.toString(), minOut: minOut.toString() }
+  } : {
+    step: "redeem",
+    tx: buildPsmRedeemTx({ psm, stablecoin, ucdAmount: amountIn, minOut, chainId }),
+    expected: {
+      kind: "psm-redeem",
+      psmAddress: psm,
+      stablecoin,
+      amountUcdWei: amountIn.toString(),
+      minOut: minOut.toString()
+    }
+  };
+  for (const leg of [...approvals, exec]) {
+    validateUnsignedTx({ ...leg.tx }, leg.expected, vctx);
+  }
+  return { direction, owner, token, spender, amountIn, minOut, allowanceBefore, approvals, exec };
+}
+async function executePsmPlan(plan, signer, vctx) {
+  const approvalHashes = [];
+  const residual = () => approvalHashes.length === 0 ? "" : ` An approval already landed (tx ${approvalHashes[approvalHashes.length - 1]}): an allowance of exactly ${plan.amountIn} to ${plan.spender} stands. It authorizes only that amount; the next exchange uses or replaces it.`;
+  const sendLeg = async (leg) => {
+    const request = { to: leg.tx.to, data: leg.tx.data, value: 0n, chainId: leg.tx.chainId };
+    validateUnsignedTx({ ...request }, leg.expected, vctx);
+    const sent = await signer.sendTransaction(request);
+    const receipt = await sent.wait();
+    if (!receipt)
+      throw new Error(`PSM ${leg.step} tx ${sent.hash} returned no receipt`);
+    if (receipt.status !== 1)
+      throw new Error(`PSM ${leg.step} tx ${sent.hash} reverted`);
+    return { hash: sent.hash, blockNumber: receipt.blockNumber };
+  };
+  for (const leg of plan.approvals) {
+    const landed = await sendLeg(leg).catch((e) => {
+      throw new Error(`PSM ${leg.step} failed: ${e instanceof Error ? e.message : String(e)}.${residual()}`);
+    });
+    approvalHashes.push(landed.hash);
+  }
+  const exec = await sendLeg(plan.exec).catch((e) => {
+    throw new Error(`PSM ${plan.exec.step} failed: ${e instanceof Error ? e.message : String(e)}.${residual()}`);
+  });
+  return { ...exec, approvalHashes };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AUTH_VALIDITY_WINDOWS,
@@ -976,6 +1113,8 @@ async function computeExtendFeeUpperBound(provider, contracts, positionId, selec
   OP_ENVELOPE_FIELD_ORDER,
   OP_ENVELOPE_LAYOUT,
   OP_ENVELOPE_TYPES,
+  PRIORITY_FEE_CAP_WEI,
+  PRIORITY_FEE_FLOOR_WEI,
   QUANTUM_SECONDS,
   REQUEST_TIMEOUT_MS,
   SIGNABLE_FUNCTIONS,
@@ -986,17 +1125,23 @@ async function computeExtendFeeUpperBound(provider, contracts, positionId, selec
   authorizeWithServer,
   broadcastSignedTx,
   buildAuthEnvelope,
+  buildPsmApproveTx,
+  buildPsmRedeemTx,
+  buildPsmSwapTx,
   buildValidationContext,
   computeExtendFeeUpperBound,
   decodeSignable,
   describeUnsignedTx,
   encodeSignable,
+  executePsmPlan,
   fetchWithTimeout,
   isAuthFresh,
   isStrictCurrentQuantum,
   modeForChainId,
   nextQuantumTimestamp,
+  planPsmExchange,
   postJson,
+  psmExchangeReadsFromProvider,
   randomNonceHex,
   readTxFeeFields,
   signAndBroadcast,

package/dist/sign-guard.mjs

@@ -1,7 +1,11 @@
 // src/utils/sign-guard/errors.ts
 var TxValidationError = class extends Error {
-  constructor(msg) {
-    super(`Refusing to sign server-returned transaction: ${msg}`);
+  /**
+   * @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, subject = "server-returned transaction") {
+    super(`Refusing to sign ${subject}: ${msg}`);
     this.name = "TxValidationError";
   }
 };
@@ -84,6 +88,8 @@ import { ethers as ethers2 } from "ethers";
 var MAX_GAS_LIMIT = 5000000n;
 var MAX_FEE_PER_GAS_WEI = 2000000000000n;
 var DEFAULT_MAX_TX_FEE_WEI = 250000000000000000n;
+var PRIORITY_FEE_FLOOR_WEI = 100000000n;
+var PRIORITY_FEE_CAP_WEI = 3000000000n;
 var DEFAULT_FEE_CEILING = {
   maxGasLimit: MAX_GAS_LIMIT,
   maxFeePerGasWei: MAX_FEE_PER_GAS_WEI,
@@ -896,6 +902,129 @@ async function computeExtendFeeUpperBound(provider, contracts, positionId, selec
   const upperBoundFeeWei = ucdDebt * extensionFeeRateBps / 10000n;
   return { ucdDebt, extensionFeeRateBps, upperBoundFeeWei };
 }
+
+// src/utils/sign-guard/psm-exchange.ts
+import { ethers as ethers6 } from "ethers";
+function buildPsmApproveTx(p) {
+  return {
+    to: p.token,
+    data: encodeSignable("approve", [p.spender, p.amount]),
+    value: "0x0",
+    chainId: p.chainId
+  };
+}
+function buildPsmSwapTx(p) {
+  return {
+    to: p.psm,
+    data: encodeSignable("swap", [p.stablecoin, p.amountIn, p.minOut]),
+    value: "0x0",
+    chainId: p.chainId
+  };
+}
+function buildPsmRedeemTx(p) {
+  return {
+    to: p.psm,
+    data: encodeSignable("redeem", [p.stablecoin, p.ucdAmount, p.minOut]),
+    value: "0x0",
+    chainId: p.chainId
+  };
+}
+var PSM_READS_ABI = ["function supportedStablecoins(address) view returns (bool)"];
+var ERC20_READS_ABI = ["function allowance(address owner, address spender) view returns (uint256)"];
+function psmExchangeReadsFromProvider(provider, psmAddress) {
+  const psm = new ethers6.Contract(psmAddress, PSM_READS_ABI, provider);
+  return {
+    isStablecoinSupported: async (stablecoin) => await psm.getFunction("supportedStablecoins")(stablecoin),
+    allowance: async (token, owner, spender) => await new ethers6.Contract(token, ERC20_READS_ABI, provider).getFunction("allowance")(owner, spender)
+  };
+}
+var refuse = (direction, msg) => new TxValidationError(msg, `PSM ${direction}`);
+function requireAddress(direction, label, value) {
+  if (!value || !ethers6.isAddress(value)) {
+    throw refuse(direction, `${label} address is missing or invalid (${String(value)})`);
+  }
+  return ethers6.getAddress(value);
+}
+async function planPsmExchange(params) {
+  const { direction, amountIn, minOut, vctx, reads } = params;
+  const chainId = vctx.chainId;
+  if (amountIn <= 0n) {
+    throw refuse(direction, `amount must be greater than zero (got ${amountIn})`);
+  }
+  if (minOut <= 0n) {
+    throw refuse(direction, `minimum-out floor must be greater than zero (got ${minOut}) \u2014 a zero floor is refused on-chain`);
+  }
+  const owner = requireAddress(direction, "owner", params.owner);
+  const psm = requireAddress(direction, "SimplePSMV2", params.addresses.psm);
+  const stablecoin = requireAddress(direction, "stablecoin", params.addresses.stablecoin);
+  const isSwap = direction === "swap";
+  const token = isSwap ? stablecoin : requireAddress(direction, "UCDToken", params.addresses.ucdToken);
+  const spender = isSwap ? psm : requireAddress(direction, "UCDController", params.addresses.ucdController);
+  if (!await reads.isStablecoinSupported(stablecoin)) {
+    throw refuse(direction, `stablecoin ${stablecoin} is not supported by the PSM at ${psm}`);
+  }
+  const approveExpected = (amount) => isSwap ? { kind: "stablecoin-approve", tokenAddress: token, spender, amountUnits: amount.toString() } : { kind: "ucd-approve-controller", ucdTokenAddress: token, spender, amountWei: amount.toString() };
+  const allowanceBefore = await reads.allowance(token, owner, spender);
+  const approvals = [];
+  if (allowanceBefore < amountIn) {
+    if (allowanceBefore > 0n) {
+      approvals.push({
+        step: "reset-approve",
+        tx: buildPsmApproveTx({ token, spender, amount: 0n, chainId }),
+        expected: approveExpected(0n)
+      });
+    }
+    approvals.push({
+      step: "approve",
+      tx: buildPsmApproveTx({ token, spender, amount: amountIn, chainId }),
+      expected: approveExpected(amountIn)
+    });
+  }
+  const exec = isSwap ? {
+    step: "swap",
+    tx: buildPsmSwapTx({ psm, stablecoin, amountIn, minOut, chainId }),
+    expected: { kind: "psm-swap", psmAddress: psm, stablecoin, amountIn: amountIn.toString(), minOut: minOut.toString() }
+  } : {
+    step: "redeem",
+    tx: buildPsmRedeemTx({ psm, stablecoin, ucdAmount: amountIn, minOut, chainId }),
+    expected: {
+      kind: "psm-redeem",
+      psmAddress: psm,
+      stablecoin,
+      amountUcdWei: amountIn.toString(),
+      minOut: minOut.toString()
+    }
+  };
+  for (const leg of [...approvals, exec]) {
+    validateUnsignedTx({ ...leg.tx }, leg.expected, vctx);
+  }
+  return { direction, owner, token, spender, amountIn, minOut, allowanceBefore, approvals, exec };
+}
+async function executePsmPlan(plan, signer, vctx) {
+  const approvalHashes = [];
+  const residual = () => approvalHashes.length === 0 ? "" : ` An approval already landed (tx ${approvalHashes[approvalHashes.length - 1]}): an allowance of exactly ${plan.amountIn} to ${plan.spender} stands. It authorizes only that amount; the next exchange uses or replaces it.`;
+  const sendLeg = async (leg) => {
+    const request = { to: leg.tx.to, data: leg.tx.data, value: 0n, chainId: leg.tx.chainId };
+    validateUnsignedTx({ ...request }, leg.expected, vctx);
+    const sent = await signer.sendTransaction(request);
+    const receipt = await sent.wait();
+    if (!receipt)
+      throw new Error(`PSM ${leg.step} tx ${sent.hash} returned no receipt`);
+    if (receipt.status !== 1)
+      throw new Error(`PSM ${leg.step} tx ${sent.hash} reverted`);
+    return { hash: sent.hash, blockNumber: receipt.blockNumber };
+  };
+  for (const leg of plan.approvals) {
+    const landed = await sendLeg(leg).catch((e) => {
+      throw new Error(`PSM ${leg.step} failed: ${e instanceof Error ? e.message : String(e)}.${residual()}`);
+    });
+    approvalHashes.push(landed.hash);
+  }
+  const exec = await sendLeg(plan.exec).catch((e) => {
+    throw new Error(`PSM ${plan.exec.step} failed: ${e instanceof Error ? e.message : String(e)}.${residual()}`);
+  });
+  return { ...exec, approvalHashes };
+}
 export {
   AUTH_VALIDITY_WINDOWS,
   BROADCAST_PATH,
@@ -909,6 +1038,8 @@ export {
   OP_ENVELOPE_FIELD_ORDER,
   OP_ENVELOPE_LAYOUT,
   OP_ENVELOPE_TYPES,
+  PRIORITY_FEE_CAP_WEI,
+  PRIORITY_FEE_FLOOR_WEI,
   QUANTUM_SECONDS,
   REQUEST_TIMEOUT_MS,
   SIGNABLE_FUNCTIONS,
@@ -919,17 +1050,23 @@ export {
   authorizeWithServer,
   broadcastSignedTx,
   buildAuthEnvelope,
+  buildPsmApproveTx,
+  buildPsmRedeemTx,
+  buildPsmSwapTx,
   buildValidationContext,
   computeExtendFeeUpperBound,
   decodeSignable,
   describeUnsignedTx,
   encodeSignable,
+  executePsmPlan,
   fetchWithTimeout,
   isAuthFresh,
   isStrictCurrentQuantum,
   modeForChainId,
   nextQuantumTimestamp,
+  planPsmExchange,
   postJson,
+  psmExchangeReadsFromProvider,
   randomNonceHex,
   readTxFeeFields,
   signAndBroadcast,

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

@@ -22,14 +22,22 @@ export declare function safeGetBitcoinAddressesFromPkp(pkpId: string, maxRetries
     testnet: string;
     regtest: string;
 }>;
+type BitcoinAddressNetwork = 'mainnet' | 'testnet' | 'regtest';
 /**
- * Safely validate and format a Bitcoin address
- * @param address Bitcoin address to validate
- * @param network Network type for validation
- * @returns Validated address
- * @throws Clear error message if validation fails
+ * Validate a Bitcoin address for the network the caller is operating on.
+ *
+ * Runs on the BTC withdrawal path before any Lit Action, authorization or signature, so
+ * it verifies the CHECKSUM (base58check / bech32 / bech32m, via `BitcoinUtils`) and then
+ * the network. BTC sent to a mistyped or wrong-network address is unrecoverable; the
+ * previous implementation checked the prefix only, so a one-character typo passed.
+ *
+ * `network` is required. It used to default to 'regtest', which would have validated a
+ * mainnet caller's address against the wrong chain without saying so.
+ *
+ * @returns the address unchanged
+ * @throws if the address is malformed, fails its checksum, or is not on `network`
  */
-export declare function safeValidateBitcoinAddress(address: string, network?: 'mainnet' | 'testnet' | 'regtest'): string;
+export declare function safeValidateBitcoinAddress(address: string, network: BitcoinAddressNetwork): 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
@@ -49,3 +57,4 @@ export declare function normalizeBitcoinAddress(address: string): string;
  * @throws Clear error message if validation fails
  */
 export declare function safeValidatePositionId(positionId: string): string;
+export {};

package/dist/utils/agent-delegation.utils.d.ts

@@ -18,3 +18,42 @@ export declare function mintAgentPkp(params: {
     authHeader?: () => Promise<Record<string, string>> | Record<string, string>;
     timeoutMs?: number;
 }): Promise<string>;
+/** `AgentStatus` in `IAgentDelegateRegistryBase.sol`. */
+export declare const AGENT_STATUS: {
+    readonly None: 0;
+    readonly Active: 1;
+    readonly Revoked: 2;
+};
+/** How the enable-path binds the borrower's agent. `reuse` needs no mint and no tx. */
+export type AgentBindingPlan = {
+    kind: "reuse";
+    agent: string;
+} | {
+    kind: "register";
+} | {
+    kind: "rotate";
+};
+/**
+ * Decide which registry call binds a borrower's agent — BEFORE a PKP is minted.
+ *
+ * The registry does not change `status` on expiry: an expired agent is still
+ * `status == Active`, only `validUntil` has passed. So `isAgentActive()` is false, yet
+ * `registerAgent` reverts `AgentIsActiveUseRotate()` — rotation is the renewal path, and it
+ * needs a NEW agent address (AR-1 burns an address on first bind). Treating "not active" as
+ * "register" minted a billed PKP and then reverted, on every attempt, once an agent expired.
+ *
+ * `isAgentActive` also folds in the registry's pause. An UNEXPIRED `Active` record that reads
+ * inactive means paused: both `registerAgent` and `rotateAgent` are `whenNotPaused`, so this
+ * throws rather than let the caller mint a PKP for a transaction that cannot land.
+ *
+ * @param nowSeconds chain time (latest block timestamp), not the local clock
+ */
+export declare function planAgentBinding(params: {
+    isActive: boolean;
+    record: {
+        agent: string;
+        validUntil: bigint | number;
+        status: bigint | number;
+    };
+    nowSeconds: number;
+}): AgentBindingPlan;

package/dist/utils/assert-provider-chain.d.ts

@@ -0,0 +1,16 @@
+/**
+ * An explicit `chainId` is a claim until the provider confirms it.
+ *
+ * The SDK resolves its contract addresses, validators and subgraph from `chainId`. If the
+ * provider (the wallet) is actually on another chain, every address it is about to call or
+ * sign for belongs to the wrong network. So the claim is checked once, at initialisation.
+ *
+ * Returns the mismatch as a message (for the caller's `Result`), or `null` when the provider
+ * agrees. A provider that cannot report its network is NOT waved through: its error
+ * propagates unchanged, so the caller sees the real cause and no SDK exists to sign with.
+ */
+export declare function describeProviderChainMismatch(provider: {
+    getNetwork(): Promise<{
+        chainId: bigint | number;
+    }>;
+}, chainId: number): Promise<string | null>;

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

@@ -110,8 +110,8 @@ export declare const LIQUIDATION_REVEAL_GAS_CEILING: bigint;
  * 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;
+import { PRIORITY_FEE_FLOOR_WEI, PRIORITY_FEE_CAP_WEI } from "../sign-guard/fee-ceiling";
+export { PRIORITY_FEE_FLOOR_WEI, PRIORITY_FEE_CAP_WEI };
 /** Blocks of eth_feeHistory sampled; the median across them absorbs a single spike block. */
 export declare const FEE_HISTORY_BLOCK_COUNT = 20;
 /**

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/contract-error-decoder.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Contract error decoder — a revert's bytes turned into the error the CONTRACT declares.
+ *
+ * Every name and selector here comes from the committed typechain ABIs, never from a
+ * hand-written table. Two hand-written tables used to live in this file and they had
+ * drifted: `0x137f3b70 -> InDeadZone` is a selector no contract can ever emit (the real
+ * error is `DeadZoneViolation()`, `0xbe4b82c1`; `isInDeadZone` is a view function), so a
+ * borrower hitting the dead zone would have been told about an error that does not exist.
+ * An ABI-derived table cannot drift: a renamed or deleted error disappears with it.
+ *
+ * Selector collisions across contracts are possible in principle (4 bytes). The table
+ * records EVERY contract a selector belongs to and `contract` names them all, rather than
+ * silently picking one.
+ */
+import { type ErrorFragment } from "ethers";
+/** Decoded error information. */
+export interface DecodedError {
+    name: string;
+    selector: string;
+    args?: any[];
+    /** The contract(s) declaring this error, or `"Unknown"`. */
+    contract: string;
+    message: string;
+}
+export interface ContractErrorEntry {
+    /** `Name(type,type)` exactly as declared. */
+    signature: string;
+    fragment: ErrorFragment;
+    /** Every contract in the set declaring this selector. */
+    contracts: string[];
+}
+/** Selector -> declared error, built once from the generated fragments. */
+export declare function contractErrorTable(): Map<string, ContractErrorEntry>;
+/** The declared error for a selector, or null when no contract in the set declares it. */
+export declare function lookupContractError(selector: string): ContractErrorEntry | null;
+/**
+ * Decode a contract revert.
+ *
+ * Returns the declared error with its ARGUMENTS wherever the payload carries them — the
+ * figures are the point (`SlippageExceeded(got, minimum)`, `InsufficientReserves(available,
+ * required)`). Selector-only payloads still resolve to the right name with empty args.
+ * Standard `Error(string)` and `Panic(uint256)` reverts decode too. Returns null only when
+ * there is nothing to decode at all.
+ */
+export declare function decodeContractError(error: any): DecodedError | null;
+/** Format a decoded error for logging and user-facing messages. */
+export declare function formatDecodedError(decoded: DecodedError): string;

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;