@gvnrdao/dh-sdk 0.0.320 → 0.0.323

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

@@ -0,0 +1,154 @@
+/**
+ * "Is this Safe delegated, and to which agent?" — the single implementation.
+ *
+ * Every consumer that needs to know whether a multi-sig Safe can act through an
+ * AgentModule asks this: the frontend gate, the CLI, MCP. It was previously
+ * reimplemented per-consumer, and this session shows what that costs — the same
+ * invariant lived in two places twice, and both times only one copy was fixed
+ * when it turned out to be wrong.
+ *
+ * ── WHAT MAKES A DELEGATION REAL ───────────────────────────────────────────
+ * A module counts only when ALL of these hold:
+ *   - it is enabled on the Safe (`getModulesPaginated`)
+ *   - `safe()` is that Safe and `positionManager()` is this chain's
+ *   - `AgentModuleFactory.isFromFactory(module)` claims it
+ *
+ * That last one is not decoration. The agent-module-executor Lit Action refuses
+ * at its second guard to sign through any module the factory disowns, so an
+ * unprovenanced module is one nothing can ever use. Measured on the Sepolia test
+ * Safe (2026-08-05): it carried a pre-factory module from an old e2e harness,
+ * correctly bound and pointing at an EOA agent nothing could sign with — and
+ * without the provenance check it read as a working delegation.
+ *
+ * ── WHY THE ANSWER IS TRI-STATE ────────────────────────────────────────────
+ * `unknown` is not a rounding error, it is the whole safety property. Callers
+ * act on "not-delegated" by BLOCKING loan creation, so a check that merely
+ * failed to run must never produce it. The distinctions below are load-bearing
+ * and were each learned from a live failure:
+ *
+ *   - `safe()` unreadable        → unknown. Every module here answers it, so a
+ *                                  failure means we could not read, not that the
+ *                                  module is wrong.
+ *   - `positionManager()` absent → EVIDENCE. It is the discriminator (absent on
+ *                                  VaultProvisionerModule), so a revert is a real
+ *                                  answer: not an AgentModule.
+ *   - provenance unreadable      → unknown.
+ *   - no factory on this chain   → unknown, never "not-delegated". Mainnet has
+ *                                  no AgentModuleFactory, and reporting that as
+ *                                  not-delegated blocked vault creation behind a
+ *                                  ceremony that cannot run there at all.
+ *
+ * ── NOT A SUBSTITUTE FOR THE LIT ACTION'S OWN CHECKS ───────────────────────
+ * The executor re-derives provenance and the registry binding itself. It must:
+ * it is the enforcement point and cannot trust anything a caller computed.
+ * Sharing this code with it would weaken it, so it stays independent.
+ */
+import { type Provider } from "ethers";
+export type SafeDelegationStatus = "delegated" | "not-delegated" | "unknown";
+export interface SafeAgentDelegation {
+    /** Lowercased Safe the answer describes. */
+    safeAddress: string;
+    /** Chain the answer describes — a module on one chain says nothing about another. */
+    chainId: number;
+    status: SafeDelegationStatus;
+    /** The AgentModule, or null when there isn't one (or we could not tell). */
+    moduleAddress: string | null;
+    /**
+     * The agent EOA that SIGNS AND PAYS for delegated operations — read from the
+     * module, not the registry. They should agree, but the module's `agent()` is
+     * who `onlyAgent` actually admits, so it is the truth about who needs gas.
+     */
+    agentAddress: string | null;
+    /** Registry expiry for the Safe's agent record, when readable. */
+    validUntil: number | null;
+    /** True when the Safe's module list exceeded one page — the answer may be partial. */
+    truncated: boolean;
+}
+/**
+ * Resolve the Safe's agent delegation from chain state.
+ *
+ * `provider` is the CALLER'S, deliberately: it must read the chain the caller is
+ * actually on. Resolving it internally would let an SDK configured for one chain
+ * answer about another, which is the exact confusion that made a live Sepolia
+ * delegation look absent while the wallet had silently defaulted to mainnet.
+ *
+ * Never throws — every failure resolves to `unknown`.
+ */
+export declare function getSafeAgentDelegation(params: {
+    safeAddress: string;
+    chainId: number;
+    provider: Provider;
+}): Promise<SafeAgentDelegation>;
+/** One entry in a Safe transaction batch. */
+export interface SafeDelegationCall {
+    to: string;
+    data: string;
+    value: string;
+}
+export interface SafeAgentDelegationDisablePlan {
+    /**
+     * The calls, in execution order. They must land ATOMICALLY — see below for
+     * why a half-applied revocation is worse than none.
+     */
+    calls: SafeDelegationCall[];
+    /** The module being removed. */
+    moduleAddress: string;
+    /** The agent being revoked, when the module could name it. */
+    agentAddress: string | null;
+    /** The predecessor `disableModule` needs — SENTINEL when the module heads the list. */
+    prevModule: string;
+}
+/**
+ * Build the calls that undo a Safe's agent delegation.
+ *
+ * THE COUNTERPART TO {@link getSafeAgentDelegation}, and here rather than in any
+ * one consumer for the reason that reader is here: it needs the same module
+ * enumeration, and a second copy of that walk is how the two drift. The
+ * frontend, the CLI and MCP all revoke the same way or none of them can be
+ * trusted to.
+ *
+ * ── WHY TWO CALLS ──────────────────────────────────────────────────────────
+ * Neither alone is a full revocation:
+ *
+ *  - `revokeAgent` flips the registry record to Revoked, which is what the Lit
+ *    Action's `can*` gates read. After it, no mint/repay/renew/withdraw can be
+ *    authorized for this agent.
+ *  - `disableModule` removes the on-chain execution path, and it is the one
+ *    that matters for the calls needing NO validator attestation: with the
+ *    module still enabled, a live agent key can forward `approve` and
+ *    `setPositionDelegate` through the Safe whatever the registry says
+ *    (`AgentModule.execute` checks only `msg.sender == agent` and its own
+ *    selector whitelist).
+ *
+ * Submit them as ONE batch. Revoking the record while leaving the module
+ * enabled reads as "not delegated" everywhere in the UI while those unattested
+ * paths stay open — the worst of both states.
+ *
+ * ── WHAT IT DOES NOT UNDO ──────────────────────────────────────────────────
+ * A `setPositionDelegate` the agent already installed on PositionDelegateRegistry
+ * SURVIVES both calls (vigil C-43). Clearing that is per-position and is not
+ * part of this plan.
+ *
+ * THROWS, unlike `getSafeAgentDelegation` — the asymmetry is deliberate. That
+ * one answers a question and "unknown" is a usable answer. This one produces a
+ * transaction the Safe's owners must gather to sign, so a guess costs them an
+ * approval round on something that must revert. Every failure is loud:
+ *
+ *  - the chain has no AgentDelegationRegistry;
+ *  - the Safe's module list cannot be read (never guess a predecessor: a wrong
+ *    `prevModule` is Safe's GS103, AFTER the owners have signed);
+ *  - the module is not enabled on the Safe (the caller is acting on a stale
+ *    verdict).
+ *
+ * @param params.moduleAddress Optional. Supply the module from a verdict already
+ *        on screen so the transaction describes what the user was looking at;
+ *        omit it and the delegation is resolved here.
+ */
+export declare function buildSafeAgentDelegationDisableCalls(params: {
+    safeAddress: string;
+    chainId: number;
+    provider: Provider;
+    moduleAddress?: string;
+    /** bytes32 recorded against the revocation. Defaults to `bytes32("user-disabled")`. */
+    reason?: string;
+}): Promise<SafeAgentDelegationDisablePlan>;

