@gvnrdao/dh-sdk 0.0.236 → 0.0.244

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

@@ -70,8 +70,72 @@ export declare class DiamondHandsSDK {
     private readonly bitcoinOperations;
     private readonly mockTokenManager?;
     private readonly graphClient;
+    /**
+     * Session helper for the lit-ops-server. Set in service mode; undefined
+     * in standalone mode (no server to authenticate against). Use
+     * `this.getAuthHeader()` which centralizes the undefined check.
+     */
+    private readonly serverSession?;
     private isInitialized;
     private isDisposed;
+    /**
+     * Audit H-13: per-position write serialization. Tracks positions with an
+     * in-flight state-mutating call so a concurrent mint / payment / extend /
+     * withdraw / liquidation for the same position fast-fails locally instead
+     * of paying a full Lit-Action round-trip + gas only to revert on-chain
+     * via the M-4 flash-loan protection's `lastInteractionBlockByPosition`
+     * guard. Stored as a Set — no Promise needed since callers don't await
+     * on each other; they get an immediate refusal and can retry once their
+     * sibling call has completed.
+     */
+    private readonly inFlightWrites;
+    /**
+     * Acquire the per-position write lock. Returns `null` on success, or a
+     * structured failure when another write is already in flight. The caller
+     * must `cast` the failure to the method's specific result type — every
+     * write-method result includes a `{ success: false; error: string }`
+     * branch so the cast is safe.
+     */
+    private tryAcquireWriteLock;
+    /** Release the per-position write lock. Safe to call when not held. */
+    private releaseWriteLock;
+    /**
+     * Build the `Authorization: Bearer <jwt>` header for a request to
+     * lit-ops-server. Returns an empty object in standalone mode (no server
+     * to authenticate to) or when the session helper has not been wired —
+     * in which case the server's `requireSessionToken` middleware will
+     * reject the call with 401, which is the correct outcome.
+     */
+    private getAuthHeader;
+    /**
+     * Audit H-9: invalidate the LoanQuery cache so subsequent reads return
+     * the post-write state. We clear the entire loan-query cache (not just
+     * the entry for this position) because the cache keys by `pkpId` and we
+     * don't always have it in scope at the release site — a position-keyed
+     * helper would require a pre-write lookup that defeats the cache. The
+     * blast radius is bounded: the cache is per-process and a fresh fetch
+     * is cheap relative to a Lit Action call.
+     *
+     * `includePkpCache: true` is passed by liquidation to also drop the
+     * 24-hour PKP-data cache entry — the Lit auth-context attached to a
+     * PKP changes when ownership transfers, so the cached `ethAddress`
+     * (used for capacity-credit delegation) must be re-derived.
+     */
+    private invalidateCachesForPosition;
+    /**
+     * Audit H-11: pre-flight check for `PositionManager.getProtocolPauseStatus()`.
+     *
+     * Returns `{ ok: true }` if none of the supplied pause keys are set, or
+     * `{ ok: false, error }` if the protocol is paused for this operation
+     * type. Caller returns the structured failure to the user before paying
+     * for a LIT Action round-trip + gas that the on-chain function would
+     * later revert.
+     *
+     * Best-effort: if no EVM provider is available (e.g., service-mode setup
+     * without `ethRpcUrl`) or the read itself fails, we return `{ ok: true }`
+     * with a debug log — the on-chain call remains the final authority.
+     */
+    private preflightProtocolPause;
     /**
      * Private constructor - use DiamondHandsSDK.create() instead
      *
@@ -328,7 +392,7 @@ export declare class DiamondHandsSDK {
      * @param customBitcoinRpcUrl - Optional custom Bitcoin RPC URL (for local testing)
      * @returns Withdrawal result with transaction details
      */
-    withdrawBTC(positionId: string, withdrawalAddress: string, withdrawalAmount: number, rpcUrl?: string, customBitcoinRpcUrl?: string): Promise<BTCWithdrawalResult>;
+    withdrawBTC(positionId: string, withdrawalAddress: string, withdrawalAmount: number): Promise<BTCWithdrawalResult>;
     /**
      * Execute Bitcoin withdrawal (Phase 2)
      *
@@ -341,10 +405,15 @@ export declare class DiamondHandsSDK {
     executeBTCWithdrawal(request: {
         positionId: string;
         utxoIdentifier: string;
+        utxoSatoshis: number;
         networkFee: number;
         destination: string;
-        rpcUrl?: string;
-        customBitcoinRpcUrl?: string;
+        /**
+         * User-authorized withdrawal amount in satoshis (Phase 1 `withdrawalAmount`).
+         * Bound into the Phase-2 signature alongside `destination` so the Lit
+         * Action can cross-check against the on-chain authorizer record.
+         */
+        targetAmount: number;
     }): Promise<{
         success: boolean;
         txid?: string;
@@ -364,7 +433,7 @@ export declare class DiamondHandsSDK {
      * @param rpcUrl - Optional RPC URL override for LIT Action (for local testing)
      * @returns Array of execution results for each pending transfer
      */
-    executePendingBtcTransfers(positionId: string, networkFee: number, rpcUrl?: string): Promise<Array<{
+    executePendingBtcTransfers(positionId: string, networkFee: number): Promise<Array<{
         success: boolean;
         utxoIdentifier?: string;
         txid?: string;
@@ -423,7 +492,7 @@ export declare class DiamondHandsSDK {
      * @param customBitcoinRpcUrl - Optional custom Bitcoin RPC URL (for local testing)
      * @returns Complete withdrawal result with both authorization and execution details
      */
-    withdrawBTCAndExecute(positionId: string, withdrawalAddress: string, withdrawalAmount: number, networkFee: number, rpcUrl?: string, customBitcoinRpcUrl?: string): Promise<{
+    withdrawBTCAndExecute(positionId: string, withdrawalAddress: string, withdrawalAmount: number, networkFee: number): Promise<{
         success: boolean;
         authorization?: BTCWithdrawalResult;
         transfers?: Array<{
@@ -463,7 +532,7 @@ export declare class DiamondHandsSDK {
     getLoansByBorrower(borrower: string, pagination?: {
         page: number;
         pageSize: number;
-    }): Promise<Result<import("../interfaces/chunks/loan-operations.i").PaginatedLoansResponse, SDKError>>;
+    }, orderBy?: "createdAt" | "lastUpdatedAt" | "ucdDebt", orderDirection?: "asc" | "desc"): Promise<Result<import("../interfaces/chunks/loan-operations.i").PaginatedLoansResponse, SDKError>>;
     /**
      * Get all active loans
      *
@@ -524,6 +593,13 @@ export declare class DiamondHandsSDK {
      * @returns the current Bitcoin price in USD
      */
     getBitcoinPrice(): Promise<{
+        price: number;
+        priceE8: string;
+        timestamp: number;
+        source: string;
+        signature?: undefined;
+        signer?: undefined;
+    } | {
         price: number;
         priceE8: string;
         timestamp: number;
@@ -571,6 +647,23 @@ export declare class DiamondHandsSDK {
      * ```
      */
     getTermsWithFees(): Promise<Result<TermsWithFeesResult, SDKError>>;
+    getProtocolConfig(): Promise<Result<{
+        liquidationThreshold: string;
+        minimumLoanValueUcd: string;
+        minimumLoanValueWei: string;
+        maxSingleLoanValueUcd: string;
+        maxSingleLoanValueWei: string;
+    }, SDKError>>;
+    getGasBalance(address: string): Promise<Result<{
+        balanceWei: string;
+        balanceEth: string;
+    }, SDKError>>;
+    getVaultBalance(positionId: string): Promise<Result<{
+        vaultAddress: string;
+        balanceSats: string;
+        balanceBtc: string;
+        btcPrice: string;
+    }, SDKError>>;
     /**
      * Mint mock BTC tokens (test networks only)
      *
@@ -612,7 +705,10 @@ export declare class DiamondHandsSDK {
      */
     private isProductionNetwork;
     /**
-     * Get Bitcoin network based on chain
+     * Get Bitcoin network based on chain.
+     *
+     * Provider URLs are now sourced from the on-chain registry, so the network
+     * is derived purely from `this.config.chain`.
      */
     private getBitcoinNetwork;
     /**

package/dist/modules/loan/loan-creator.module.d.ts

@@ -10,7 +10,7 @@
  *
  * Flow: PKP Creation → Authorization → Contract Call → Verification
  */
-import type { Wallet } from "ethers";
+import { type Wallet } from "ethers";
 import { Result } from "../../types/result";
 import { SDKError } from "../../utils/error-handler";
 import type { PKPManager } from "../pkp/pkp-manager.module";

package/dist/modules/loan/loan-query.module.d.ts

@@ -16,7 +16,7 @@ import type { Cache } from "../cache/cache-manager.module";
 import type { LoanData, LoanDataDetail, PaginatedLoansResponse } from "../../interfaces/chunks/loan-operations.i";
 import type { LoanEvents, LoanEventsFilter } from "../../types/event-types";
 import { DiamondHandsGraphClient } from "@graphs/diamond-hands";
-import type { providers } from "ethers";
+import { type Provider } from "ethers";
 /**
  * Loan query filters
  */
@@ -52,7 +52,7 @@ export interface LoanQueryConfig {
     /** Bitcoin operations for balance enrichment */
     bitcoinOperations: BitcoinOperations;
     /** Ethereum provider for PKP public key retrieval */
-    provider?: providers.Provider;
+    provider?: Provider;
     /** PositionManagerCoreModule address — used as fallback vault address source for Chipotle loans */
     positionManagerCoreAddress?: string;
     /** Cache for loan query results (keyed by PKP ID) */
@@ -132,7 +132,7 @@ export declare class LoanQuery {
      * @param pagination - Pagination parameters
      * @returns Paginated loans for borrower
      */
-    getLoansByBorrower(borrower: string, pagination?: PaginationParams): Promise<Result<PaginatedLoansResponse, SDKError>>;
+    getLoansByBorrower(borrower: string, pagination?: PaginationParams, orderBy?: "createdAt" | "lastUpdatedAt" | "ucdDebt", orderDirection?: "asc" | "desc"): Promise<Result<PaginatedLoansResponse, SDKError>>;
     /**
      * Get active loans (status = 0)
      *

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

@@ -27,8 +27,12 @@ export interface PKPManagerConfig {
     litNetwork: string;
     /** Service mode: endpoint for lit-ops-server */
     serviceEndpoint?: string;
-    /** Service mode: authentication token */
-    serviceAuthToken?: string;
+    /**
+     * Service mode: returns `Authorization`-style headers for each request.
+     * Called once per request so the underlying session can refresh as
+     * needed. Empty object disables the header (server will 401).
+     */
+    getAuthHeader?: () => Promise<Record<string, string>>;
     /** Direct mode: wallet for PKP operations */
     litOpsWallet?: Wallet;
     /** Optional cache for PKP data */

package/dist/protocol/protocol-pause.d.ts

@@ -1,7 +1,7 @@
 /**
  * Helpers for `PositionManager.getProtocolPauseStatus()` (Lit Actions / client fast-fail).
  */
-import { ethers } from 'ethers';
+import { type Provider } from 'ethers';
 export type ProtocolPauseStatus = {
     positionManagerPaused: boolean;
     positionManagerLiquidationsPaused: boolean;
@@ -14,6 +14,6 @@ export type ProtocolPauseStatus = {
     ucdTokenPaused: boolean;
     simplePsmPaused: boolean;
 };
-export declare function fetchProtocolPauseStatus(provider: ethers.providers.Provider, positionManagerAddress: string): Promise<ProtocolPauseStatus>;
+export declare function fetchProtocolPauseStatus(provider: Provider, positionManagerAddress: string): Promise<ProtocolPauseStatus>;
 export type ProtocolPauseKey = keyof ProtocolPauseStatus;
 export declare function assertProtocolNotPaused(status: ProtocolPauseStatus, requiredKeys: readonly ProtocolPauseKey[]): void;

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

@@ -0,0 +1,39 @@
+/**
+ * Address Conversion Utilities
+ * Provides safe address conversion and validation with clear error messages
+ */
+/**
+ * Safely convert a string to bytes32 with clear error handling
+ * @param value String value to convert
+ * @param fieldName Name of the field for error messages
+ * @returns bytes32 string
+ * @throws Clear error message if conversion fails
+ */
+export declare function safeHexZeroPad(value: string, fieldName?: string): string;
+/**
+ * Safely get Bitcoin addresses from PKP with retry and clear error handling
+ * @param pkpId PKP ID to derive addresses from
+ * @param maxRetries Maximum number of retries (default: 3)
+ * @returns Bitcoin addresses for all networks
+ * @throws Clear error message if derivation fails
+ */
+export declare function safeGetBitcoinAddressesFromPkp(pkpId: string, maxRetries?: number): Promise<{
+    mainnet: string;
+    testnet: string;
+    regtest: string;
+}>;
+/**
+ * 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
+ */
+export declare function safeValidateBitcoinAddress(address: string, network?: 'mainnet' | 'testnet' | 'regtest'): string;
+/**
+ * Safely parse and validate a position ID
+ * @param positionId Position ID to validate
+ * @returns Validated position ID
+ * @throws Clear error message if validation fails
+ */
+export declare function safeValidatePositionId(positionId: string): string;

package/dist/utils/bitcoin-provider.utils.d.ts

@@ -45,4 +45,40 @@ export declare class BitcoinProvider {
      * Check if an address has received at least a specific amount
      */
     hasReceivedAmount(address: string, expectedAmount: bigint): Promise<boolean>;
+    /**
+     * Fetch a Bitcoin transaction by txid.
+     *
+     * Audit CRIT-2: used to verify that a Phase-2 BTC withdrawal the server
+     * claimed broadcast actually exists and matches the user's authorization.
+     * Returns `null` if no provider has the tx yet — the caller may retry to
+     * allow for propagation/indexing delay.
+     *
+     * Esplora response shape: `{ txid, vin: [{txid, vout, ...}], vout: [{value, scriptpubkey_address, ...}], status: {confirmed, ...} }`
+     */
+    getTransaction(txid: string): Promise<BitcoinTransactionInfo | null>;
+    /**
+     * Try each candidate path on the provider. Returns `null` on 404 (tx not
+     * yet visible) but throws on other errors so the outer loop can move to
+     * the next provider.
+     */
+    private fetchTxFromProvider;
+}
+/**
+ * Normalized Bitcoin transaction information returned by `getTransaction`.
+ * Only the fields used by post-broadcast verification are populated; we
+ * deliberately do NOT echo full witness / scriptpubkey data to keep the
+ * surface small.
+ */
+export interface BitcoinTransactionInfo {
+    txid: string;
+    vin: Array<{
+        txid: string;
+        vout: number;
+    }>;
+    vout: Array<{
+        value: number;
+        address?: string;
+    }>;
+    /** True if the tx is in a block, false if still in mempool, undefined unknown. */
+    confirmed?: boolean;
 }

package/dist/utils/btc-withdrawal-message.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Helpers for building the EIP-191 `execute-btc-withdrawal` envelope that the
+ * `btc-transaction-signer` LIT Action verifies.
+ *
+ * Pulled out of the CLI's executePendingWithdrawal util so the SDK and CLI
+ * use the same logic and signing rules.
+ */
+import { type Signer } from "ethers";
+export interface BtcExecuteSignParams {
+    positionId: string;
+    txid: string;
+    vout: number;
+    networkFee: number;
+    chainId: number;
+    signer: Signer;
+}
+export interface BtcExecuteSignedEnvelope {
+    positionId: string;
+    txid: string;
+    vout: number;
+    satoshis: number;
+    /** Bitcoin destination address bound into the signature. */
+    targetAddress: string;
+    /** Authorized withdrawal amount (sats) bound into the signature. */
+    targetAmount: number;
+    networkFee: number;
+    chainId: number;
+    /** Quantum-aligned timestamp (start of a 60s quantum). */
+    timestamp: number;
+    /** EIP-191 signature over the message hash. */
+    userSignature: string;
+    /** Address recovered from the signer (borrower). */
+    borrowerAddress: string;
+}
+/**
+ * Build the quantum-aligned timestamp + EIP-191 signature the
+ * `/api/lit/pending-withdrawals/execute` endpoint expects.
+ *
+ * Audit CRIT-1: the signed message now binds `targetAddress` and `targetAmount`
+ * in addition to the UTXO identifier. The previous shape bound only the UTXO,
+ * delegating destination/amount enforcement to the Lit Action's on-chain
+ * `getAuthorizedSpends` lookup. That single defense was reliable in practice
+ * but the user-signed message is now self-describing — the Lit Action
+ * cross-checks the user-signed values against the on-chain authorizer record
+ * and refuses any disagreement, so a bug or future loosening of one side does
+ * not silently redirect funds.
+ *
+ * Caller passes the UTXO satoshis (from Phase 1 result) AND the user-authorized
+ * destination + amount; this helper returns everything the server needs to
+ * delegate to the BTC signer LIT Action.
+ *
+ * Wire-compat: this is a coordinated breaking change — the new SDK signatures
+ * are not accepted by an older btc-transaction-signer Lit Action, and the new
+ * Lit Action does not accept older SDK signatures. Deploy together.
+ */
+export declare function buildBtcExecuteEnvelope(params: BtcExecuteSignParams & {
+    satoshis: number;
+    targetAddress: string;
+    targetAmount: number;
+}): Promise<BtcExecuteSignedEnvelope>;

package/dist/utils/chunks/bitcoin-utils.d.ts

@@ -51,6 +51,16 @@ export declare function getBitcoinAddressFromPkp(pkpPublicKey: string, network?:
  */
 export declare function getBitcoinAddressesFromPkp(pkpPublicKey: string): Promise<BitcoinAddresses>;
 export declare class BitcoinUtils {
+    /**
+     * Validate a Bitcoin address across mainnet / testnet / regtest with full
+     * checksum verification.
+     *
+     * Audit H-12: the previous implementation was a permissive regex with no
+     * checksum check — garbage like `bc1qqqqqqqqqq` passed. The new
+     * implementation uses the `bech32` and `bs58check` packages (both already
+     * in deps) to validate the actual checksum, and rejects unknown HRPs /
+     * version bytes / witness program lengths.
+     */
     static validateAddress(address: string): boolean;
     static formatTransaction(hash: string, amount: string, recipient: string): {
         hash: string;

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

@@ -2,23 +2,22 @@
  * EIP-1559 transaction broadcast helpers for paths that need explicit gas limits
  * (e.g. large mintUCD) without manual signDigest / eth_sendRawTransaction.
  */
-import { ethers as ethers5 } from "ethers";
-import type { BigNumber, providers, Signer } from "ethers";
+import { type Provider, type Signer, type TransactionResponse } from "ethers";
 /** Observed mintUCD + LIT validation can exceed 7M gas; cap avoids block limit issues. */
-export declare const MINT_UCD_GAS_CEILING: ethers5.BigNumber;
+export declare const MINT_UCD_GAS_CEILING: bigint;
 /** Headroom on eth_estimateGas (25%). */
 export declare const MINT_UCD_ESTIMATE_MARGIN_BPS = 2500;
 /**
  * Returns gas limit with margin, capped, or null if estimateGas reverts/fails.
  */
-export declare function estimateContractCallGasWithMargin(provider: providers.Provider, from: string, to: string, data: string, marginBps: number, ceiling: BigNumber): Promise<BigNumber | null>;
-export declare function resolveEip1559FeeFields(provider: providers.Provider): Promise<{
-    maxFeePerGas: BigNumber;
-    maxPriorityFeePerGas: BigNumber;
+export declare function estimateContractCallGasWithMargin(provider: Provider, from: string, to: string, data: string, marginBps: number, ceiling: bigint): Promise<bigint | null>;
+export declare function resolveEip1559FeeFields(provider: Provider): Promise<{
+    maxFeePerGas: bigint;
+    maxPriorityFeePerGas: bigint;
 }>;
 export declare function sendEip1559Transaction(params: {
     signer: Signer;
     to: string;
     data: string;
-    gasLimit: BigNumber;
-}): Promise<ethers5.providers.TransactionResponse>;
+    gasLimit: bigint;
+}): Promise<TransactionResponse>;

package/dist/utils/eip712-login.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Build + sign the `DhServerLogin` EIP-712 envelope the lit-ops-server's
+ * `POST /api/auth/login` route expects. Used by both the CLI helper and
+ * frontends that consume the SDK directly.
+ */
+import { Signer, TypedDataField } from "ethers";
+export interface DhServerLoginMessage {
+    address: string;
+    issuedAt: number;
+    nonce: string;
+}
+export interface DhServerLoginPayload {
+    chainId: number;
+    message: DhServerLoginMessage;
+    signature: string;
+}
+export declare function buildLoginDomain(chainId: number): {
+    name: string;
+    version: string;
+    chainId: number;
+};
+export declare const LOGIN_TYPES: Record<string, TypedDataField[]>;
+/**
+ * Sign a fresh login envelope. Caller POSTs the returned `payload` to the
+ * server's `/api/auth/login` route.
+ */
+export declare function buildSignedLoginPayload(signer: Signer, chainId: number): Promise<DhServerLoginPayload>;

package/dist/utils/extend-authorization.utils.d.ts

@@ -4,7 +4,7 @@
  * Generates authorization signatures for extend position requests
  * that can be verified by the extend-position-validator LIT Action.
  */
-import { ethers as ethers5 } from "ethers";
+import { type Wallet } from "ethers";
 /**
  * Extend Owner Authorization Interface (matches lit-actions)
  */
@@ -55,7 +55,7 @@ export declare function buildExtendAuthorizationHash(positionId: string, newTerm
  * @param signerOrPrecomputed - Either an ethers Wallet (EOA) or { timestamp, signature } for smart contract wallets
  * @returns Authorization object with signature
  */
-export declare function generateExtendAuthorization(positionId: string, newTerm: number, chainId: number, signerOrPrecomputed: ethers5.Wallet | {
+export declare function generateExtendAuthorization(positionId: string, newTerm: number, chainId: number, signerOrPrecomputed: Wallet | {
     timestamp: number;
     signature: string;
 }): Promise<ExtendOwnerAuthorization>;

package/dist/utils/mint-authorization.utils.d.ts

@@ -5,7 +5,7 @@
  * that can be verified by the ucd-mint-validator LIT Action.
  * Also includes withdrawal authorization utilities.
  */
-import { ethers as ethers5 } from "ethers";
+import { type Provider, type Signer } from "ethers";
 /**
  * Owner Authorization Interface (matches lit-actions)
  */
@@ -58,7 +58,7 @@ export declare function buildMintAuthorizationHash(positionId: string, amount: b
  * @param signerOrPrecomputed - Either an ethers Signer (EOA) or { timestamp, signature } for smart contract wallets
  * @returns Authorization object with signature
  */
-export declare function generateMintAuthorization(positionId: string, amount: bigint, chainId: number, signerOrPrecomputed: ethers5.Signer | {
+export declare function generateMintAuthorization(positionId: string, amount: bigint, chainId: number, signerOrPrecomputed: Signer | {
     timestamp: number;
     signature: string;
 }): Promise<MintOwnerAuthorization>;
@@ -113,7 +113,7 @@ export interface BalanceConfirmationAuthorization {
  * - Signer address is recovered from signature by LIT Action
  * - LIT Action validates recovered address === position owner
  */
-export declare function generatePaymentAuthorization(positionId: string, amount: bigint, chainId: number, signer: ethers5.Signer): Promise<PaymentOwnerAuthorization>;
+export declare function generatePaymentAuthorization(positionId: string, amount: bigint, chainId: number, signer: Signer): Promise<PaymentOwnerAuthorization>;
 /**
  * Generate extend position authorization signature
  *
@@ -131,7 +131,7 @@ export declare function generatePaymentAuthorization(positionId: string, amount:
  * - Signer address is recovered from signature by LIT Action
  * - LIT Action validates recovered address === position owner
  */
-export declare function generateExtendAuthorization(positionId: string, selectedTerm: number, chainId: number, signer: ethers5.Signer): Promise<ExtendOwnerAuthorization>;
+export declare function generateExtendAuthorization(positionId: string, selectedTerm: number, chainId: number, signer: Signer): Promise<ExtendOwnerAuthorization>;
 /**
  * Optional Chipotle service fallback for `getPKPPublicKeyFromTokenId`.
  *
@@ -143,7 +143,8 @@ export declare function generateExtendAuthorization(positionId: string, selected
  */
 export interface ChipotleServiceFallback {
     serviceEndpoint: string;
-    serviceAuthToken?: string;
+    /** Returns `Authorization`-style headers for the lit-ops-server request. */
+    getAuthHeader?: () => Promise<Record<string, string>>;
     borrowerAddress?: string;
     timeoutMs?: number;
     debug?: boolean;
@@ -165,7 +166,7 @@ export interface ChipotleServiceFallback {
  * @param chipotleFallback - Service-mode fallback used when pkpTokenId is a Chipotle id
  * @returns PKP public key as hex string with '0x' prefix
  */
-export declare function getPKPPublicKeyFromTokenId(pkpTokenId: string, provider?: ethers5.providers.Provider, pkpNftContractAddress?: string, chipotleFallback?: ChipotleServiceFallback): Promise<string>;
+export declare function getPKPPublicKeyFromTokenId(pkpTokenId: string, provider?: Provider, pkpNftContractAddress?: string, chipotleFallback?: ChipotleServiceFallback): Promise<string>;
 /**
  * Withdraw Owner Authorization Interface (matches lit-actions)
  */
@@ -218,7 +219,7 @@ export declare function buildWithdrawAuthorizationHash(positionId: string, amoun
  * @returns Authorization object with signature
  */
 export declare function generateWithdrawAuthorization(positionId: string, amount: bigint, // satoshis
-chainId: number, signerOrPrecomputed: ethers5.Signer | {
+chainId: number, signerOrPrecomputed: Signer | {
     timestamp: number;
     signature: string;
 }, destinationAddress: string): Promise<WithdrawOwnerAuthorization>;
@@ -244,4 +245,4 @@ chainId: number, signerOrPrecomputed: ethers5.Signer | {
  * @param signer - Ethereum signer to sign with (the caller)
  * @returns Authorization object with signature
  */
-export declare function generateBalanceConfirmationAuthorization(positionId: string, chainId: number, signer: ethers5.Signer): Promise<BalanceConfirmationAuthorization>;
+export declare function generateBalanceConfirmationAuthorization(positionId: string, chainId: number, signer: Signer): Promise<BalanceConfirmationAuthorization>;

package/dist/utils/position-delegate.utils.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Position Delegate Utilities
+ *
+ * Helpers for registering an off-chain authorization delegate on a position.
+ * The delegate lets a Safe-as-borrower delegate LIT Action auth signing to a
+ * hot agent EOA without making that EOA a Safe owner. The delegate is read by
+ * the LIT Action authorization verifier as a third recovery arm after the
+ * EOA `position.borrower` check and the EIP-1271 smart-account fallback.
+ *
+ * State lives on `PositionDelegateRegistry` (a standalone contract), not on
+ * PositionManager — PositionManager is at the 24 KiB Spurious Dragon limit
+ * and cannot carry the additional storage + setter without going over.
+ */
+import { type Signer, type Provider, type TransactionResponse } from "ethers";
+/**
+ * Register (or revoke) the off-chain authorization delegate for a position.
+ *
+ * Must be called by the position's current `borrower` — for Safe-as-borrower
+ * setups, that means the call must go through `safe.execTransaction(...)` or
+ * `agentModule.execute(...)` so that `msg.sender` at the registry equals the
+ * Safe. Pass `ethers.constants.AddressZero` as `delegate` to revoke.
+ *
+ * @param positionId Position identifier (bytes32).
+ * @param delegate New delegate EOA, or zero address to clear.
+ * @param signer Ethers signer that will be `msg.sender` at the registry.
+ * @param registryAddress Deployed `PositionDelegateRegistry` address for the chain.
+ * @returns The submitted transaction response.
+ */
+export declare function setPositionDelegate(positionId: string, delegate: string, signer: Signer, registryAddress: string): Promise<TransactionResponse>;
+/**
+ * Read the currently registered delegate for a position.
+ *
+ * Returns the zero address when no delegate has been registered. Pure view;
+ * any provider works (signer not required).
+ *
+ * @param positionId Position identifier (bytes32).
+ * @param provider Ethers provider or signer.
+ * @param registryAddress Deployed `PositionDelegateRegistry` address.
+ * @returns The delegate EOA, or zero address if none.
+ */
+export declare function getPositionDelegate(positionId: string, provider: Provider | Signer, registryAddress: string): Promise<string>;

package/dist/utils/server-session.d.ts

@@ -0,0 +1,44 @@
+/**
+ * In-memory session JWT manager for lit-ops-server.
+ *
+ * The server's `POST /api/auth/login` route accepts an EIP-712-signed
+ * `DhServerLogin` envelope and returns an HS256 JWT with a 15-minute TTL.
+ * This helper:
+ *
+ *   - caches the JWT until ~30s before expiry,
+ *   - coalesces concurrent callers behind a single in-flight Promise so we
+ *     don't spam `/api/auth/login` on parallel SDK calls,
+ *   - exposes `getValidToken()` returning the live token and
+ *     `getAuthHeader()` returning a ready-to-spread `{ Authorization: ... }`
+ *     object.
+ *
+ * Browser-safe — no filesystem touches. The CLI mirrors this shape but
+ * persists to `~/.diamond-hands/session.json` for cross-invocation reuse.
+ */
+import type { Signer } from "ethers";
+export interface ServerSessionOptions {
+    signer: Signer;
+    serviceEndpoint: string;
+    chainId: number;
+    /** Override for tests. */
+    now?: () => number;
+    /** Override for tests. */
+    fetchImpl?: typeof fetch;
+}
+export declare class ServerSession {
+    private readonly signer;
+    private readonly serviceEndpoint;
+    private readonly chainId;
+    private readonly now;
+    private readonly fetchImpl;
+    private cached;
+    private inFlight;
+    constructor(opts: ServerSessionOptions);
+    /** Returns a JWT good for at least `REFRESH_LEEWAY_SECONDS` more seconds. */
+    getValidToken(): Promise<string>;
+    /** Convenience for fetch: spread directly into `headers`. */
+    getAuthHeader(): Promise<Record<string, string>>;
+    /** Drop the cached token (e.g. on 401 from server). Next call re-logs in. */
+    clear(): void;
+    private getOrRefresh;
+}

package/dist/utils/signature-tempering.utils.d.ts

@@ -1,10 +1,13 @@
 /**
  * Signature Tempering Utility
  *
- * Security testing tool to intentionally corrupt signatures
- * to prove that smart contracts properly validate and reject invalid signatures.
+ * Security testing tool to intentionally corrupt signatures so tests can prove
+ * the on-chain validator rejects invalid signatures.
  *
- * WARNING: This is for TESTING ONLY. Tempered signatures will cause transactions to FAIL.
+ * WARNING: TESTING ONLY. `maybeTemperSignature` refuses to corrupt signatures
+ * when `NODE_ENV === "production"`, regardless of the config flag. The previous
+ * behavior (any caller could flip `temperSignaturesTest: true` to corrupt every
+ * signature) was an audit finding — the function is now defense-in-depth.
  */
 /**
  * Tempers a signature by modifying the 3rd character with a random valid hex character