@t2000/sdk 1.5.0 → 1.7.0

package/dist/index.d.ts

@@ -1,13 +1,13 @@
 import { EventEmitter } from 'eventemitter3';
 import { SuiJsonRpcClient } from '@mysten/sui/jsonRpc';
 import { Ed25519Keypair } from '@mysten/sui/keypairs/ed25519';
-import { V as TxMetadata, q as SafeguardConfig, T as T2000Error, R as TransactionSigner, a1 as ZkLoginProof, x as SupportedAsset } from './types-BhiUiiNs.js';
-export { A as ALL_NAVI_ASSETS, B as BORROW_FEE_BPS, a as BPS_DENOMINATOR, aB as CETUS_USDC_SUI_POOL, C as CLOCK_ID, b as COIN_REGISTRY, c as ClassifyBalanceChange, d as ClassifyResult, e as CoinMeta, D as DEFAULT_NETWORK, f as DEFAULT_SAFEGUARD_CONFIG, E as ETH_TYPE, g as ExtractedTransfer, F as FeeOperation, G as GAS_RESERVE_MIN, I as IKA_TYPE, K as KNOWN_TARGETS, h as KeypairSigner, L as LABEL_PATTERNS, i as LOFI_TYPE, M as MANIFEST_TYPE, j as MIST_PER_SUI, N as NAVX_TYPE, aC as OPERATION_ASSETS, O as OUTBOUND_OPS, k as OVERLAY_FEE_RATE, aD as Operation, l as OverlayFeeConfig, P as ProtocolFeeInfo, S as SAVE_FEE_BPS, m as STABLE_ASSETS, n as SUI_DECIMALS, o as SUI_TYPE, p as SUPPORTED_ASSETS, r as SafeguardError, s as SafeguardErrorDetails, t as SafeguardRule, u as SimulationResult, v as StableAsset, w as SuiRpcTxBlock, y as SwapRouteResult, z as T2000ErrorCode, H as T2000ErrorData, J as T2000_OVERLAY_FEE_WALLET, Q as TOKEN_MAP, U as TxDirection, W as USDC_DECIMALS, X as USDC_TYPE, Y as USDE_TYPE, Z as USDSUI_TYPE, _ as USDT_TYPE, $ as WAL_TYPE, a0 as WBTC_TYPE, a2 as ZkLoginSigner, a3 as addFeeTransfer, aE as assertAllowedAsset, a4 as buildSwapTx, a5 as calculateFee, a6 as classifyAction, a7 as classifyLabel, a8 as classifyTransaction, a9 as extractTransferDetails, aa as extractTxCommands, ab as extractTxSender, ac as fallbackLabel, ad as findSwapRoute, ae as formatAssetAmount, af as formatSui, ag as formatUsd, aF as getCoinMeta, ah as getDecimals, ai as getDecimalsForCoinType, aj as getTier, aG as isAllowedAsset, aH as isInRegistry, ak as isSupported, al as isTier1, am as isTier2, an as mapMoveAbortCode, ao as mapWalletError, ap as mistToSui, aI as normalizeCoinType, aq as parseSuiRpcTx, aJ as queryHistory, aK as queryTransaction, ar as rawToStable, as as rawToUsdc, at as refineLendingLabel, au as resolveSymbol, av as resolveTokenType, aL as simulateTransaction, aw as stableToRaw, ax as suiToMist, aM as throwIfSimulationFailed, ay as truncateAddress, az as usdcToRaw, aA as validateAddress } from './types-BhiUiiNs.js';
+import { V as TxMetadata, q as SafeguardConfig, T as T2000Error, R as TransactionSigner, a1 as ZkLoginProof, x as SupportedAsset, l as OverlayFeeConfig, y as SwapRouteResult } from './types-B0VlW8Ov.js';
+export { A as ALL_NAVI_ASSETS, B as BORROW_FEE_BPS, a as BPS_DENOMINATOR, aB as CETUS_USDC_SUI_POOL, C as CLOCK_ID, b as COIN_REGISTRY, c as ClassifyBalanceChange, d as ClassifyResult, e as CoinMeta, D as DEFAULT_NETWORK, f as DEFAULT_SAFEGUARD_CONFIG, E as ETH_TYPE, g as ExtractedTransfer, F as FeeOperation, G as GAS_RESERVE_MIN, I as IKA_TYPE, K as KNOWN_TARGETS, h as KeypairSigner, L as LABEL_PATTERNS, i as LOFI_TYPE, M as MANIFEST_TYPE, j as MIST_PER_SUI, N as NAVX_TYPE, aC as OPERATION_ASSETS, O as OUTBOUND_OPS, k as OVERLAY_FEE_RATE, aD as Operation, P as ProtocolFeeInfo, S as SAVE_FEE_BPS, m as STABLE_ASSETS, n as SUI_DECIMALS, o as SUI_TYPE, p as SUPPORTED_ASSETS, r as SafeguardError, s as SafeguardErrorDetails, t as SafeguardRule, u as SimulationResult, v as StableAsset, w as SuiRpcTxBlock, z as T2000ErrorCode, H as T2000ErrorData, J as T2000_OVERLAY_FEE_WALLET, Q as TOKEN_MAP, U as TxDirection, W as USDC_DECIMALS, X as USDC_TYPE, Y as USDE_TYPE, Z as USDSUI_TYPE, _ as USDT_TYPE, $ as WAL_TYPE, a0 as WBTC_TYPE, a2 as ZkLoginSigner, a3 as addFeeTransfer, aE as addSwapToTx, aF as assertAllowedAsset, a4 as buildSwapTx, a5 as calculateFee, a6 as classifyAction, a7 as classifyLabel, a8 as classifyTransaction, a9 as extractTransferDetails, aa as extractTxCommands, ab as extractTxSender, ac as fallbackLabel, ad as findSwapRoute, ae as formatAssetAmount, af as formatSui, ag as formatUsd, aG as getCoinMeta, ah as getDecimals, ai as getDecimalsForCoinType, aj as getTier, aH as isAllowedAsset, aI as isInRegistry, ak as isSupported, al as isTier1, am as isTier2, an as mapMoveAbortCode, ao as mapWalletError, ap as mistToSui, aJ as normalizeCoinType, aq as parseSuiRpcTx, aK as queryHistory, aL as queryTransaction, ar as rawToStable, as as rawToUsdc, at as refineLendingLabel, au as resolveSymbol, av as resolveTokenType, aM as simulateTransaction, aw as stableToRaw, ax as suiToMist, aN as throwIfSimulationFailed, ay as truncateAddress, az as usdcToRaw, aA as validateAddress } from './types-B0VlW8Ov.js';
 import { L as LendingAdapter, a as LendingRates, P as PendingReward$1 } from './descriptors-BnbL3xN8.js';
 export { A as AdapterCapability, b as AdapterPositions, c as AdapterTxResult, H as HealthInfo, d as ProtocolDescriptor, e as allDescriptors, n as naviDescriptor } from './descriptors-BnbL3xN8.js';
 import { i as T2000Options, P as PayOptions, c as PayResult, j as StakeVSuiResult, U as UnstakeVSuiResult, k as SwapResult, l as SwapQuoteResult, h as SendResult, B as BalanceResponse, T as TransactionRecord, D as DepositInfo, m as PaymentRequest, S as SaveResult, W as WithdrawResult, b as MaxWithdrawResult, a as BorrowResult, g as RepayResult, M as MaxBorrowResult, H as HealthFactorResult, d as PendingReward, C as ClaimRewardsResult, n as CompoundRewardsResult, f as PositionsResult, R as RatesResult, E as EarningsResult, F as FundStatusResult, o as FinancialSummary } from './types-jAD-e7Pq.js';
 export { A as AssetRates, G as GasReserve, p as HFAlertLevel, e as PositionEntry } from './types-jAD-e7Pq.js';
