@t2000/sdk 1.23.0 → 1.24.0

package/dist/index.d.cts

@@ -433,14 +433,15 @@ declare function selectSuiCoin(tx: Transaction, client: SuiJsonRpcClient, owner:
  */
 
 /**
- * Canonical write tools. The 9 tools that can be composed into a PTB.
+ * Canonical write tools. The 10 tools that can be composed into a PTB
+ * (Track B 2026-05-08 added `harvest_rewards`).
  *
  * 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';
+type WriteToolName = 'save_deposit' | 'withdraw' | 'borrow' | 'repay_debt' | 'send_transfer' | 'swap_execute' | 'claim_rewards' | 'harvest_rewards' | 'volo_stake' | 'volo_unstake';
 interface SaveDepositInput {
     amount: number;
     asset?: 'USDC' | 'USDsui';
@@ -474,6 +475,18 @@ interface SwapExecuteInput {
     providers?: string[];
 }
 type ClaimRewardsInput = Record<string, never>;
+/**
+ * [Track B] `harvest_rewards` accepts only optional tunables — no required
+ * inputs, since the user's choice is binary ("harvest now" or not). Default
+ * slippage 1%, default dust floor $0.01. The audric host's HARVEST chip
+ * passes literal `{}` and gets sensible defaults.
+ */
+interface HarvestRewardsInput {
+    /** Per-swap slippage tolerance (0.001–0.05). Default 0.01 (1%). */
+    slippage?: number;
+    /** USD floor for "is this worth swapping?" — dust below transfers to wallet. Default $0.01. */
+    minRewardUsd?: number;
+}
 interface VoloStakeInput {
     amountSui: number;
 }
@@ -522,6 +535,9 @@ type WriteStep = {
 } | {
     toolName: 'claim_rewards';
     input: ClaimRewardsInput;
+} | {
+    toolName: 'harvest_rewards';
+    input: HarvestRewardsInput;
 } | {
     toolName: 'volo_stake';
     input: VoloStakeInput;
@@ -641,6 +657,23 @@ type StepPreview = {
 } | {
     toolName: 'claim_rewards';
     rewards: PendingReward$1[];
+} | {
+    toolName: 'harvest_rewards';
+    claimed: PendingReward$1[];
+    swaps: Array<{
+        fromSymbol: string;
+        fromCoinType: string;
+        toSymbol: 'USDC';
+        inputAmount: number;
+        expectedOutputUsdc: number;
+    }>;
+    skipped: Array<{
+        symbol: string;
+        coinType: string;
+        amount: number;
+        reason: 'untradeable' | 'dust' | 'no-route';
+    }>;
+    expectedUsdcDeposited: number;
 } | {
     toolName: 'volo_stake';
     effectiveAmountMist: bigint;
@@ -719,7 +752,7 @@ type AppenderFn<TInput, TPreview extends StepPreview> = (tx: Transaction, input:
 /**
  * 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
+ * that all 10 `WriteToolName` values have an entry — TypeScript will
  * fail the build if a tool is missing.
  */
 declare const WRITE_APPENDER_REGISTRY: {
@@ -744,6 +777,9 @@ declare const WRITE_APPENDER_REGISTRY: {
     claim_rewards: AppenderFn<ClaimRewardsInput, Extract<StepPreview, {
         toolName: 'claim_rewards';
     }>>;
+    harvest_rewards: AppenderFn<HarvestRewardsInput, Extract<StepPreview, {
+        toolName: 'harvest_rewards';
+    }>>;
     volo_stake: AppenderFn<VoloStakeInput, Extract<StepPreview, {
         toolName: 'volo_stake';
     }>>;
@@ -794,6 +830,7 @@ declare function getFinancialSummary(client: SuiJsonRpcClient, walletAddress: st
 
 declare function getRates(client: SuiJsonRpcClient): Promise<RatesResult>;
 declare function getPendingRewards(client: SuiJsonRpcClient, address: string): Promise<PendingReward$1[]>;
+declare function addClaimRewardsToTx(tx: Transaction, 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
@@ -817,6 +854,156 @@ declare function buildClaimRewardsTx(client: SuiJsonRpcClient, address: string):
     tx: Transaction;
     rewards: PendingReward$1[];
 }>;
+/**
+ * Minimal shape we read off the NAVI SDK's `LendingReward` rows. Kept
+ * structural rather than imported so the tests don't have to reproduce
+ * the full upstream type and the function works for any future caller
+ * that has the same fields.
+ */
+interface ClaimableRewardLike {
+    userClaimableReward: number | string;
+    rewardCoinType: string;
+    assetId?: number | string;
+}
+/**
+ * Aggregate raw NAVI `claimable` rows into the `PendingReward[]` shape
+ * the engine surfaces to the LLM and the UI. Aggregates by reward coin
+ * type so a user with rewards from multiple pools (e.g. USDC pool + SUI
+ * pool both rewarding vSUI) sees a single "0.0165 vSUI" line rather
+ * than three separate dust entries. Filters out non-finite / non-positive
+ * amounts so dust noise can't sneak in as "$0.00 REWARD" rows.
+ */
+declare function aggregateClaimableRewards(claimable: ClaimableRewardLike[]): PendingReward$1[];
+
+/**
+ * NAVI rewards harvest — single-PTB compound flow.
+ *
+ * **Goal.** Bundle the three-step "claim → swap → save" reward-cycling
+ * routine into ONE atomic Programmable Transaction Block so the user
+ * sees ONE confirm card instead of three sequential ones, and so the
+ * legs settle together (or revert together — no half-claimed-but-
+ * unsaved drift).
+ *
+ * **Flow.**
+ *   1. Read pending rewards via NAVI's `getUserAvailableLendingRewards`
+ *      (same source as `getPendingRewards` + `addClaimRewardsToTx`, so
+ *      what the user sees in `pending_rewards` is exactly what gets
+ *      harvested — no drift).
+ *   2. Append `claimLendingRewardsPTB(... { customCoinReceive: { type: 'skip' }})`
+ *      so the claimed coin handles are returned as `TransactionObjectArgument`
+ *      handles instead of being transferred to the wallet — they stay
+ *      consumable inside the same PTB.
+ *   3. For each claimed handle:
+ *        • If the reward IS USDC, hold the handle for the deposit step.
+ *        • If the reward is in `COIN_REGISTRY` AND tradeable on Cetus
+ *          (any tier-2 token effectively), append `addSwapToTx` in chain
+ *          mode using the claimed coin as `inputCoin`. Collect the USDC
+ *          output handle.
+ *        • Else (untradeable / non-registry), transfer the claimed coin
+ *          back to the user's wallet — preserves the reward but skips
+ *          the auto-deposit (the user keeps it as a wallet asset).
+ *   4. Merge all collected USDC handles via `tx.mergeCoins`, then deposit
+ *      via `addSaveToTx`.
+ *
+ * **Atomicity.** Single PTB = single transaction = single sponsored-gas
+ * envelope. Either ALL legs settle (claim + swap(s) + deposit) or none
+ * do. No partial-state recovery code needed.
+ *
+ * **Sponsored-gas posture.** This builder appends ONLY chained move
+ * calls — no `tx.gas` reads, no Pyth fee writes, no oracle Pyth updates.
+ * Cetus chain-mode swaps with `slippage` ≤ 5% don't require Pyth either
+ * (Cetus aggregator routes around Pyth-dependent providers when callers
+ * pass `providers: getProvidersExcluding(...)`). Audric's host wires
+ * the provider exclusion automatically for Enoki sponsorship — see
+ * `cetus-swap.ts` JSDoc.
+ *
+ * **Dust filter.** Rewards with `amount * priceCache.get(symbol) <
+ * minRewardUsd` are skipped from the swap leg AND from the deposit —
+ * not worth the gas to swap dust. They get transferred back to the
+ * wallet (preserving on-chain truth: the claim happened, the swap
+ * didn't). Default minRewardUsd = $0.01.
+ *
+ * **Failure modes.**
+ *   - PROTOCOL_UNAVAILABLE — NAVI rewards lookup or claim PTB build failed.
+ *     Engine surfaces "NAVI is degraded right now."
+ *   - SWAP_NO_ROUTE — a reward asset has no Cetus route. Logged + that
+ *     leg is skipped (rewards transferred to wallet). Other legs proceed.
+ *   - INVALID_AMOUNT — rewards array empty after dust filter (nothing
+ *     worth harvesting). Throws so the engine narrates "nothing to
+ *     harvest right now" instead of building a no-op PTB.
+ *
+ * **Why a separate file (not inside `navi.ts`).** This composition
+ * crosses two protocols (NAVI + Cetus) — keeping it out of `navi.ts`
+ * preserves the single-protocol-per-file invariant the rest of the SDK
+ * follows. Mirrors how `cetus-swap.ts` already lives separately even
+ * though it composes through `composeTx.ts`.
+ */
+
+interface HarvestSwapLeg {
+    /** Reward symbol pre-swap (e.g. 'vSUI', 'NAVX'). */
+    fromSymbol: string;
+    /** Reward coinType pre-swap. */
+    fromCoinType: string;
+    /** Always 'USDC' — this builder only deposits to the USDC pool. */
+    toSymbol: 'USDC';
+    /** Display-units input amount (the entire claimed reward for that coin). */
+    inputAmount: number;
+    /** Display-units USDC the swap quote estimated. Actual on-chain may differ within slippage. */
+    expectedOutputUsdc: number;
+}
+interface HarvestSkippedLeg {
+    /** Reward symbol skipped (untradeable, dust, or no-route). */
+    symbol: string;
+    coinType: string;
+    /** Display-units claimed amount (still credited to user's wallet — just not auto-deposited). */
+    amount: number;
+    /** 'untradeable' | 'dust' | 'no-route' */
+    reason: 'untradeable' | 'dust' | 'no-route';
+}
+interface HarvestPlan {
+    /** Every reward that WILL be claimed by this PTB. */
+    claimed: PendingReward$1[];
+    /** Each non-USDC reward that WILL be swapped to USDC inline. */
+    swaps: HarvestSwapLeg[];
+    /** Rewards claimed but transferred back to wallet (no auto-deposit). */
+    skipped: HarvestSkippedLeg[];
+    /** Display-units USDC that will be deposited to the NAVI USDC pool. */
+    expectedUsdcDeposited: number;
+}
+interface BuildHarvestRewardsTxOptions {
+    /** Per-swap slippage tolerance (0.001–0.05). Defaults to 0.01 (1%). */
+    slippage?: number;
+    /**
+     * USD floor for "is this worth swapping?". Rewards below this threshold
+     * get transferred back to the wallet instead of swapped. Default $0.01.
+     * Pass 0 to disable the filter (always swap; useful for tests).
+     */
+    minRewardUsd?: number;
+    /**
+     * Symbol → USD price map. Sourced from the engine's `ToolContext.priceCache`
+     * in production; tests can pass a literal Map. When undefined, the dust
+     * filter degrades to "skip nothing" (every reward is swapped) so we don't
+     * accidentally drop large rewards just because we couldn't price them.
+     */
+    priceCache?: Map<string, number>;
+    /**
+     * Cetus provider allow-list. Sponsored callers (Enoki) pass
+     * `getProvidersExcluding(['pyth-dependent-list'])` to keep the PTB
+     * Pyth-free. Non-sponsored callers omit this.
+     */
+    providers?: string[];
+}
+/**
+ * Standalone harvest builder — creates a fresh PTB, sets the sender,
+ * appends the full harvest flow, and returns both the tx and the plan.
+ * Used by CLI / direct SDK callers (smoke tests, scripts). The audric
+ * host goes through `composeTx({ steps: [{ toolName: 'harvest_rewards' }] })`
+ * which wires the appender + Enoki sponsorship.
+ */
+declare function buildHarvestRewardsTx(client: SuiJsonRpcClient, address: string, options?: BuildHarvestRewardsTxOptions): Promise<{
+    tx: Transaction;
+    plan: HarvestPlan;
+}>;
 
 declare function getSwapQuote(params: {
     walletAddress: string;
@@ -1055,4 +1242,4 @@ declare function fullHandle(label: string): string;
  */
 declare function displayHandle(label: string): string;
 
-export { AUDRIC_PARENT_NAME, AUDRIC_PARENT_NFT_ID, type AppenderContext, BalanceResponse, type BorrowInput, BorrowResult, type BuildAddLeafParams, type BuildRevokeLeafParams, 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, type LabelValidationResult, 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, buildAddLeafTx, buildClaimRewardsTx, buildRevokeLeafTx, buildSendTx, buildStakeVSuiTx, buildUnstakeVSuiTx, composeTx, deriveAllowedAddressesFromPtb, displayHandle, exportPrivateKey, fetchAllCoins, fullHandle, generateKeypair, getAddress, getFinancialSummary, getPendingRewards, getRates, getSwapQuote, getVoloStats, keypairFromPrivateKey, loadKey, saveKey, selectAndSplitCoin, selectSuiCoin, validateLabel, walletExists };
+export { AUDRIC_PARENT_NAME, AUDRIC_PARENT_NFT_ID, type AppenderContext, BalanceResponse, type BorrowInput, BorrowResult, type BuildAddLeafParams, type BuildHarvestRewardsTxOptions, type BuildRevokeLeafParams, 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, type HarvestPlan, type HarvestSkippedLeg, type HarvestSwapLeg, HealthFactorResult, type LabelValidationResult, 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, addClaimRewardsToTx, addSendToTx, addStakeVSuiToTx, addUnstakeVSuiToTx, aggregateClaimableRewards, buildAddLeafTx, buildClaimRewardsTx, buildHarvestRewardsTx, buildRevokeLeafTx, buildSendTx, buildStakeVSuiTx, buildUnstakeVSuiTx, composeTx, deriveAllowedAddressesFromPtb, displayHandle, exportPrivateKey, fetchAllCoins, fullHandle, generateKeypair, getAddress, getFinancialSummary, getPendingRewards, getRates, getSwapQuote, getVoloStats, keypairFromPrivateKey, loadKey, saveKey, selectAndSplitCoin, selectSuiCoin, validateLabel, walletExists };

package/dist/index.d.ts

@@ -433,14 +433,15 @@ declare function selectSuiCoin(tx: Transaction, client: SuiJsonRpcClient, owner:
  */
 
 /**
- * Canonical write tools. The 9 tools that can be composed into a PTB.
+ * Canonical write tools. The 10 tools that can be composed into a PTB
+ * (Track B 2026-05-08 added `harvest_rewards`).
  *
  * 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';
+type WriteToolName = 'save_deposit' | 'withdraw' | 'borrow' | 'repay_debt' | 'send_transfer' | 'swap_execute' | 'claim_rewards' | 'harvest_rewards' | 'volo_stake' | 'volo_unstake';
 interface SaveDepositInput {
     amount: number;
     asset?: 'USDC' | 'USDsui';
@@ -474,6 +475,18 @@ interface SwapExecuteInput {
     providers?: string[];
 }
 type ClaimRewardsInput = Record<string, never>;
+/**
+ * [Track B] `harvest_rewards` accepts only optional tunables — no required
+ * inputs, since the user's choice is binary ("harvest now" or not). Default
+ * slippage 1%, default dust floor $0.01. The audric host's HARVEST chip
+ * passes literal `{}` and gets sensible defaults.
+ */
+interface HarvestRewardsInput {
+    /** Per-swap slippage tolerance (0.001–0.05). Default 0.01 (1%). */
+    slippage?: number;
+    /** USD floor for "is this worth swapping?" — dust below transfers to wallet. Default $0.01. */
+    minRewardUsd?: number;
+}
 interface VoloStakeInput {
     amountSui: number;
 }
@@ -522,6 +535,9 @@ type WriteStep = {
 } | {
     toolName: 'claim_rewards';
     input: ClaimRewardsInput;
+} | {
+    toolName: 'harvest_rewards';
+    input: HarvestRewardsInput;
 } | {
     toolName: 'volo_stake';
     input: VoloStakeInput;
@@ -641,6 +657,23 @@ type StepPreview = {
 } | {
     toolName: 'claim_rewards';
     rewards: PendingReward$1[];
+} | {
+    toolName: 'harvest_rewards';
+    claimed: PendingReward$1[];
+    swaps: Array<{
+        fromSymbol: string;
+        fromCoinType: string;
+        toSymbol: 'USDC';
+        inputAmount: number;
+        expectedOutputUsdc: number;
+    }>;
+    skipped: Array<{
+        symbol: string;
+        coinType: string;
+        amount: number;
+        reason: 'untradeable' | 'dust' | 'no-route';
+    }>;
+    expectedUsdcDeposited: number;
 } | {
     toolName: 'volo_stake';
     effectiveAmountMist: bigint;
@@ -719,7 +752,7 @@ type AppenderFn<TInput, TPreview extends StepPreview> = (tx: Transaction, input:
 /**
  * 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
+ * that all 10 `WriteToolName` values have an entry — TypeScript will
  * fail the build if a tool is missing.
  */
 declare const WRITE_APPENDER_REGISTRY: {
@@ -744,6 +777,9 @@ declare const WRITE_APPENDER_REGISTRY: {
     claim_rewards: AppenderFn<ClaimRewardsInput, Extract<StepPreview, {
         toolName: 'claim_rewards';
     }>>;
+    harvest_rewards: AppenderFn<HarvestRewardsInput, Extract<StepPreview, {
+        toolName: 'harvest_rewards';
+    }>>;
     volo_stake: AppenderFn<VoloStakeInput, Extract<StepPreview, {
         toolName: 'volo_stake';
     }>>;
@@ -794,6 +830,7 @@ declare function getFinancialSummary(client: SuiJsonRpcClient, walletAddress: st
 
 declare function getRates(client: SuiJsonRpcClient): Promise<RatesResult>;
 declare function getPendingRewards(client: SuiJsonRpcClient, address: string): Promise<PendingReward$1[]>;
+declare function addClaimRewardsToTx(tx: Transaction, 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
@@ -817,6 +854,156 @@ declare function buildClaimRewardsTx(client: SuiJsonRpcClient, address: string):
     tx: Transaction;
     rewards: PendingReward$1[];
 }>;
+/**
+ * Minimal shape we read off the NAVI SDK's `LendingReward` rows. Kept
+ * structural rather than imported so the tests don't have to reproduce
+ * the full upstream type and the function works for any future caller
+ * that has the same fields.
+ */
+interface ClaimableRewardLike {
+    userClaimableReward: number | string;
+    rewardCoinType: string;
+    assetId?: number | string;
+}
+/**
+ * Aggregate raw NAVI `claimable` rows into the `PendingReward[]` shape
+ * the engine surfaces to the LLM and the UI. Aggregates by reward coin
+ * type so a user with rewards from multiple pools (e.g. USDC pool + SUI
+ * pool both rewarding vSUI) sees a single "0.0165 vSUI" line rather
+ * than three separate dust entries. Filters out non-finite / non-positive
+ * amounts so dust noise can't sneak in as "$0.00 REWARD" rows.
+ */
+declare function aggregateClaimableRewards(claimable: ClaimableRewardLike[]): PendingReward$1[];
+
+/**
+ * NAVI rewards harvest — single-PTB compound flow.
+ *
+ * **Goal.** Bundle the three-step "claim → swap → save" reward-cycling
+ * routine into ONE atomic Programmable Transaction Block so the user
+ * sees ONE confirm card instead of three sequential ones, and so the
+ * legs settle together (or revert together — no half-claimed-but-
+ * unsaved drift).
+ *
+ * **Flow.**
+ *   1. Read pending rewards via NAVI's `getUserAvailableLendingRewards`
+ *      (same source as `getPendingRewards` + `addClaimRewardsToTx`, so
+ *      what the user sees in `pending_rewards` is exactly what gets
+ *      harvested — no drift).
+ *   2. Append `claimLendingRewardsPTB(... { customCoinReceive: { type: 'skip' }})`
+ *      so the claimed coin handles are returned as `TransactionObjectArgument`
+ *      handles instead of being transferred to the wallet — they stay
+ *      consumable inside the same PTB.
+ *   3. For each claimed handle:
+ *        • If the reward IS USDC, hold the handle for the deposit step.
+ *        • If the reward is in `COIN_REGISTRY` AND tradeable on Cetus
+ *          (any tier-2 token effectively), append `addSwapToTx` in chain
+ *          mode using the claimed coin as `inputCoin`. Collect the USDC
+ *          output handle.
+ *        • Else (untradeable / non-registry), transfer the claimed coin
+ *          back to the user's wallet — preserves the reward but skips
+ *          the auto-deposit (the user keeps it as a wallet asset).
+ *   4. Merge all collected USDC handles via `tx.mergeCoins`, then deposit
+ *      via `addSaveToTx`.
+ *
+ * **Atomicity.** Single PTB = single transaction = single sponsored-gas
+ * envelope. Either ALL legs settle (claim + swap(s) + deposit) or none
+ * do. No partial-state recovery code needed.
+ *
+ * **Sponsored-gas posture.** This builder appends ONLY chained move
+ * calls — no `tx.gas` reads, no Pyth fee writes, no oracle Pyth updates.
+ * Cetus chain-mode swaps with `slippage` ≤ 5% don't require Pyth either
+ * (Cetus aggregator routes around Pyth-dependent providers when callers
+ * pass `providers: getProvidersExcluding(...)`). Audric's host wires
+ * the provider exclusion automatically for Enoki sponsorship — see
+ * `cetus-swap.ts` JSDoc.
+ *
+ * **Dust filter.** Rewards with `amount * priceCache.get(symbol) <
+ * minRewardUsd` are skipped from the swap leg AND from the deposit —
+ * not worth the gas to swap dust. They get transferred back to the
+ * wallet (preserving on-chain truth: the claim happened, the swap
+ * didn't). Default minRewardUsd = $0.01.
+ *
+ * **Failure modes.**
+ *   - PROTOCOL_UNAVAILABLE — NAVI rewards lookup or claim PTB build failed.
+ *     Engine surfaces "NAVI is degraded right now."
+ *   - SWAP_NO_ROUTE — a reward asset has no Cetus route. Logged + that
+ *     leg is skipped (rewards transferred to wallet). Other legs proceed.
+ *   - INVALID_AMOUNT — rewards array empty after dust filter (nothing
+ *     worth harvesting). Throws so the engine narrates "nothing to
+ *     harvest right now" instead of building a no-op PTB.
+ *
+ * **Why a separate file (not inside `navi.ts`).** This composition
+ * crosses two protocols (NAVI + Cetus) — keeping it out of `navi.ts`
+ * preserves the single-protocol-per-file invariant the rest of the SDK
+ * follows. Mirrors how `cetus-swap.ts` already lives separately even
+ * though it composes through `composeTx.ts`.
+ */
+
+interface HarvestSwapLeg {
+    /** Reward symbol pre-swap (e.g. 'vSUI', 'NAVX'). */
+    fromSymbol: string;
+    /** Reward coinType pre-swap. */
+    fromCoinType: string;
+    /** Always 'USDC' — this builder only deposits to the USDC pool. */
+    toSymbol: 'USDC';
+    /** Display-units input amount (the entire claimed reward for that coin). */
+    inputAmount: number;
+    /** Display-units USDC the swap quote estimated. Actual on-chain may differ within slippage. */
+    expectedOutputUsdc: number;
+}
+interface HarvestSkippedLeg {
+    /** Reward symbol skipped (untradeable, dust, or no-route). */
+    symbol: string;
+    coinType: string;
+    /** Display-units claimed amount (still credited to user's wallet — just not auto-deposited). */
+    amount: number;
+    /** 'untradeable' | 'dust' | 'no-route' */
+    reason: 'untradeable' | 'dust' | 'no-route';
+}
+interface HarvestPlan {
+    /** Every reward that WILL be claimed by this PTB. */
+    claimed: PendingReward$1[];
+    /** Each non-USDC reward that WILL be swapped to USDC inline. */
+    swaps: HarvestSwapLeg[];
+    /** Rewards claimed but transferred back to wallet (no auto-deposit). */
+    skipped: HarvestSkippedLeg[];
+    /** Display-units USDC that will be deposited to the NAVI USDC pool. */
+    expectedUsdcDeposited: number;
+}
+interface BuildHarvestRewardsTxOptions {
+    /** Per-swap slippage tolerance (0.001–0.05). Defaults to 0.01 (1%). */
+    slippage?: number;
+    /**
+     * USD floor for "is this worth swapping?". Rewards below this threshold
+     * get transferred back to the wallet instead of swapped. Default $0.01.
+     * Pass 0 to disable the filter (always swap; useful for tests).
+     */
+    minRewardUsd?: number;
+    /**
+     * Symbol → USD price map. Sourced from the engine's `ToolContext.priceCache`
+     * in production; tests can pass a literal Map. When undefined, the dust
+     * filter degrades to "skip nothing" (every reward is swapped) so we don't
+     * accidentally drop large rewards just because we couldn't price them.
+     */
+    priceCache?: Map<string, number>;
+    /**
+     * Cetus provider allow-list. Sponsored callers (Enoki) pass
+     * `getProvidersExcluding(['pyth-dependent-list'])` to keep the PTB
+     * Pyth-free. Non-sponsored callers omit this.
+     */
+    providers?: string[];
+}
+/**
+ * Standalone harvest builder — creates a fresh PTB, sets the sender,
+ * appends the full harvest flow, and returns both the tx and the plan.
+ * Used by CLI / direct SDK callers (smoke tests, scripts). The audric
+ * host goes through `composeTx({ steps: [{ toolName: 'harvest_rewards' }] })`
+ * which wires the appender + Enoki sponsorship.
+ */
+declare function buildHarvestRewardsTx(client: SuiJsonRpcClient, address: string, options?: BuildHarvestRewardsTxOptions): Promise<{
+    tx: Transaction;
+    plan: HarvestPlan;
+}>;
 
 declare function getSwapQuote(params: {
     walletAddress: string;
@@ -1055,4 +1242,4 @@ declare function fullHandle(label: string): string;
  */
 declare function displayHandle(label: string): string;
 
-export { AUDRIC_PARENT_NAME, AUDRIC_PARENT_NFT_ID, type AppenderContext, BalanceResponse, type BorrowInput, BorrowResult, type BuildAddLeafParams, type BuildRevokeLeafParams, 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, type LabelValidationResult, 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, buildAddLeafTx, buildClaimRewardsTx, buildRevokeLeafTx, buildSendTx, buildStakeVSuiTx, buildUnstakeVSuiTx, composeTx, deriveAllowedAddressesFromPtb, displayHandle, exportPrivateKey, fetchAllCoins, fullHandle, generateKeypair, getAddress, getFinancialSummary, getPendingRewards, getRates, getSwapQuote, getVoloStats, keypairFromPrivateKey, loadKey, saveKey, selectAndSplitCoin, selectSuiCoin, validateLabel, walletExists };
+export { AUDRIC_PARENT_NAME, AUDRIC_PARENT_NFT_ID, type AppenderContext, BalanceResponse, type BorrowInput, BorrowResult, type BuildAddLeafParams, type BuildHarvestRewardsTxOptions, type BuildRevokeLeafParams, 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, type HarvestPlan, type HarvestSkippedLeg, type HarvestSwapLeg, HealthFactorResult, type LabelValidationResult, 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, addClaimRewardsToTx, addSendToTx, addStakeVSuiToTx, addUnstakeVSuiToTx, aggregateClaimableRewards, buildAddLeafTx, buildClaimRewardsTx, buildHarvestRewardsTx, buildRevokeLeafTx, buildSendTx, buildStakeVSuiTx, buildUnstakeVSuiTx, composeTx, deriveAllowedAddressesFromPtb, displayHandle, exportPrivateKey, fetchAllCoins, fullHandle, generateKeypair, getAddress, getFinancialSummary, getPendingRewards, getRates, getSwapQuote, getVoloStats, keypairFromPrivateKey, loadKey, saveKey, selectAndSplitCoin, selectSuiCoin, validateLabel, walletExists };