com_r35157_nenjim-hubd-impl_ref/openspec/changes/archive/2026-08-13-72-add-evelyn-iou-buyback-and-burn-service/proposal.md

Why

The available wallet, Jupiter, Solana transaction-awaiting, ticker, currency-identity, and notification services now make an automated Evelyn IOU buyback-and-burn flow possible, but no Evelyn-owned orchestration currently combines them with the transaction-safety rules needed to avoid duplicate swaps or burns. Issue #72 adds that orchestration while keeping stable AssetAZ UUIDs—not Solana integration details—as its configuration boundary.

What Changes

• Add an Evelyn-specific continuously running EvelynIOUBurnerService API and reference implementation with immediate, non-overlapping, fixed-delay iterations and explicit start/stop lifecycle behavior.
• Configure prioritized accepted inputs and their minimum reserves as an ordered defensive copy of List<MoneyAmount>, using each entry's AssetAZ UUID as authoritative and canonicalizing metadata through CurrencyIdentityService.
• Resolve native SOL and unique non-SOL solana-mint representations internally through CIS, detect supported SPL token programs and token precision through Solana, and keep mints/programs out of Evelyn's constructor configuration.
• Limit each iteration to at most one exact-input Jupiter attempt and to the configured USDC-equivalent ceiling, while preserving each currency's reserve and rounding downward to its supported precision.
• Reload and burn the complete visible EVE balance only with a fresh canonical EVE/USDT price, retain pending burn signatures until a definitive FINALIZED result, and make exactly one notification attempt after successful finalization.
• Suspend later swaps or burns for the current lifecycle when their submission outcome may be unknown; never automatically retry, rebuild, re-sign, or resubmit a transaction. Reset process-local pending and suspension state only on an explicit stop/start cycle.
• Clarify the existing Jupiter swap contract so the canonical SOL/WSOL mint may represent native SOL input without changing the existing swap(...) signature or SPL/Token-2022 behavior.
• Keep configuration parsing, Nenjim autorun wiring, persistence, generic burner abstractions, tests, and test hooks out of scope.

Capabilities

New Capabilities

• evelyn-iou-burner-service: Defines the Evelyn-specific configuration, identity resolution, buyback limit and priority rules, sequential lifecycle, complete-balance burn, pending/unknown transaction safety, finalization, and one-attempt notification behavior.

Modified Capabilities

• jupiter-swap-service: Explicitly supports native SOL input when represented by the canonical CIS-resolved SOL/WSOL mint while retaining the existing exact-input API and behavior for supported SPL token programs.

Impact

• Adds public API source under com.fanitas.evelyn.service.burner and its reference implementation under com.fanitas.evelyn.service.burner.impl.ref.
• Uses existing SolanaWallet, JupiterSwapService, SolanaBlockChain, TickerService, CurrencyIdentityService, BoundNotificationService, MoneyAmount, and ValueTags without adding dependencies or changing DeTag configuration.
• Updates JupiterSwapService JavaDoc and the active OpenSpec delta only; no composition-root, configuration-file, persistence, generated-source, or automated-test changes are included.