-import { Transaction } from '@mysten/sui/transactions';
+import { Transaction, TransactionObjectArgument } from '@mysten/sui/transactions';
 export { NaviAdapter, ProtocolRegistry } from './adapters/index.js';
 import '@cetusprotocol/aggregator-sdk';
 
@@ -233,6 +233,490 @@ declare function walletExists(keyPath?: string): Promise<boolean>;
 declare function exportPrivateKey(keypair: Ed25519Keypair): string;
 declare function getAddress(keypair: Ed25519Keypair): string;
 
+declare function buildSendTx({ client, address, to, amount, asset, }: {
+    client: SuiJsonRpcClient;
+    address: string;
+    to: string;
+    amount: number;
+    asset?: SupportedAsset;
+}): Promise<Transaction>;
+/**
+ * Fragment-appender for the chain-mode send leg of SPEC 7 multi-write
+ * PTBs. Consumes a coin reference produced by a previous appender (e.g.
+ * `addWithdrawToTx`, `addSwapToTx`) and transfers it to `recipient`
+ * within the same PTB — no intermediate wallet materialization.
+ *
+ * Codifies the hand-built send leg from
+ * `scripts/smoke-spec7-withdraw-then-send.ts` (P2.1) into a typed
+ * appender. SPEC 7 § "Layer 1" — P2.2b will register this in the
+ * `WRITE_APPENDER_REGISTRY` under `send_transfer` for chain-mode
+ * dispatch; the registry adapter will handle the wallet-fetch fallback
+ * by delegating to `buildSendTx` when no upstream coin is available.
+ *
+ * For single-step send_transfer flows (no chained predecessor), use
+ * `buildSendTx` directly — it builds a complete tx including the
+ * wallet-coin selection / merge / split prelude.
+ *
+ * @returns void — the coin is consumed by `tx.transferObjects`. Callers
+ *   that need the post-transfer "effective amount" should rely on the
+ *   upstream appender's `effectiveAmount` (e.g. `addWithdrawToTx`'s
+ *   return), not on this appender.
+ */
+declare function addSendToTx(tx: Transaction, coin: TransactionObjectArgument, recipient: string): void;
+
+/**
+ * Wallet-side coin selection helpers — shared paginated coin lookup +
+ * merge + split prelude used by every wallet-mode appender that needs
+ * a `TransactionObjectArgument` reference to a specific amount of a
+ * given coin type.
+ *
+ * Replaces three earlier inline implementations:
+ * - `cetus-swap.ts:fetchAllCoinsForSwap` (kept for backwards-compat,
+ *   delegates here)
+ * - `volo.ts:fetchCoinsByType` (kept for backwards-compat, delegates
+ *   here)
+ * - audric host's `transactions/prepare/route.ts:fetchCoinsForSwap`
+ *   (P2.2c retires this when migrating to `composeTx`)
+ *
+ * Single source of truth for the "fetch coins of type X owned by
+ * address Y, paginated" pattern. P2.2b extracts this so `composeTx`'s
+ * registry adapters can build a wallet-mode `TransactionObjectArgument`
+ * uniformly across save / send / repay / etc.
+ */
+
+interface CoinPage {
+    ids: string[];
+    totalBalance: bigint;
+}
+/**
+ * Paginated coin lookup. Fetches every coin object of `coinType` owned
+ * by `owner` (walks the cursor until `hasNextPage === false`). Returns
+ * the list of object IDs + summed balance.
+ *
+ * Replaces inline `client.getCoins` calls that miss coins on the second
+ * page when wallets accumulate many small coin objects (the bug class
+ * that bit `buildSendTx` pre-P2.2 — captured for SPEC 12).
+ */
+declare function fetchAllCoins(client: SuiJsonRpcClient, owner: string, coinType: string): Promise<CoinPage>;
+interface SelectAndSplitResult {
+    /** TransactionObjectArgument for a coin holding `effectiveAmount` raw units. */
+    coin: TransactionObjectArgument;
+    /** Actual raw amount the returned coin holds. May be < requested if `swapAll` is true. */
+    effectiveAmount: bigint;
+    /** True iff the request consumed the entire wallet balance (no split needed). */
+    swapAll: boolean;
+}
+/**
+ * Wallet-mode coin selection prelude. Fetches every coin of `coinType`
+ * owned by `owner`, merges them into a primary, and splits off the
+ * requested `amount` (or returns the merged primary directly if the
+ * request meets/exceeds the total balance — `swapAll` semantics).
+ *
+ * Throws `T2000Error` (`INSUFFICIENT_BALANCE`) when:
+ * - No coins of `coinType` exist for `owner`
+ * - `amount` is bigger than the total balance AND the caller did NOT
+ *   opt into `swapAll: true` clipping
+ *
+ * Used by:
+ * - `composeTx` registry adapters (save_deposit, send_transfer,
+ *   repay_debt — non-SUI assets) for the wallet-mode prelude
+ * - Layer 1 dual-mode appenders (`addSwapToTx`, `addStakeVSuiToTx`,
+ *   `addUnstakeVSuiToTx`) when `inputCoin` is omitted
+ *
+ * @param tx — PTB to append `mergeCoins` + `splitCoins` commands to.
+ * @param client — Sui RPC client for the paginated `getCoins` lookup.
+ * @param owner — wallet address whose coins to fetch.
+ * @param coinType — fully-qualified Sui coin type
+ *   (`"0x...::usdc::USDC"`).
+ * @param amount — raw amount to split out (in MIST / smallest unit).
+ *   Pass `'all'` to consume the entire merged primary directly.
+ * @param options.allowSwapAll — if true (default), `amount` >=
+ *   totalBalance auto-clips to total (matches audric host's swap
+ *   branch). If false, throws `INSUFFICIENT_BALANCE` when over.
+ *
+ * @returns
+ *   - `coin` — `TransactionObjectArgument` ready for downstream
+ *     consumption (e.g. `addSaveToTx`, `tx.transferObjects`).
+ *   - `effectiveAmount` — the raw amount the returned coin actually
+ *     holds (handles swapAll clipping).
+ *   - `swapAll` — true iff the entire merged primary was consumed.
+ */
+declare function selectAndSplitCoin(tx: Transaction, client: SuiJsonRpcClient, owner: string, coinType: string, amount: bigint | 'all', options?: {
+    allowSwapAll?: boolean;
+}): Promise<SelectAndSplitResult>;
+/**
+ * SUI-specific coin selection. Branches on sponsorship context:
+ *
+ * - **Sponsored (`sponsoredContext: true`)** — fetches SUI coins via
+ *   `getCoins` and merges/splits, because `tx.gas` belongs to the
+ *   Enoki sponsor (NOT the user) under sponsored flows. Same shape as
+ *   `selectAndSplitCoin` for any other coin type.
+ *
+ * - **Self-funded (`sponsoredContext: false`)** — splits from `tx.gas`
+ *   directly (the user's gas coin IS their SUI). More efficient — no
+ *   getCoins RTT.
+ *
+ * Captures the SUI-vs-other-asset divergence that lives inline in
+ * `buildSendTx` today (`tx.splitCoins(tx.gas, ...)` vs paginated
+ * lookup). composeTx's `send_transfer` adapter routes through this
+ * helper to handle both.
+ */
+declare function selectSuiCoin(tx: Transaction, client: SuiJsonRpcClient, owner: string, amountMist: bigint, sponsoredContext: boolean): Promise<SelectAndSplitResult>;
+
+/**
+ * SPEC 7 v0.4 § Layer 0 — Canonical Write Architecture.
+ *
+ * `composeTx({ steps })` is the single canonical entry-point for every
+ * Audric Enoki-sponsored write. The fragment-appender pattern (Layer 1)
+ * is the implementation; this primitive dispatches each step to its
+ * registered appender from the typed `WRITE_APPENDER_REGISTRY`.
+ *
+ * Single-write and multi-write go through the same code path. A 1-step
+ * `composeTx([{ toolName: 'send_transfer', input: {...} }])` produces
+ * the same shape of result as a 3-step bundle.
+ *
+ * **Why this exists**
+ *
+ * Pre-Layer-0, four parallel write stacks lived across the audric host:
+ * `transactions/prepare` (fat ~600-line route), `services/prepare`
+ * (hand-rolled), `debug-swap` (diagnostic), and PayButton (dapp-kit).
+ * Each one re-implemented merge/split/transfer + hand-maintained the
+ * `allowedAddresses` array Enoki requires. Two production bugs in the
+ * past 60 days came from drift between them — PR-H1 (claim-rewards
+ * self-transfer missing from allowedAddresses) and PR-H4 (borrow/
+ * withdraw self-transfer same bug).
+ *
+ * Layer 0 collapses 3 of those stacks into one canonical primitive.
+ * PayButton stays out by design (different signer, different trust
+ * model — see `audric-canonical-write.mdc` for the rationale and the
+ * `// CANONICAL-BYPASS:` escape-hatch contract).
+ *
+ * **What composeTx owns**
+ *
+ * - PTB assembly via per-tool wallet-mode appenders (the
+ *   `WRITE_APPENDER_REGISTRY`).
+ * - Pre-built `txKindBytes` (`tx.build({ onlyTransactionKind: true })`)
+ *   ready for Enoki's `createSponsoredTransaction`.
+ * - Auto-derived `derivedAllowedAddresses` from the assembled PTB's
+ *   top-level `transferObjects` calls — eliminates the PR-H1/H4 bug
+ *   class permanently. Hand-maintained arrays are now unreachable.
+ * - S.38 Pyth flag plumbing — `sponsoredContext: true` automatically
+ *   applies `skipPythUpdate` (borrow/withdraw) and `skipOracle` (repay)
+ *   to NAVI appenders so Enoki doesn't reject `tx.gas`-as-argument.
+ *
+ * **What composeTx does NOT own**
+ *
+ * - **Fees** — Audric concern, not @t2000/sdk concern (CLAUDE.md
+ *   rule #9). The SDK is fee-free by design as of @t2000/sdk@1.1.0
+ *   (B5 v2). Audric host wraps composeTx with fee insertion in P2.2c.
+ * - **Sponsorship** — caller's job. composeTx returns `txKindBytes`
+ *   pre-built for Enoki; the caller calls `createSponsoredTransaction`
+ *   with their JWT.
+ * - **Chain-mode coin handoff between steps** — Layer 2 (engine
+ *   bundling) ships this. P2.2b is wallet-mode-only: each step fetches
+ *   coins independently. Layer 2 will extend by introducing
+ *   `inputCoinFromStep: number` to thread upstream output coins.
+ *
+ * **Cross-references**
+ *
+ * - Spec → `spec/SPEC_7_MULTI_WRITE_PTB.md` § "Layer 0: Canonical
+ *   Write Architecture"
+ * - Read-side companion → `t2000/.cursor/rules/single-source-of-truth.mdc`
+ *   + `audric/.cursor/rules/audric-canonical-portfolio.mdc`
+ * - Write-side rule → `audric/.cursor/rules/audric-canonical-write.mdc`
+ */
+
+/**
+ * Canonical write tools. The 9 tools that can be composed into a PTB.
+ *
+ * Excluded by design:
+ * - `pay_api` — recipient/amount unknown at compose time; the on-chain
+ *   leg uses `send_transfer` after the gateway 402 challenge resolves.
+ * - `save_contact` — no on-chain leg (Prisma-only).
+ */
+type WriteToolName = 'save_deposit' | 'withdraw' | 'borrow' | 'repay_debt' | 'send_transfer' | 'swap_execute' | 'claim_rewards' | 'volo_stake' | 'volo_unstake';
+interface SaveDepositInput {
+    amount: number;
+    asset?: 'USDC' | 'USDsui';
+}
+interface WithdrawInput {
+    amount: number;
+    asset?: 'USDC' | 'USDsui';
+}
+interface BorrowInput {
+    amount: number;
+    asset?: 'USDC' | 'USDsui';
+}
+interface RepayDebtInput {
+    amount: number;
+    asset?: 'USDC' | 'USDsui';
+}
+interface SendTransferInput {
+    to: string;
+    amount: number;
+    asset?: SupportedAsset;
+}
+interface SwapExecuteInput {
+    from: string;
+    to: string;
+    amount: number;
+    slippage?: number;
+    byAmountIn?: boolean;
+    /** Cetus provider allow-list. Sponsored callers MUST pass an exclusion list
+     *  to remove Pyth-dependent providers — see addSwapToTx JSDoc. composeTx
+     *  derives this automatically from `sponsoredContext` if omitted. */
+    providers?: string[];
+}
+type ClaimRewardsInput = Record<string, never>;
+interface VoloStakeInput {
+    amountSui: number;
+}
+interface VoloUnstakeInput {
+    amountVSui: number | 'all';
+}
+/**
+ * Discriminated union mapping `toolName` → `input`. Used to type
+ * `WriteStep` so consumers get autocomplete + compile-time validation
+ * that the input matches the tool.
+ */
+type WriteStep = {
+    toolName: 'save_deposit';
+    input: SaveDepositInput;
+} | {
+    toolName: 'withdraw';
+    input: WithdrawInput;
+} | {
+    toolName: 'borrow';
+    input: BorrowInput;
+} | {
+    toolName: 'repay_debt';
+    input: RepayDebtInput;
+} | {
+    toolName: 'send_transfer';
+    input: SendTransferInput;
+} | {
+    toolName: 'swap_execute';
+    input: SwapExecuteInput;
+} | {
+    toolName: 'claim_rewards';
+    input: ClaimRewardsInput;
+} | {
+    toolName: 'volo_stake';
+    input: VoloStakeInput;
+} | {
+    toolName: 'volo_unstake';
+    input: VoloUnstakeInput;
+};
+interface ComposeTxOptions {
+    sender: string;
+    steps: WriteStep[];
+    client: SuiJsonRpcClient;
+    /**
+     * S.38 Pyth flag (sponsorship-critical). When true:
+     * - NAVI borrow/withdraw appenders apply `skipPythUpdate: true`
+     *   (preserves on-chain price-feed updates, skips the tx.gas-using
+     *   Pyth fee payment that Enoki rejects).
+     * - NAVI repay appender applies `skipOracle: true` (debt reduction
+     *   has no health-factor risk, full oracle bypass is safe).
+     * - Cetus swap appender applies `getProvidersExcluding([HAEDALPMM,
+     *   METASTABLE, OBRIC, STEAMM_OMM, STEAMM_OMM_V2, SEVENK,
+     *   HAEDALHMMV2])` — Pyth-dependent providers reference `tx.gas` for
+     *   oracle fees, also rejected by Enoki.
+     * - SUI sends fetch coins via `getCoins` (tx.gas belongs to sponsor,
+     *   not user) instead of splitting from `tx.gas`.
+     *
+     * Self-funded callers (CLI, MCP, server tasks) leave this `false` /
+     * omit — they pay all oracle/Pyth fees from their own SUI gas.
+     */
+    sponsoredContext?: boolean;
+    /**
+     * Per-call overlay fee config for Cetus swaps. Audric host passes
+     * `{ rate: 0.001, receiver: T2000_OVERLAY_FEE_WALLET }` to charge the
+     * 0.1% swap overlay. CLI / direct SDK callers omit. Forwarded to
+     * `addSwapToTx`'s `input.overlayFee`.
+     */
+    overlayFee?: OverlayFeeConfig;
+    /**
+     * Optional fee-injection hooks for save_deposit + borrow. Fires inside
+     * the appender at the exact moment the user's coin is in hand and BEFORE
+     * the protocol step consumes (save) or the canonical transferObjects
+     * finalizes (borrow). Audric host uses this to inline `addFeeTransfer`
+     * for USDC SAVE_FEE_BPS / BORROW_FEE_BPS without ever leaving the
+     * canonical write contract — keeps the SDK fee-free per CLAUDE.md
+     * rule #9 while letting hosts charge their own overlay fees.
+     *
+     * Hooks are fire-and-forget (no return value). They mutate `tx` directly
+     * (e.g., `addFeeTransfer(tx, coin, ...)` splits the fee chunk off and
+     * appends a top-level `transferObjects` to the host's fee wallet — that
+     * recipient automatically appears in `derivedAllowedAddresses`).
+     */
+    feeHooks?: ComposeTxFeeHooks;
+}
+/**
+ * Per-tool fee-injection callbacks. Each hook fires at a tool-specific
+ * moment in the appender flow (see field JSDoc). Currently scoped to
+ * the 2 fee-eligible tools — extend if/when new ones land.
+ */
+interface ComposeTxFeeHooks {
+    /**
+     * Fires inside the `save_deposit` appender AFTER the user's USDC/USDsui
+     * coin is split into the deposit amount, BEFORE NAVI's `deposit` move
+     * call consumes the coin. Order matters: the `coin` reference passed in
+     * is the SAME `TransactionObjectArgument` that flows into the deposit,
+     * so any `splitCoins(coin, [feeAmount])` inside the hook reduces the
+     * deposit by exactly that fee.
+     */
+    save_deposit?: (ctx: ComposeTxFeeHookContext<SaveDepositInput>) => void | Promise<void>;
+    /**
+     * Fires inside the `borrow` appender AFTER NAVI returns the borrowed
+     * coin, BEFORE the canonical `transferObjects(coin, sender)` finalizes.
+     * The `coin` reference is the borrowed-and-not-yet-transferred output;
+     * splitting a fee here means the user receives the remainder.
+     */
+    borrow?: (ctx: ComposeTxFeeHookContext<BorrowInput>) => void | Promise<void>;
+}
+/**
+ * Context object passed to every fee hook. Carries the `tx` (mutate it),
+ * the in-flight `coin` (split fees off it), the resolved tool input
+ * (asset/amount for fee-policy decisions), and the sender (rarely needed
+ * but kept for symmetry with `AppenderContext`).
+ */
+interface ComposeTxFeeHookContext<TInput> {
+    tx: Transaction;
+    coin: TransactionObjectArgument;
+    input: TInput;
+    sender: string;
+}
+/** Per-step preview returned by each registry appender. Tool-specific shape. */
+type StepPreview = {
+    toolName: 'save_deposit';
+    effectiveAmount: number;
+    asset: 'USDC' | 'USDsui';
+} | {
+    toolName: 'withdraw';
+    effectiveAmount: number;
+    asset: 'USDC' | 'USDsui';
+} | {
+    toolName: 'borrow';
+    effectiveAmount: number;
+    asset: 'USDC' | 'USDsui';
+} | {
+    toolName: 'repay_debt';
+    effectiveAmount: number;
+    asset: 'USDC' | 'USDsui';
+} | {
+    toolName: 'send_transfer';
+    effectiveAmount: number;
+    recipient: string;
+    asset: SupportedAsset;
+} | {
+    toolName: 'swap_execute';
+    effectiveAmountIn: number;
+    expectedAmountOut: number;
+    route: SwapRouteResult;
+} | {
+    toolName: 'claim_rewards';
+    rewards: PendingReward$1[];
+} | {
+    toolName: 'volo_stake';
+    effectiveAmountMist: bigint;
+} | {
+    toolName: 'volo_unstake';
+    effectiveAmountMist: bigint | 'all';
+};
+interface ComposeTxResult {
+    tx: Transaction;
+    /**
+     * Pre-built bytes for Enoki's `createSponsoredTransaction`. Built
+     * with `onlyTransactionKind: true` so the gas coin can be supplied
+     * by the sponsor.
+     */
+    txKindBytes: Uint8Array;
+    /**
+     * Auto-derived from the assembled PTB's top-level `transferObjects`
+     * commands. Replaces hand-maintained `allowedAddresses` arrays in
+     * audric host's `transactions/prepare` + `services/prepare` —
+     * eliminates the PR-H1/H4 bug class permanently.
+     */
+    derivedAllowedAddresses: string[];
+    perStepPreviews: StepPreview[];
+}
+/**
+ * Per-appender context passed into every registry entry. Carries the
+ * RPC client, sender, sponsorship flag, and optional per-call overlay
+ * fee config (Cetus swaps).
+ */
+interface AppenderContext {
+    client: SuiJsonRpcClient;
+    sender: string;
+    sponsoredContext: boolean;
+    overlayFee?: OverlayFeeConfig;
+    feeHooks?: ComposeTxFeeHooks;
+}
+type AppenderFn<TInput, TPreview extends StepPreview> = (tx: Transaction, input: TInput, ctx: AppenderContext) => Promise<TPreview>;
+/**
+ * The typed registry. Each entry is a wallet-mode dispatcher that takes
+ * (tx, input, ctx) and returns a per-step preview. Compile-time check
+ * that all 9 `WriteToolName` values have an entry — TypeScript will
+ * fail the build if a tool is missing.
+ */
+declare const WRITE_APPENDER_REGISTRY: {
+    save_deposit: AppenderFn<SaveDepositInput, Extract<StepPreview, {
+        toolName: 'save_deposit';
+    }>>;
+    withdraw: AppenderFn<WithdrawInput, Extract<StepPreview, {
+        toolName: 'withdraw';
+    }>>;
+    borrow: AppenderFn<BorrowInput, Extract<StepPreview, {
+        toolName: 'borrow';
+    }>>;
+    repay_debt: AppenderFn<RepayDebtInput, Extract<StepPreview, {
+        toolName: 'repay_debt';
+    }>>;
+    send_transfer: AppenderFn<SendTransferInput, Extract<StepPreview, {
+        toolName: 'send_transfer';
+    }>>;
+    swap_execute: AppenderFn<SwapExecuteInput, Extract<StepPreview, {
+        toolName: 'swap_execute';
+    }>>;
+    claim_rewards: AppenderFn<ClaimRewardsInput, Extract<StepPreview, {
+        toolName: 'claim_rewards';
+    }>>;
+    volo_stake: AppenderFn<VoloStakeInput, Extract<StepPreview, {
+        toolName: 'volo_stake';
+    }>>;
+    volo_unstake: AppenderFn<VoloUnstakeInput, Extract<StepPreview, {
+        toolName: 'volo_unstake';
+    }>>;
+};
+/**
+ * Walks the assembled PTB's command list and extracts every recipient
+ * address from top-level `TransferObjects` commands. Top-level only —
+ * recipients inside nested Move calls are NOT inspected (Enoki only
+ * cross-checks top-level commands).
+ *
+ * Replaces hand-maintained `allowedAddresses` arrays. Two production
+ * bugs in 60 days came from drift between the array and the actual
+ * PTB recipients (PR-H1 + PR-H4). Computing this from the PTB makes
+ * drift impossible by construction.
+ */
+declare function deriveAllowedAddressesFromPtb(tx: Transaction): string[];
+/**
+ * Compose a PTB from a list of canonical write steps. Each step
+ * dispatches to its registered fragment-appender; the assembled PTB is
+ * returned alongside pre-built `txKindBytes` ready for Enoki sponsorship
+ * + auto-derived `derivedAllowedAddresses`.
+ *
+ * Single-step: `composeTx({ steps: [{ toolName: 'send_transfer', input: {...} }], ... })`
+ * Multi-step (Layer 2): `composeTx({ steps: [{...}, {...}, {...}], ... })`
+ *
+ * Throws:
+ * - `T2000Error('NO_APPENDER')` — unknown `toolName`
+ * - Any error thrown by the per-step appender (insufficient balance,
+ *   asset not supported, route not found, etc.) — propagates as-is.
+ */
+declare function composeTx(opts: ComposeTxOptions): Promise<ComposeTxResult>;
+
 declare const HF_WARN_THRESHOLD = 1.8;
 declare const HF_CRITICAL_THRESHOLD = 1.3;
 type FinancialSummaryOptions = Record<string, never>;
