com_r35157_nenjim-hubd-impl_ref/openspec/changes/archive/2026-08-11-67-add-generic-await-transaction-support/proposal.md

Why

Submitting a Solana transaction only proves RPC acceptance, leaving callers unable to distinguish a requested on-chain commitment outcome from an unknown pending or dropped transaction. A generic wait operation is needed so future consumers can explicitly await processed, confirmed, or finalized outcomes without coupling submission to confirmation.

What Changes

• Add public Solana commitment and transaction-outcome types with strict status invariants and comprehensive timeout semantics.
• Add SolanaBlockChain.awaitTransaction(...) to poll getSignatureStatuses for an already submitted signature.
• Reuse the existing shared five-second RPC throttle while making gate acquisition interruptible and bounded by an overall monotonic deadline.
• Validate signatures and timeouts locally, strictly validate RPC responses, and reserve FAILED exclusively for on-chain execution errors observed at the requested commitment.
• Delegate every cached-wrapper call directly without caching or deduplication.
• Add the SolanaSlot ValueTag backed by nullable Long.

Capabilities

New Capabilities

• solana-transaction-awaiting: Generic blocking observation of an existing Solana transaction through a requested commitment level, with definitive success/failure and unknown-timeout semantics.

Modified Capabilities

None.

Impact

The Solana public API, reference RPC implementation, cached decorator, and shared Detag configuration are extended. Existing RPC operations retain their public behavior and common throttling; no wallet, Jupiter, burn, Evelyn, WebSocket, or transaction-submission consumer is changed to wait automatically.