@gvnrdao/dh-sdk 0.0.320 → 0.0.324

package/dist/interfaces/chunks/config.i.d.ts

@@ -48,6 +48,8 @@ export interface ContractAddresses {
     agentDelegationRegistry?: string;
     /** DHAgentDelegate; EIP-7702 execution adapter (Gate 2) the borrower EOA delegates to. Sepolia only. */
     dhAgentDelegate?: string;
+    /** AgentModuleFactory; CREATE2 factory a multi-sig Safe uses to deploy its own AgentModule in the delegation ceremony. Sepolia only. */
+    agentModuleFactory?: string;
     mockUsdcToken?: string;
     mockUsdcOwner?: string;
     mockUsdtToken?: string;

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

@@ -148,6 +148,98 @@ export declare class DiamondHandsSDK {
      * No-op in standalone mode (no server session to prime).
      */
     primeServerSession(payload: DhServerLoginPayload): Promise<void>;
+    /**
+     * Build the Safe-delegation ceremony for a multi-sig Safe (Phase 1 of
+     * multi-sig support): asks lit-ops-server to mint (or recover) the Safe's
+     * agent PKP and returns the exact call batch the Safe's owners must execute
+     * (AgentModuleFactory.deploy → safe.enableModule → registerAgent), derived
+     * from live chain state so a half-done ceremony resumes.
+     *
+     * Service-mode only — the server holds the Chipotle account that mints the
+     * PKP and it gates the route to current Safe owners. `knownAgentAddress` is
+     * the caller-persisted agent from an earlier prepare whose ceremony has not
+     * landed yet; echoing it back prevents a duplicate mint after a server
+     * restart.
+     */
+    prepareSafeAgentModule(request: {
+        safeAddress: string;
+        knownAgentAddress?: string;
+    }): Promise<{
+        status: "ready" | "already-delegated";
+        agentAddress: string;
+        moduleAddress: string;
+        validUntil: number | null;
+        calls: {
+            to: string;
+            data: string;
+            value: string;
+        }[];
+    }>;
+    /**
+     * Shared transport for `/agent-module/{authorize,execute}`.
+     *
+     * Both routes run the agent PKP's key inside a Lit Action, gated on the
+     * caller's session being a CURRENT Safe owner (M-8c). Service-mode only, for
+     * the same reason as {@link prepareSafeAgentModule}: the key lives in the
+     * server's Chipotle account and has no standalone equivalent.
+     */
+    private postAgentModuleRoute;
+    /**
+     * The agent signs the borrower authorization envelope for `op` on `positionId`.
+     *
+     * The returned `{ timestamp, signature }` feeds the SDK's PRECOMPUTED
+     * authorization path (`generateExtendAuthorization` and siblings) — the same
+     * path Safe/EIP-1271 borrowers already use. It is NOT a generic message
+     * signer: the Lit Action REBUILDS the envelope from these fields rather than
+     * signing anything the caller supplies, which is what stops a delegated agent
+     * key being turned into an arbitrary oracle.
+     *
+     * `timestamp` must be quantum-aligned by the caller
+     * (`calculateNextQuantumTimestamp()`) and must be the SAME value later passed
+     * to the protocol call, or the validator recovers a different signer.
+     */
+    agentModuleAuthorize(request: {
+        safeAddress: string;
+        positionId: string;
+        op: "mint" | "repay" | "renew" | "withdraw";
+        timestamp: number;
+        amount?: string;
+        selectedTerm?: number;
+    }): Promise<{
+        module: string;
+        agent: string;
+        authorization: {
+            timestamp: number;
+            signature: string;
+            signer: string;
+        };
+    }>;
+    /**
+     * The agent signs `module.execute(target, innerData)` as a raw EIP-1559
+     * transaction. Returns the SIGNED transaction — the caller broadcasts it, so
+     * the tx hash and receipt come from the caller's own provider.
+     *
+     * `tx` fields are caller-supplied because the Lit Action runs on many nodes
+     * and reconciles results: anything fetched in-action (nonce, gas) would
+     * differ per node and fail consensus.
+     */
+    agentModuleExecute(request: {
+        safeAddress: string;
+        positionId: string;
+        op: "mint" | "repay" | "renew" | "withdraw";
+        target: string;
+        innerData: string;
+        tx: {
+            nonce: number;
+            gasLimit: string;
+            maxFeePerGas: string;
+            maxPriorityFeePerGas: string;
+        };
+    }): Promise<{
+        module: string;
+        agent: string;
+        signedTransaction: string;
+    }>;
     /**
      * Audit H-9: invalidate the LoanQuery cache so subsequent reads return
      * the post-write state. We clear the entire loan-query cache (not just
@@ -448,6 +540,24 @@ export declare class DiamondHandsSDK {
      * address strings, query the subgraph `WithdrawalAddressBook`.
      */
     getApprovedWithdrawalAddresses(user?: string): Promise<Result<import("./withdrawal-address/withdrawal-address.module").WithdrawalAddressEntry[], SDKError>>;
+    /**
+     * Recover the revert reason of an already-mined, already-reverted transaction.
+     *
+     * A status-0 receipt carries no revert data, and ethers does not re-fetch it, so
+     * the reason has to be recovered by replaying the exact calldata as an `eth_call`
+     * pinned to the block that mined it — the only block whose `block.timestamp`
+     * reproduces a timing-dependent revert such as `DeadZoneViolation()`.
+     *
+     * Caveat: the replay runs against end-of-block state rather than the state at the
+     * transaction's own index, so for a state-dependent revert the recovered name is
+     * diagnostic, not proof. Timing reverts (the case this exists for) are unaffected —
+     * they depend only on the block timestamp.
+     *
+     * @returns the decoded error name, its raw selector if unknown, or `null` when the
+     *          replay yields no revert data at all (never throws — a failed diagnosis
+     *          must not mask the underlying failure).
+     */
+    private decodeMinedRevert;
     /**
      * Withdraw Bitcoin from a position
      *
@@ -509,6 +619,11 @@ export declare class DiamondHandsSDK {
      * The service path's post-broadcast CRIT-2 re-verification exists to catch
      * a LYING SERVER; here the broadcast happens locally from the signatures we
      * just obtained, so the esplora-returned txid is already first-hand.
+     *
+     * Multi-UTXO consolidation in standalone mode requires the caller to supply
+     * `request.utxos` explicitly — `fetchConfirmedVaultUtxos` is service-mode
+     * only, so there is no automatic gather here; without the set, a multi-UTXO
+     * vault fails in the signer with its "Insufficient UTXO value" error.
      */
     private executeBTCWithdrawalStandalonePhase2;
     executeBTCWithdrawal(request: {
@@ -903,6 +1018,25 @@ export declare class DiamondHandsSDK {
      * and catching — `ALL_DEPLOYMENTS` is published on the `@gvnrdao/dh-sdk/deployments` subpath.
      */
     private agentDelegationRegistryOrThrow;
+    /**
+     * `LoanGrant` fields that EVERY deployed registry version returns.
+     *
+     * Deliberately omits `minWithdrawRatioBps` — see {@link readLoanGrant}.
+     */
+    private static readonly LOAN_GRANT_PREFIX_IFACE;
+    /**
+     * Read a position's grant, decoding only the struct prefix that every deployed registry
+     * version shares.
+     *
+     * `LoanGrant` gained a fourth member (`minWithdrawRatioBps`) in registry v2.1.0, and the
+     * typechain bindings are generated from that source — but Sepolia (`0x6AE7fc6b…`) and mainnet
+     * (`0x54853b7E…`) both run v2.0.0, whose `getLoanGrant` returns three words. Decoding that
+     * with the generated four-field decoder fails `BAD_DATA` on every live chain, which is what
+     * took the Agents tab down. The first three members are identical in both layouts, and ethers
+     * ignores the trailing static word on a v2.1.0 registry, so this decoder is correct against
+     * both. Nothing in this SDK reads `minWithdrawRatioBps`: WITHDRAW is not a scope it grants.
+     */
+    private readLoanGrant;
     /**
      * Read a position's auto-renew delegation state (used to drive the Enable/Disable toggle).
      * Pure view — no signer required.
@@ -916,6 +1050,49 @@ export declare class DiamondHandsSDK {
             reason: number;
         } | null;
     }>;
+    /**
+     * Read every delegation scope a position has granted, plus the mint floor and the protocol
+     * minimum the UI must clamp its editor to. Pure view — no signer required.
+     *
+     * Superset of `getAutoRenewStatus`, which predates the multi-scope UI and is kept for
+     * callers that only care about renew.
+     */
+    getDelegationStatus(positionId: string, user?: string): Promise<{
+        renewEnabled: boolean;
+        repayEnabled: boolean;
+        mintEnabled: boolean;
+        /** Grant's post-mint CR floor in bps; 0 when MINT is not granted. */
+        minCollateralRatioBps: number;
+        /** What `canMint` actually enforces: `max(grant floor, protocol min)`. 0 when not granted. */
+        effectiveMintFloorBps: number;
+        /** Governance floor-of-floors — the lowest value the user may set (15000 = 150%). */
+        protocolMinFloorBps: number;
+        borrower: string;
+        agentActive: boolean | null;
+        /** Agent expiry (unix seconds) — the ONLY time bound on every grant. Null without `user`. */
+        agentValidUntil: number | null;
+    }>;
+    /** Governance floor-of-floors for agent mints (bps). The UI's minimum for the floor editor. */
+    getAgentMintFloorMinBps(): Promise<number>;
+    /**
+     * Shared enable-path preamble for EVERY scope: resolve the registry, ensure the borrower has
+     * an active agent (minting + registering a per-user PKP on first use), and make that agent the
+     * position's Gate-1 delegate. Returns the signer-connected registry and the agent address.
+     *
+     * Every `enableAuto*` runs this: the registry reverts `NoActiveAgent` without an agent, and
+     * `lit-ops-server.isPositionDelegate` 403s the agent on the execute routes without Gate 1 —
+     * so a scope enabled without this preamble would look on but never execute.
+     */
+    private prepareAgentDelegation;
+    /**
+     * Shared disable-path epilogue: drop the position's Gate-1 delegate, but ONLY once no scope
+     * remains. Scopes compose, so clearing Gate 1 on every disable would silently break the
+     * surviving ones server-side (the agent would 403 on the execute routes while its remaining
+     * grant still reads as enabled on-chain).
+     *
+     * Also refuses to clobber a delegate registered for anything other than this user's agent.
+     */
+    private clearGate1IfNoScopesRemain;
     /**
      * Enable auto-renew delegation for a position. Orchestrates the first-time setup: if the
      * borrower has no active agent, mints a fresh per-user agent PKP (via lit-ops-server) and
@@ -938,6 +1115,54 @@ export declare class DiamondHandsSDK {
         hash: string;
         blockNumber: number;
     }>;
+    /**
+     * Enable auto-repay delegation: the agent may repay this position's debt on the borrower's
+     * behalf. Deliberately uncapped in the registry — repay only ever burns the borrower's own
+     * debt from the borrower's own funds, and the ERC-20 allowance to PositionManager (never
+     * granted to the agent) is the natural bound. Borrower-signed.
+     */
+    enableAutoRepay(positionId: string, options?: {
+        agentValiditySeconds?: number;
+    }): Promise<{
+        hash: string;
+        blockNumber: number;
+        agentAddress?: string;
+    }>;
+    /** Disable auto-repay delegation for a position. Borrower-signed. */
+    disableAutoRepay(positionId: string): Promise<{
+        hash: string;
+        blockNumber: number;
+    }>;
+    /**
+     * Enable auto-mint delegation with a post-mint collateral-ratio floor (bps) the mint validator
+     * enforces. `minCollateralRatioBps` must be at or above the governance minimum
+     * (`getAgentMintFloorMinBps()`, 15000 = 150%) — checked here so the caller gets a readable
+     * error instead of a `FloorBelowProtocolMin` revert after signing. Borrower-signed.
+     */
+    enableAutoMint(positionId: string, minCollateralRatioBps: number, options?: {
+        agentValiditySeconds?: number;
+    }): Promise<{
+        hash: string;
+        blockNumber: number;
+        agentAddress?: string;
+    }>;
+    /** Disable auto-mint delegation for a position (also zeroes its mint floor). Borrower-signed. */
+    disableAutoMint(positionId: string): Promise<{
+        hash: string;
+        blockNumber: number;
+    }>;
+    /**
+     * Change an existing mint grant's collateral floor in place — no disable/re-enable dance.
+     * MINT must already be granted; the new floor must clear the governance minimum. Note the
+     * borrower may move it in either direction (above the minimum); only `REGISTRAR_ROLE` is
+     * restricted to raising. Borrower-signed.
+     */
+    setMintCollateralFloor(positionId: string, newFloorBps: number): Promise<{
+        hash: string;
+        blockNumber: number;
+    }>;
+    /** Pre-flight the registry's `FloorBelowProtocolMin` guard with a message a user can act on. */
+    private assertMintFloorAtOrAboveProtocolMin;
     /**
      * Get Bitcoin balance for an address
      *

package/dist/safe-delegation.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Narrow entry point for Safe agent-delegation reads.
+ *
+ * A SUBPATH rather than a main-index re-export, for two reasons the frontend
+ * learned the hard way:
+ *
+ *  - the app shadows the bare `@gvnrdao/dh-sdk` specifier with a hand-written
+ *    ambient module (`types/@gvnrdao__dh-sdk.d.ts`), so anything imported from
+ *    there is UNCHECKED against the real package — a call could take wrong
+ *    arguments and still compile. Subpaths escape the shim and get the
+ *    package's own types;
+ *  - the main index pulls the whole SDK (and `@gvnrdao/dh-lit-actions`) for what
+ *    is a handful of `eth_call`s.
+ */
+export { getSafeAgentDelegation, buildSafeAgentDelegationDisableCalls, type SafeAgentDelegation, type SafeAgentDelegationDisablePlan, type SafeDelegationCall, type SafeDelegationStatus, } from "./utils/safe-agent-delegation.utils";