@gvnrdao/dh-sdk 0.0.337 → 0.0.338

package/dist/utils/borrower-authorization-712.d.ts

@@ -26,7 +26,7 @@
  * data (instead of `personal_sign` over a precomputed keccak digest) is what
  * lets MetaMask render `RepayRequest { positionId, paymentAmount,
  * quantumTimestamp }` instead of an opaque 32-byte hex string. The ERC-7730
- * descriptor (`clear-signing/pending/eip712-LoanOperationsManager.json`) keys
+ * descriptor (`clear-signing/registry/diamond-hands/eip712-LoanOperationsManager.json`) keys
  * its formats by these `encodeType` strings verbatim.
  *
  * No Solidity contract recomputes these digests: the borrower signature is

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

@@ -10,6 +10,15 @@ export interface DhServerLoginMessage {
     nonce: string;
     /** Audit M-8: service endpoint URL this login targets (replay-binds to one service). */
     audience?: string;
+    /**
+     * Human-readable sentence the wallet renders on the signing prompt instead of four
+     * opaque machine fields. Opt-in — see `buildSignedLoginPayload`'s `withStatement`.
+     *
+     * NOT free text: the servers rebuild the expected value from the allowlisted
+     * `audience` and reject anything else, so it must come from
+     * `canonicalLoginStatement`.
+     */
+    statement?: string;
 }
 export interface DhServerLoginPayload {
     chainId: number;
@@ -24,6 +33,20 @@ export declare function buildLoginDomain(chainId: number): {
 export declare const LOGIN_TYPES: Record<string, TypedDataField[]>;
 /** Audit M-8: login types with the audience binding. */
 export declare const LOGIN_TYPES_WITH_AUDIENCE: Record<string, TypedDataField[]>;
+/**
+ * Login types carrying the human-readable `statement` as well.
+ *
+ * `statement` is FIRST because signing UIs render struct members in declaration order
+ * and the prose is what the user actually reads. The position is hashed into the
+ * typeHash, so this order is consensus with both servers, not formatting.
+ */
+export declare const LOGIN_TYPES_WITH_STATEMENT: Record<string, TypedDataField[]>;
+/**
+ * The statement to sign alongside `audience`, or null when the audience has no host
+ * (in which case the caller must sign the shape without a statement — a statement the
+ * server cannot rebuild is a signature it will reject).
+ */
+export declare function canonicalLoginStatement(audience: string): string | null;
 /**
  * Sign a fresh login envelope. Caller POSTs the returned `payload` to the
  * server's `/api/auth/login` route.
@@ -43,4 +66,14 @@ export declare function buildSignedLoginPayload(signer: Signer, chainId: number,
 reuse?: {
     issuedAt: number;
     nonce: string;
-}): Promise<DhServerLoginPayload>;
+}, 
+/**
+ * Add the human-readable `statement` the wallet renders on the prompt. OFF by default:
+ * it changes the digest, so a client that opts in requires servers that already accept
+ * the statement-bearing shape. The headless consumers (CLI, MCP, dh-cr-monitor) have no
+ * signing UI to improve and should leave it off; a browser passes true.
+ *
+ * Ignored without an `audience` — the servers derive the expected text from the
+ * audience host, so a statement they cannot rebuild is a signature they will reject.
+ */
+withStatement?: boolean): Promise<DhServerLoginPayload>;

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

@@ -71,6 +71,21 @@ export declare function sessionStoreKey(address: string, chainId: number, endpoi
 export interface PendingLoginEnvelope {
     issuedAt: number;
     nonce: string;
+    /**
+     * Whether the envelope this record stands for was signed WITH the human-readable
+     * statement.
+     *
+     * Part of the record because it is part of the DIGEST, not incidental metadata.
+     * A Safe identifies a queued message purely by its EIP-712 hash, and the presence
+     * of `statement` selects the field set — so replaying this nonce under the other
+     * shape produces a DIFFERENT hash, which Safe shows as a new message needing its
+     * FIRST signature. Every owner signature already collected is orphaned, and a
+     * 2-of-N can never reach threshold.
+     *
+     * Absent on records written before statements existed, which reads as `false` —
+     * correct, because that is exactly what those envelopes were signed as.
+     */
+    withStatement?: boolean;
 }
 /**
  * How long an unsigned envelope stays reusable FOR A CONTRACT WALLET. Must stay

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

@@ -45,6 +45,17 @@ export interface ServerSessionOptions {
      * (CLI, MCP, cr-monitor) omit it and keep the endpoint binding unchanged.
      */
     loginAudience?: string;
+    /**
+     * Add the human-readable `statement` to the login envelope — the sentence a
+     * wallet renders instead of four opaque fields.
+     *
+     * OFF by default. `statement` changes the EIP-712 digest and the server picks
+     * its field set by presence alone, so sending one to a server that predates it
+     * fails EVERY login. Only a caller that knows the server accepts statements
+     * (a browser reading the capability flag) should turn this on. Ignored without
+     * `loginAudience`, since the expected text is derived from the audience host.
+     */
+    withStatement?: boolean;
     /**
      * Fires immediately before a wallet signature is requested — i.e. only when
      * neither the cached JWT nor the persisted envelope could renew the session,
@@ -86,6 +97,8 @@ export declare class ServerSession {
     private readonly signer;
     private readonly serviceEndpoint;
     private readonly loginAudience;
+    /** Whether this session's login carries the human-readable statement. */
+    private readonly withStatement;
     private readonly chainId;
     private readonly store;
     private readonly onSignaturePrompt?;

package/dist/utils/sign-guard/errors.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The one error the sign-guard raises when it refuses to let bytes reach a key.
+ *
+ * Exported from exactly one SDK entry (`@gvnrdao/dh-sdk/sign-guard`) so
+ * `instanceof` checks in consumers cannot split across two module realms.
+ */
+export declare class TxValidationError extends Error {
+    constructor(msg: string);
+}

package/dist/utils/sign-guard/extend-fee-bound.d.ts

@@ -0,0 +1,15 @@
+import { ethers } from "ethers";
+import type { ContractRegistry } from "./tx-validator";
+export interface ExtendFeeBound {
+    ucdDebt: bigint;
+    extensionFeeRateBps: bigint;
+    upperBoundFeeWei: bigint;
+}
+/**
+ * Best-effort: returns `null` if a required address is missing or a read
+ * fails, and reports WHY through `onDegraded`. Callers should surface the
+ * degrade and sign with the on-chain validator signature as the only fee
+ * binder rather than block the user — a borrower who cannot renew risks
+ * liquidation.
+ */
+export declare function computeExtendFeeUpperBound(provider: ethers.Provider, contracts: ContractRegistry, positionId: string, selectedTerm: number, onDegraded?: (reason: string) => void): Promise<ExtendFeeBound | null>;

package/dist/utils/sign-guard/fee-ceiling.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Upper bounds on what a client is willing to sign.
+ *
+ * The calldata whitelist pins *what* is called; these pin what it may cost.
+ * The EOA path signs a server's `gasLimit` / `maxFeePerGas` verbatim, and
+ * neither the on-chain validator signature nor the calldata whitelist covers
+ * fee fields — so without this a compromised lit-ops-server could return a
+ * perfectly-pinned `mintUCD` carrying `gasLimit: 30_000_000` at 5000 gwei
+ * (~150 ETH) and the client would sign it. The calldata would be exactly what
+ * the user approved; the cost would not be.
+ *
+ * The worst-case total is the binding constraint — the two component rails
+ * are sanity checks on the individual fields. Real protocol calls land around
+ * 500k gas, so even a 200 gwei congestion spike costs ~0.1 ETH.
+ */
+export declare const MAX_GAS_LIMIT = 5000000n;
+export declare const MAX_FEE_PER_GAS_WEI = 2000000000000n;
+export declare const DEFAULT_MAX_TX_FEE_WEI = 250000000000000000n;
+export interface FeeCeiling {
+    maxGasLimit: bigint;
+    maxFeePerGasWei: bigint;
+    /** Worst-case `gasLimit × maxFeePerGas` a single tx may authorize. */
+    maxTxFeeWei: bigint;
+    /**
+     * Appended to the worst-case refusal so the user learns how THIS client lets
+     * them raise the ceiling (the CLI names `DH_MAX_TX_FEE_ETH`). The SDK has no
+     * opinion on where the override lives — that is consumer configuration.
+     */
+    raiseHint?: string;
+}
+export declare const DEFAULT_FEE_CEILING: FeeCeiling;
+/** Worst-case fee a tx can cost: gasLimit × the highest per-gas price it authorizes. */
+export declare function worstCaseFeeWei(gasLimit: bigint | null, maxFeePerGas: bigint | null): bigint | null;
+/**
+ * Call `raise` if a transaction's fee parameters exceed the ceiling.
+ *
+ * Absent fields are not an error — ethers/the provider populates them later,
+ * and callers re-assert the ceiling after that happens.
+ */
+export declare function assertFeeCeiling(gasLimit: bigint | null, maxFeePerGas: bigint | null, raise: (msg: string) => never, ceiling?: FeeCeiling): void;

package/dist/utils/sign-guard/index.d.ts

@@ -0,0 +1,9 @@
+export { TxValidationError } from "./errors";
+export { SIGNABLE_FUNCTIONS, encodeSignable, decodeSignable, signableFunctionName, signableSelectors, } from "./signable-functions";
+export { MAX_GAS_LIMIT, MAX_FEE_PER_GAS_WEI, DEFAULT_MAX_TX_FEE_WEI, DEFAULT_FEE_CEILING, worstCaseFeeWei, assertFeeCeiling, type FeeCeiling, } from "./fee-ceiling";
+export { validateUnsignedTx, buildValidationContext, describeUnsignedTx, readTxFeeFields, type ExpectedAction, type ContractRegistry, type ValidationContext, } from "./tx-validator";
+export { QUANTUM_SECONDS, AUTH_VALIDITY_WINDOWS, authValiditySec, nextQuantumTimestamp, isAuthFresh, isStrictCurrentQuantum, modeForChainId, randomNonceHex, OP_ENVELOPE_LAYOUT, OP_ENVELOPE_TYPES, OP_ENVELOPE_FIELD_ORDER, stampOpEnvelope, buildAuthEnvelope, type OpEnvelopeInput, type StampedOpEnvelope, type AuthEnvelope, } from "./op-envelope";
+export { DELEGATED_OPS, BROADCAST_PATH, type DelegatedOp, type DelegatedOpSpec } from "./op-specs";
+export { REQUEST_TIMEOUT_MS, LitOpsHttpError, LitOpsTransportError, fetchWithTimeout, postJson, asEnvelope, authorizeWithServer, broadcastSignedTx, type FetchOptions, type ExecuteEnvelope, type BroadcastEnvelope, type ExecuteOutcome, type BroadcastOutcome, } from "./lit-ops-client";
+export { signAndBroadcast, type SignGuardSigner } from "./sign-and-broadcast";
+export { computeExtendFeeUpperBound, type ExtendFeeBound } from "./extend-fee-bound";

package/dist/utils/sign-guard/lit-ops-client.d.ts

@@ -0,0 +1,107 @@
+import type { AuthEnvelope } from "./op-envelope";
+/**
+ * The transport half of the server-delegated pipeline: POST to lit-ops-server
+ * with a timeout, turn the three classic failure modes into legible errors
+ * (a stalled connection, a non-2xx with an HTML body, a 200 that is not JSON),
+ * and narrow the untrusted envelope.
+ *
+ * `fetchImpl` is the test seam (precedent: `server-session.ts`). Login is NOT
+ * here — callers pass already-authenticated `headers`; how a session is
+ * obtained and persisted is consumer policy.
+ */
+/** Default network timeout for lit-ops-server calls. */
+export declare const REQUEST_TIMEOUT_MS = 60000;
+export interface FetchOptions {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+/** A non-2xx response. Branch on `status`, never on message text. */
+export declare class LitOpsHttpError extends Error {
+    readonly status: number;
+    readonly url: string;
+    readonly body: string;
+    constructor(url: string, status: number, body: string);
+}
+/** The connection could not be made at all (DNS, refused, reset). Distinct from a timeout. */
+export declare class LitOpsTransportError extends Error {
+    readonly url: string;
+    constructor(url: string, cause: Error);
+}
+/**
+ * `fetch` with an abort-based timeout so a server that accepts the connection
+ * then stalls cannot hang the caller indefinitely.
+ */
+export declare function fetchWithTimeout(url: string, init: RequestInit, timeoutMs?: number, fetchImpl?: typeof fetch): Promise<Response>;
+/** Status-aware JSON POST. Throws `LitOpsHttpError` on non-2xx, `LitOpsTransportError` on no connection. */
+export declare function postJson<T>(url: string, body: unknown, headers: Record<string, string>, opts?: FetchOptions): Promise<T>;
+/** The per-action `execute` envelope, after runtime checking. */
+export interface ExecuteEnvelope {
+    success: boolean;
+    data?: {
+        approved?: boolean;
+        unsignedTx?: Record<string, unknown>;
+        error?: string;
+        [key: string]: unknown;
+    };
+    error?: string;
+}
+export interface BroadcastEnvelope {
+    success: boolean;
+    data?: {
+        txHash?: string;
+        blockNumber?: number;
+    };
+    error?: string;
+}
+/**
+ * Narrow an untrusted server response to the envelope shape.
+ *
+ * Deliberately shallow: it verifies the envelope is an object with the fields
+ * the pipeline branches on, and leaves the security-critical values (calldata,
+ * target, amounts) to `validateUnsignedTx`, which pins them against what the
+ * user authorized. A schema library would add a dependency without moving that
+ * boundary.
+ */
+export declare function asEnvelope(raw: unknown, label: string): ExecuteEnvelope & BroadcastEnvelope;
+export interface ExecuteOutcome {
+    data: NonNullable<ExecuteEnvelope["data"]>;
+    unsignedTx: Record<string, unknown>;
+}
+/**
+ * POST the signed auth envelope to the op's execute route and enforce the
+ * approval gates. Returns a discriminated failure rather than throwing so
+ * callers keep their `{ success: false, error }` result shape.
+ */
+export declare function authorizeWithServer(opts: {
+    serviceEndpoint: string;
+    executePath: string;
+    envelope: AuthEnvelope;
+    /** Already-authenticated headers (e.g. the lit-ops-server Bearer JWT). */
+    headers: Record<string, string>;
+    /** Used when the server refuses without saying why. */
+    refusalMessage: string;
+} & FetchOptions): Promise<{
+    ok: true;
+    outcome: ExecuteOutcome;
+} | {
+    ok: false;
+    error: string;
+}>;
+export interface BroadcastOutcome {
+    transactionHash?: string;
+    blockNumber?: number;
+}
+/** Relay a signed tx through lit-ops-server. */
+export declare function broadcastSignedTx(opts: {
+    serviceEndpoint: string;
+    headers: Record<string, string>;
+    signedTx: string;
+    /** Merged into the broadcast body, e.g. `{ mintMeta }`. */
+    meta?: Record<string, unknown>;
+} & FetchOptions): Promise<{
+    ok: true;
+    outcome: BroadcastOutcome;
+} | {
+    ok: false;
+    error: string;
+}>;

package/dist/utils/sign-guard/op-envelope.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Quantum-window timing, replay nonces and the borrower authorization
+ * envelope for the server-delegated protocol actions (mint / repay / renew).
+ *
+ * These helpers were duplicated across the CLI (`util/quantum.ts`) and the MCP
+ * (`boundary/upstream/shared/quantum.ts`) because the SDK owned the canonical
+ * quantum logic internally without exporting it. One copy now.
+ */
+/** Quantum window width in seconds — matches the on-chain / LIT-action window. */
+export declare const QUANTUM_SECONDS = 60;
+/** Borrower authorizations are valid for this many windows (past, current, next). */
+export declare const AUTH_VALIDITY_WINDOWS = 3;
+export declare function authValiditySec(): number;
+/**
+ * The NEXT quantum boundary, in seconds.
+ *
+ * Audit M-C: signing against the *current* boundary leaves almost no time for
+ * the round-trip when the call lands late in a window, so the authorization
+ * can expire before the tx is mined. Sitting exactly on a boundary must still
+ * advance, or the authorization is born at the edge of its window.
+ */
+export declare function nextQuantumTimestamp(nowMs?: number): number;
+/** General ops (mint/repay/extend): issued within the last 3 windows and never in the future. */
+export declare function isAuthFresh(issuedAtSec: number, nowSec: number): boolean;
+/** Withdrawal (`strictCurrentQuantum`): issued in the SAME quantum window as now. */
+export declare function isStrictCurrentQuantum(issuedAtSec: number, nowSec: number): boolean;
+/** lit-ops-server environment selector. Mainnet is the only `prod` chain. */
+export declare function modeForChainId(chainId: number): string;
+/**
+ * Replay nonce for an auth envelope.
+ *
+ * Width is a parameter only because the two envelopes on the wire differ: the
+ * protocol-action envelopes use 16 bytes and the `DhServerLogin` envelope uses
+ * 32. Both are far beyond any collision concern; the parameter exists to unify
+ * the implementation without changing either wire format.
+ */
+export declare function randomNonceHex(byteLength?: number): string;
+/**
+ * The packed personal-sign layout of the operation envelope. The MCP's approval
+ * page recomputes this hash in the browser from the displayed fields
+ * (`PERSONAL_SIGN_LAYOUTS["dh-op-envelope-v1"]`); the two MUST agree
+ * byte-for-byte, and `tests/shared/unit/sign-guard/op-envelope.test.ts` pins
+ * a golden vector so the wire format cannot move silently.
+ */
+export declare const OP_ENVELOPE_LAYOUT = "dh-op-envelope-v1";
+export declare const OP_ENVELOPE_TYPES: readonly ["bytes32", "uint256", "uint256", "uint256", "bytes32"];
+export declare const OP_ENVELOPE_FIELD_ORDER: readonly ["positionId", "timestamp", "chainId", "amount", "action"];
+export interface OpEnvelopeInput {
+    positionId: string;
+    chainId: number;
+    /** uint256 slot 4 of the envelope: the amount in wei for mint/repay, the term count for renew. */
+    value: bigint | number;
+    action: string;
+}
+export interface StampedOpEnvelope {
+    /** Human-readable fields in layout order — what an approval surface displays. */
+    fields: Record<(typeof OP_ENVELOPE_FIELD_ORDER)[number], string>;
+    /** `keccak256(abi.encodePacked(positionId, timestamp, chainId, amount, keccak256(action)))`. */
+    hashHex: string;
+}
+/** Stamp the envelope for one candidate quantum timestamp (re-stampable at the human's click). */
+export declare function stampOpEnvelope(input: OpEnvelopeInput, quantumTs: number): StampedOpEnvelope;
+export interface AuthEnvelope {
+    authMessage: Record<string, unknown>;
+    userSignature: string;
+    borrowerAddress: string;
+}
+/**
+ * Build and sign the off-chain authorization the LIT Action verifies.
+ *
+ * Signer-agnostic on purpose: the CLI and the MCP each have their own
+ * `DHSigner` shape, so this takes a `signAuthMessage(hash)` callback. In EOA
+ * mode the borrower signs directly; in Safe mode the agent EOA signs and the
+ * LIT Action accepts it via `positionDelegate(positionId)`.
+ *
+ * `payload` carries the value under whatever key that action's server endpoint
+ * expects (`DELEGATED_OPS[op].payloadKey`).
+ */
+export declare function buildAuthEnvelope(opts: {
+    signAuthMessage: (messageHash: string) => Promise<string>;
+    borrowerAddress: string;
+    chainId: number;
+    positionId: string;
+    action: string;
+    value: bigint | number;
+    payload: Record<string, unknown>;
+    nowMs?: number;
+}): Promise<AuthEnvelope>;

package/dist/utils/sign-guard/op-specs.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The three server-delegated operations, as DATA.
+ *
+ * Audit CRIT-5: the CLI sent the wrong action string for repayment for months
+ * ("partial-payment" instead of "make-payment") because the string lived in
+ * one of three near-identical copies and only one was corrected. Every
+ * consumer now reads the action string, the execute path, the payload key and
+ * the broadcast meta key from here, so there is nothing left to correct twice.
+ *
+ * Action strings must match what the corresponding validator Lit Action pins
+ * (`PARTIAL_PAYMENT_ACTION_STRING = "make-payment"` in lit-actions; see also
+ * `sdk/src/utils/mint-authorization.utils.ts`).
+ */
+export interface DelegatedOpSpec {
+    /** The `action` field of the signed envelope — what the LIT Action pins. */
+    readonly action: string;
+    /** lit-ops-server route that runs the LIT Action and returns the unsigned tx. */
+    readonly executePath: `/api/lit/${string}/execute`;
+    /** Key the server expects the value under in `authMessage`. */
+    readonly payloadKey: string;
+    /** Key the broadcast body carries the op's metadata under. */
+    readonly broadcastMetaKey: string;
+    /** Used when the server refuses without saying why. */
+    readonly refusalMessage: string;
+}
+export declare const DELEGATED_OPS: {
+    readonly mint: {
+        readonly action: "mint-ucd";
+        readonly executePath: "/api/lit/mint/execute";
+        readonly payloadKey: "amount";
+        readonly broadcastMetaKey: "mintMeta";
+        readonly refusalMessage: "Mint authorization failed";
+    };
+    readonly repay: {
+        readonly action: "make-payment";
+        readonly executePath: "/api/lit/repay/execute";
+        readonly payloadKey: "paymentAmount";
+        readonly broadcastMetaKey: "repayMeta";
+        readonly refusalMessage: "Repay authorization failed";
+    };
+    readonly renew: {
+        readonly action: "extend-position";
+        readonly executePath: "/api/lit/renew/execute";
+        readonly payloadKey: "newTerm";
+        readonly broadcastMetaKey: "renewMeta";
+        readonly refusalMessage: "Renew authorization failed";
+    };
+};
+export type DelegatedOp = keyof typeof DELEGATED_OPS;
+/** lit-ops-server route every signed tx is relayed through. */
+export declare const BROADCAST_PATH = "/api/lit/broadcast";

package/dist/utils/sign-guard/sign-and-broadcast.d.ts

@@ -0,0 +1,56 @@
+import type { ethers } from "ethers";
+import { type ExpectedAction, type ValidationContext } from "./tx-validator";
+import { type BroadcastOutcome, type FetchOptions } from "./lit-ops-client";
+/**
+ * The minimum a signer must offer to take part in the pipeline. Both the CLI's
+ * and the MCP's `DHSigner` satisfy it structurally.
+ *
+ * `wrapInnerTx` is where Safe mode applies its `AgentModule.execute` envelope;
+ * EOA mode returns the tx unchanged.
+ */
+export interface SignGuardSigner {
+    wrapInnerTx(inner: ethers.TransactionRequest): Promise<ethers.TransactionRequest>;
+    signTransaction(tx: ethers.TransactionRequest): Promise<string>;
+}
+/**
+ * The only path from a server-returned tx to a signature.
+ *
+ * Order is load-bearing and is why this lives in ONE function, in the SDK,
+ * consumed by every client:
+ *   1. `validateUnsignedTx` pins the call against what the user authorized;
+ *   2. `beforeSign` lets the consumer render its pre-sign banner (a second,
+ *      independent decode gate) — it is the ONLY hook, and it runs after
+ *      validation so it can never be used to launder an unvalidated tx;
+ *   3. `wrapInnerTx` applies the Safe envelope AFTER validation, so wrapping
+ *      can never launder an unvalidated inner call;
+ *   4. only then is a key asked to sign;
+ *   5. the signed bytes are relayed through lit-ops-server.
+ *
+ * Deliberately two composable primitives (`authorizeWithServer` + this) rather
+ * than one configurable executor: a single executor taking eight hooks would
+ * relocate the divergence risk into hook implementations instead of removing
+ * it. Flow differences live in `DELEGATED_OPS` data and in the callers'
+ * `expected` objects, never in per-flow hooks.
+ */
+export declare function signAndBroadcast(opts: {
+    unsignedTx: Record<string, unknown>;
+    expected: ExpectedAction;
+    vctx: ValidationContext;
+    signer: SignGuardSigner;
+    /** Presentation only — runs after validation, before any key is touched. */
+    beforeSign?: (unsignedTx: Record<string, unknown>) => void;
+    broadcast: {
+        serviceEndpoint: string;
+        headers: Record<string, string>;
+        /** Merged into the broadcast body, e.g. `{ mintMeta }`. */
+        meta?: Record<string, unknown>;
+    } & FetchOptions;
+    /** Prefix for sign/broadcast errors, e.g. "UCD approve broadcast". */
+    errorPrefix?: string;
+}): Promise<{
+    ok: true;
+    outcome: BroadcastOutcome;
+} | {
+    ok: false;
+    error: string;
+}>;

package/dist/utils/sign-guard/signable-functions.d.ts

@@ -0,0 +1,41 @@
+import { ethers } from "ethers";
+/**
+ * The ONE whitelist of every function a Diamond Hands client is willing to
+ * sign on a borrower's behalf.
+ *
+ * History that explains why this lives in the SDK: the CLI and the MCP each
+ * carried a private copy of this list. They drifted in both directions — the
+ * MCP copy kept `repayPosition` (a function on no deployed contract, removed
+ * from the CLI in ccbe0e3fc) and gained the PSM pair; the CLI copy alone had a
+ * parity test against `AgentModule.sol`. Two consumers, one on-chain module,
+ * one parity test. Now there is one list, one decoder and one parity test
+ * (`tests/shared/unit/sign-guard/agent-module-whitelist.parity.test.ts`) that
+ * guards every consumer.
+ *
+ * Kept as a literal ABI array rather than derived from `POSITION_MANAGER_ABI`
+ * so that any new signable function requires an explicit, reviewed change to
+ * this file. `contracts/src/safe-modules/AgentModule.sol` states that its
+ * hardcoded whitelist MUST stay in lock-step with this array.
+ */
+export declare const SIGNABLE_FUNCTIONS: readonly ["function mintUCD(bytes32 positionId, uint256 mintAmount, uint256 mintFee, uint256 newDebt, uint256 newCollateral, uint256 btcPrice, bytes32 authorizedSpendsHash, bytes32 ucdDebtHash, bytes32 contractHash, uint256 quantumTimestamp, bytes calldata mintValidatorSignature) external returns (bool)", "function makePayment(bytes32 positionId, uint256 paymentAmount, uint256 quantumTimestamp, uint256 btcPrice, bytes calldata paymentValidatorSignature) external returns (bool)", "function extendPosition(bytes32 positionId, uint256 selectedTerm, uint256 quantumTimestamp, uint256 btcPrice, uint256 availableBTCBalance, uint256 proRataRenewalFee, bytes calldata extensionValidatorSignature) external returns (bool)", "function extendPosition(bytes32 positionId, uint256 selectedTerm, uint256 quantumTimestamp, uint256 btcPrice, uint256 availableBTCBalance, bytes calldata extensionValidatorSignature) external returns (bool)", "function withdrawBTC((bytes32 positionId, bytes32 actionHash, bytes32 authorizedSpendsHash, bytes32 ucdDebtHash, bytes32 contractBundleHash, string withdrawalAddress, uint256 totalDeduction, uint256 newCollateral, uint256 quantumTimestamp, uint256 btcPrice, string utxoTxid, uint32 utxoVout) params, bytes withdrawalValidatorSignature, bytes btcSpendAuthSignature) external returns (bool)", "function approve(address spender, uint256 amount) external returns (bool)", "function setPositionDelegate(bytes32 positionId, address newDelegate) external", "function createPosition(bytes32 pkpId, bytes calldata validatorSignature, string mainnetVaultAddress, string regtestVaultAddress, uint256 selectedTermMonths, uint256 validatorVersion, bytes calldata pkpPublicKey) external returns (bytes32 positionId)", "function swap(address stablecoin, uint256 amountIn, uint256 minUcdOut) external returns (uint256)", "function redeem(address stablecoin, uint256 ucdAmount, uint256 minStablecoinOut) external returns (uint256)", "function addAddress(string btcAddress) external"];
+/**
+ * Encode calldata through the SAME ABI surface `validateUnsignedTx` decodes
+ * against. Any synthesized tx (test doubles, mock upstreams) MUST use this and
+ * never its own Interface, so synthesized bytes cannot drift from the decode
+ * whitelist.
+ */
+export declare function encodeSignable(fn: string, args: unknown[]): string;
+/**
+ * Decode calldata against the whitelist — the ONLY decoder a human-facing
+ * approval surface may render from (decode-equivalence: what the human sees
+ * IS what the validator checks). Throws `TxValidationError` when the bytes do
+ * not match any signable function.
+ */
+export declare function decodeSignable(data: string): {
+    name: string;
+    args: ethers.Result;
+};
+/** Function name for display, or `"<unparseable>"`. Never throws. */
+export declare function signableFunctionName(data: string): string;
+/** Every selector the whitelist accepts, keyed by 4-byte selector → sighash form. */
+export declare function signableSelectors(): Map<string, string>;