send

Build, fund, and sign a transaction that spends from the vault at the contract's current (index, unlockValue).

A time-lock vault is designed to be emptied in a single spend once it matures, so send always drains the entire spendable vault — every native UTXO, every token UTXO, and every group authority at the vault address — not just enough to fund dests + fee. Leaving coins behind would strand them at the vault address (re-locked at the contract rather than in the wallet's spendable balance), and a grouped input the completer is never told about would be silently melted.

The caller therefore does not have to size anything exactly; whatever dests does not account for comes back to the wallet:

• Native — the fee is deducted from the caller's native (ungrouped) output via DEDUCT_FEE_FROM_OUTPUT, and swept native beyond that output's amount is dumped into it as well (the output is the completer's adjustable output). With no native output in dests, surplus native returns as an ordinary change output — and the fee must come from the vault's own coin, see below.

• Tokens — a group dests pays gets its surplus back as a token change output; a group dests never mentions is auto-swept whole to a fresh wallet change destination.

• Authorities — an authority output in dests whose flag bits exactly match a vault authority UTXO consumes it (pass a baton along, for example); every unmatched vault authority is re-emitted verbatim to the change destination so it is never burned.

Two kinds of UTXO are deliberately left AT the vault, because sweeping them is impossible or destructive: authorities without the BATON bit (a child authority output requires a BATON-bearing parent, so spending one can only burn it) and fenced-group coins (fenced outputs encode the native amount as the group quantity; re-emitting the parsed amount would be an illegal script that sinks the whole sweep — fenced groups are unsupported wallet-wide).

A vault that is only PARTLY spendable right now — deposits below minConfirms, coins reserved by an in-flight build — simply sweeps the spendable subset: the sweep works whenever ANY vault UTXO is spendable (though dests must of course not ask for more than that subset holds).

Every input of the build is reserved while it is in flight and rolled back on any failure, so a concurrent send on the same vault fails cleanly instead of double-spending, and an oversized native output cannot make the completer re-select the pre-added inputs (that case fails with WalletNotEnoughBalanceException instead of building a duplicate-input transaction). On success the returned transaction's inputs REMAIN reserved — they belong to that tx now. A caller that decides not to broadcast it must release them with CommonWallet.abortTransaction, or the vault reads as unspendable for the rest of the session.

Flag rationale:

• FUND_NATIVE: every spend needs Nexa for fees. Without this, txCompleter can't pull Nexa from vault UTXOs and funding fails.

• FUND_GROUPS: lets txCompleter select token UTXOs to balance any grouped output the caller passed in. No-op when the caller only sends Nexa.

• USE_GROUP_AUTHORITIES: authorises spending authority UTXOs. The sweep pre-adds the vault's own authorities itself (matched or re-emitted, see above), so the completer's authority-selection passes normally have nothing left to do — but the flag must still be set, or an authority-bearing output in dests throws WalletAuthorityException in the completer's missing-authority accounting.

Caveat — same flag also enables minting: in wallet.kt the same bit also gates path 1 (mint-to-cover-deficit). So a caller that passes a grouped output asking for more tokens than the vault holds, with a MINT authority present in the vault, will get a silent mint to cover the shortfall. This is a known overloading of the flag in the underlying API — there is no flag combination today that gives baton passthrough without also permitting mint-to-cover. Caller is responsible for not requesting grouped outputs exceeding the vault's token balance if minting is undesired.