SDK should validate change VTXO dust before submitting collab exit

[arkanaai]

Summary

When a user initiates a collaborative exit, the SDK submits the intent to arkd without first checking whether the change VTXO left behind would fall below the dust threshold (330 sats). This causes arkd to reject the intent with a dust error that surfaces directly to the user — an error that should never reach them.

Current validation gaps

• `wallet.ts` checks `output.amount <= dustAmount` for explicit outputs ✓
• `ramps.ts` checks if fees exceed the offboard amount ✓
• `vtxo-manager.ts` skips periodic settle if `totalAmount < dustAmount` ✓

Missing: none of the above check whether the change VTXO remaining after a collab exit (`amount - offboard_amount - fees`) would be below dust.

Expected behaviour

Before submitting the intent to arkd, the SDK should compute the expected change amount (total VTXO amount − exit amount − onchain output fee of 200 sats) and, if it falls below dust (330 sats), fail fast with a clear, actionable error — e.g. "Amount too close to dust limit; consider exiting the full balance."

Note: the UX decision of what to show the user (e.g. offer to exit the full balance) belongs in the wallet layer, not the SDK. The SDK should simply reject early with a typed error so the wallet can handle it appropriately.

Steps to reproduce

1. Hold a VTXO where `amount - exit_amount - 200` < 330 sats
2. Trigger a collab exit for that partial amount
3. Observe the SDK submitting to arkd and returning a dust error to the user

Related files

• `wallet.ts`, `ramps.ts`, `vtxo-manager.ts`

[arkanaai]

Triage — arkanaai

Classification: Bug — missing pre-flight dust check on change VTXO in collab exit
Labels: bug

Root cause confirmed

The collab exit path in ramps.ts (offboard method, ~L151) checks that fees don't exceed the offboard amount (L239) but never validates whether the change VTXO left behind (total_vtxo_amount - exit_amount - onchain_output_fee) falls below dust (330 sats). The result is an arkd-side rejection that surfaces to the user as a raw dust error.

Existing dust guards in the codebase:

• wallet.ts:1498 — checks explicit output amounts
• wallet.ts:1340–1341 — selected.changeAmount < this.dustAmount in settle path
• ramps.ts:239 — fee-exceeds-amount guard

All miss the change VTXO after collab exit case.

Fix location

In ramps.ts, before submitting the intent, compute:

expectedChange = totalVtxoAmount - exitAmount - ONCHAIN_OUTPUT_FEE (200 sats)

If 0 < expectedChange < dustAmount (330 sats), throw a typed error. If expectedChange <= 0, allow (full exit). The wallet layer can then present appropriate UX (e.g. offer to exit full balance).

Medium severity — affects partial collab exits near dust boundary, no fund loss.