@@ -248,6 +732,29 @@ declare function getFinancialSummary(client: SuiJsonRpcClient, walletAddress: st
 
 declare function getRates(client: SuiJsonRpcClient): Promise<RatesResult>;
 declare function getPendingRewards(client: SuiJsonRpcClient, address: string): Promise<PendingReward$1[]>;
+/**
+ * Standalone builder for the `claim_rewards` tool. Wraps the existing
+ * `addClaimRewardsToTx` appender into a complete PTB so the SPEC 7
+ * `composeTx` registry adapter has a single-step builder it can dispatch
+ * to when `claim_rewards` is invoked alone (the chain-mode path uses
+ * `addClaimRewardsToTx` directly inside a multi-step PTB).
+ *
+ * Multi-protocol claim flows (e.g. NAVI + Suilend in a future world)
+ * still go through the `T2000` class's `claimRewards()` method, which
+ * iterates every registered lending adapter via the adapter registry —
+ * this standalone builder is intentionally NAVI-only to keep the shape
+ * symmetric with the rest of SPEC 7's Layer 1 builders.
+ *
+ * Returns `{ tx, rewards }`:
+ * - `tx` — built PTB with sender set; if no rewards are claimable, no
+ *   move calls are appended (caller should skip executing).
+ * - `rewards` — what WILL be claimed by `tx`. Empty array means nothing
+ *   to claim.
+ */
+declare function buildClaimRewardsTx(client: SuiJsonRpcClient, address: string): Promise<{
+    tx: Transaction;
+    rewards: PendingReward$1[];
+}>;
 
 declare function getSwapQuote(params: {
     walletAddress: string;
@@ -283,5 +790,68 @@ declare function buildStakeVSuiTx(_client: SuiJsonRpcClient, address: string, am
  * Build a PTB to unstake vSUI back to SUI.
  */
 declare function buildUnstakeVSuiTx(client: SuiJsonRpcClient, address: string, amountMist: bigint | 'all'): Promise<Transaction>;
+/**
+ * SPEC 7 § "Layer 1" Volo stake appender. Two modes.
+ *
+ * Wallet mode (`inputCoin` omitted): fetches SUI coins from the
+ * sender's wallet (paginated), merges/splits to `amountMist`. Mirrors
+ * the audric host's `transactions/prepare/route.ts:524-545` volo-stake
+ * branch — sponsored-flow safe (does NOT consume `tx.gas`, which
+ * belongs to the Enoki sponsor in sponsored flows).
+ *
+ * For non-sponsored flows where the caller owns `tx.gas`, prefer
+ * `buildStakeVSuiTx` directly (it splits from gas, which is more
+ * efficient by avoiding the extra getCoins RTT).
+ *
+ * Chain mode (`inputCoin` provided): consumes the passed-in SUI coin
+ * ref entirely. Used for chained flows like "swap USDC → SUI → stake".
+ * The caller is responsible for splitting upstream if they only want
+ * part of the input coin staked.
+ *
+ * @returns
+ *   - `coin`: vSUI output coin ref, ready for downstream consumption or
+ *     wallet transfer (`tx.transferObjects`).
+ *   - `effectiveAmountMist`: SUI mist consumed (echoes `input.amountMist`
+ *     in both modes; chain-mode trusts the caller-supplied value since
+ *     the actual coin balance is opaque).
+ */
+declare function addStakeVSuiToTx(tx: Transaction, client: SuiJsonRpcClient, address: string, input: {
+    amountMist: bigint;
+    inputCoin?: TransactionObjectArgument;
+}): Promise<{
+    coin: TransactionObjectArgument;
+    effectiveAmountMist: bigint;
+}>;
+/**
+ * SPEC 7 § "Layer 1" Volo unstake appender. Two modes.
+ *
+ * Wallet mode (`inputCoin` omitted): fetches vSUI coins from the
+ * sender's wallet (paginated), merges to a primary coin, splits to
+ * `amountMist` (or consumes the entire merged primary if `'all'`).
+ *
+ * Chain mode (`inputCoin` provided): consumes the passed-in vSUI coin
+ * ref. With `amountMist = 'all'`, the entire input coin is unstaked.
+ * With a bigint `amountMist`, the input coin is split internally and
+ * only that portion unstaked (the leftover stays accessible via the
+ * original ref). Used for chained flows where vSUI was just produced
+ * by a prior step.
+ *
+ * @returns
+ *   - `coin`: SUI output coin ref, ready for downstream consumption
+ *     (e.g. `addSendToTx`, `addStakeVSuiToTx` re-stake) or wallet
+ *     transfer (`tx.transferObjects`).
+ *   - `effectiveAmountMist`: input vSUI mist consumed; echoes
+ *     `input.amountMist` (`'all'` is preserved as-is — the actual SUI
+ *     received differs from input vSUI by the pool exchange rate, so
+ *     callers needing the SUI amount must query `getVoloStats` or
+ *     parse balance changes from the executed tx).
+ */
+declare function addUnstakeVSuiToTx(tx: Transaction, client: SuiJsonRpcClient, address: string, input: {
+    amountMist: bigint | 'all';
+    inputCoin?: TransactionObjectArgument;
+}): Promise<{
+    coin: TransactionObjectArgument;
+    effectiveAmountMist: bigint | 'all';
+}>;
 
-export { BalanceResponse, BorrowResult, ClaimRewardsResult, CompoundRewardsResult, ContactManager, DepositInfo, EarningsResult, FinancialSummary, type FinancialSummaryOptions, FundStatusResult, HF_CRITICAL_THRESHOLD, HF_WARN_THRESHOLD, HealthFactorResult, LendingAdapter, LendingRates, MaxBorrowResult, MaxWithdrawResult, PayOptions, PayResult, PaymentRequest, PendingReward, PositionsResult, RatesResult, RepayResult, SafeguardConfig, SafeguardEnforcer, SaveResult, SendResult, StakeVSuiResult, SupportedAsset, SwapQuoteResult, SwapResult, T2000, T2000Error, T2000Options, TransactionRecord, TransactionSigner, TxMetadata, UnstakeVSuiResult, VOLO_METADATA, VOLO_PKG, VOLO_POOL, VSUI_TYPE, type VoloStats, WithdrawResult, ZkLoginProof, buildStakeVSuiTx, buildUnstakeVSuiTx, exportPrivateKey, generateKeypair, getAddress, getFinancialSummary, getPendingRewards, getRates, getSwapQuote, getVoloStats, keypairFromPrivateKey, loadKey, saveKey, walletExists };
+export { type AppenderContext, BalanceResponse, type BorrowInput, BorrowResult, type ClaimRewardsInput, ClaimRewardsResult, type CoinPage, type ComposeTxFeeHookContext, type ComposeTxFeeHooks, type ComposeTxOptions, type ComposeTxResult, CompoundRewardsResult, ContactManager, DepositInfo, EarningsResult, FinancialSummary, type FinancialSummaryOptions, FundStatusResult, HF_CRITICAL_THRESHOLD, HF_WARN_THRESHOLD, HealthFactorResult, LendingAdapter, LendingRates, MaxBorrowResult, MaxWithdrawResult, OverlayFeeConfig, PayOptions, PayResult, PaymentRequest, PendingReward, PositionsResult, RatesResult, type RepayDebtInput, RepayResult, SafeguardConfig, SafeguardEnforcer, type SaveDepositInput, SaveResult, type SelectAndSplitResult, SendResult, type SendTransferInput, StakeVSuiResult, type StepPreview, SupportedAsset, type SwapExecuteInput, SwapQuoteResult, SwapResult, SwapRouteResult, T2000, T2000Error, T2000Options, TransactionRecord, TransactionSigner, TxMetadata, UnstakeVSuiResult, VOLO_METADATA, VOLO_PKG, VOLO_POOL, VSUI_TYPE, type VoloStakeInput, type VoloStats, type VoloUnstakeInput, WRITE_APPENDER_REGISTRY, type WithdrawInput, WithdrawResult, type WriteStep, type WriteToolName, ZkLoginProof, addSendToTx, addStakeVSuiToTx, addUnstakeVSuiToTx, buildClaimRewardsTx, buildSendTx, buildStakeVSuiTx, buildUnstakeVSuiTx, composeTx, deriveAllowedAddressesFromPtb, exportPrivateKey, fetchAllCoins, generateKeypair, getAddress, getFinancialSummary, getPendingRewards, getRates, getSwapQuote, getVoloStats, keypairFromPrivateKey, loadKey, saveKey, selectAndSplitCoin, selectSuiCoin, walletExists };