package/dist/utils/withdrawal-reconciliation.utils.d.ts

@@ -3,23 +3,36 @@
  * (`BTCSpendAuthorizer.getAuthorizedSpends`) against BITCOIN truth before any
  * UI offers "Execute" or any server invokes the TEE signer.
  *
- * Why this exists (incident 2026-07-22, position 0x992d5c…): the contract can
- * never know whether a Phase-2 BTC broadcast happened, and a pre-P6/#8
- * authorization could record a `(vout, satoshis)` pair that never matched the
- * chain (declared 96,049 vs on-chain 33,000). Executing such an entry can only
- * die at the signer's parent-fetch guard; and an entry whose outpoint was
- * already spent paying the target is DONE and must auto-clear — while an
- * entry whose funding tx merely confirmed must NOT be cleared as "complete".
+ * `satoshis` semantics — AGGREGATE, by design: the authorized `satoshis` is
+ * the TOTAL input value the consolidation will consume across the vault's
+ * confirmed UTXO set (btc-withdrawal.ts signs `vaultSatoshis = newCollateral +
+ * totalDeduction`), while `(txid, vout)` pins ONE representative outpoint.
+ * `BTCSpendAuthorizer.sol` enforces `targetAmount < satoshis`
+ * (TargetMustLeaveFeeRoom) — a withdrawal near the vault's full balance could
+ * never be authorized against a single small outpoint's value, so the
+ * aggregate is structurally required. NEVER compare `satoshis` to the
+ * representative outpoint's own value: for any vault holding more than one
+ * UTXO they legitimately differ (incident 2026-08-07, position 0x992d5c…, a
+ * 4-UTXO vault whose valid authorization was misclassified as corrupt).
+ *
+ * What IS invariant, and what this module verifies:
+ * - the funding tx exists and is confirmed (else UNFUNDED);
+ * - the representative `vout` exists on that tx (else CORRUPT);
+ * - the output at `vout` pays the VAULT address, when the caller supplies it
+ *   (else CORRUPT — this is the real 2026-07-20 (vout, satoshis)-decoupling
+ *   bug class: a vout pointing at an output the vault does not own);
+ * - `targetAmount < satoshis`, mirroring the contract invariant (else CORRUPT);
+ * - the outpoint's spend state (EXECUTED / SPENT_MISMATCH / EXECUTABLE).
  *
  * Statuses:
- * - EXECUTABLE      — outpoint confirmed, unspent, values coherent → offer Execute.
+ * - EXECUTABLE      — outpoint confirmed, unspent, record coherent → offer Execute.
  * - EXECUTED        — outpoint spent by a tx that pays the authorized target →
  *                     auto-clear, show `spendingTxid` as the completion proof.
  * - SPENT_MISMATCH  — outpoint spent but the spending tx pays the target
  *                     nothing → unexecutable; recoverStaleSpend clears it.
- * - CORRUPT         — authorization contradicts the chain (declared value ≠
- *                     real output value, targetAmount > real value, or vout
- *                     out of range) → operator recovery (admin clearing path);
+ * - CORRUPT         — authorization contradicts the chain (vout out of range,
+ *                     output not owned by the vault, or targetAmount ≥
+ *                     satoshis) → operator recovery (admin clearing path);
  *                     never Execute.
  * - UNFUNDED        — funding tx unknown/unconfirmed → wait; no Execute yet.
  *
@@ -43,7 +56,11 @@ export interface ReconciledWithdrawal<T extends AuthorizedSpendLike = Authorized
     status: PendingWithdrawalStatus;
     /** Human-readable, single-sentence explanation of the classification. */
     reason: string;
-    /** Real value of the referenced outpoint, when the funding tx is known. */
+    /**
+     * Real value of the referenced outpoint, when the funding tx is known.
+     * Diagnostic only — for a multi-UTXO vault it is legitimately smaller than
+     * the aggregate `satoshis`.
+     */
     onChainOutputValue?: number;
     /** The verified spending tx, for EXECUTED / SPENT_MISMATCH. */
     spendingTxid?: string;
@@ -61,5 +78,14 @@ export type HttpGetJson = (url: string) => Promise<{
     body: unknown;
 }>;
 export declare const defaultHttpGetJson: HttpGetJson;
-/** Classify one authorized spend against the esplora at `esploraBaseUrl`. */
-export declare function reconcileAuthorizedSpend<T extends AuthorizedSpendLike>(spend: T, esploraBaseUrl: string, httpGetJson?: HttpGetJson): Promise<ReconciledWithdrawal<T>>;
+/**
+ * Classify one authorized spend against the esplora at `esploraBaseUrl`.
+ *
+ * `opts.vaultAddress` enables the vault-ownership check (the strongest guard
+ * against the (vout, satoshis)-decoupling bug class). When absent the check is
+ * SKIPPED, not assumed — production callers (lit-ops-server, frontend) must
+ * supply it.
+ */
+export declare function reconcileAuthorizedSpend<T extends AuthorizedSpendLike>(spend: T, esploraBaseUrl: string, httpGetJson?: HttpGetJson, opts?: {
+    vaultAddress?: string;
+}): Promise<ReconciledWithdrawal<T>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gvnrdao/dh-sdk",
-  "version": "0.0.320",
+  "version": "0.0.323",
   "description": "TypeScript SDK for Diamond Hands Protocol - Bitcoin-backed lending with LIT Protocol PKPs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -29,6 +29,11 @@
       "types": "./dist/deployments.d.ts",
       "import": "./dist/deployments.mjs",
       "require": "./dist/deployments.js"
+    },
+    "./safe-delegation": {
+      "types": "./dist/safe-delegation.d.ts",
+      "import": "./dist/safe-delegation.mjs",
+      "require": "./dist/safe-delegation.js"
     }
   },
   "files": [