UTXO Discovery
Before a transaction can be planned, HardKAS must discover which UTXOs (Unspent Transaction Outputs) are available to fund the intent.
Sources of Truth
HardKAS dynamically resolves UTXOs based on the execution environment:
- Simulator (
simulated): Reads UTXOs directly from the local.hardkas/localnet.jsonsynthetic state. - Real Node (
kaspa-rpc/localnet): Queries the Kaspa network via JSON-RPC (getUtxosByAddress).
Safety Orchestration
HardKAS Safety Filtering ≠ Kaspa Consensus Validation.
UTXO discovery and pre-planning safety are execution-path dependent. The CLI real-node path applies strict filtering before passing UTXOs to the underlying planner algorithm; other paths have their own boundaries.
1. Maturity Filtering
If a UTXO is a coinbase output, HardKAS enforces maturity limits. The protocol requires coinbase outputs to mature for a specific number of DAA blocks (e.g., 100).
- HardKAS Margin: For CLI real-node environments, HardKAS orchestration applies a safety margin of
+ 10 DAA blockson top of the protocol requirement to protect againstmempool-vs-virtual-DAAraces.
2. Pending-Spend Protection
HardKAS tracks UTXOs that have been signed and submitted to the mempool but are not yet reflected in the DAG (excludeOutpoints). It automatically excludes these outpoints from discovery to prevent frustrating double-spend errors during local testing.
3. Selected-Input Re-validation
Planning validity is UTXO-scoped, not virtual-state-scoped. On a live network blocks keep arriving while a plan is built, and that alone never invalidates it. At the end of each planning attempt the CLI re-reads the node: every selected input must still be in the address UTXO set, and the node's mempool must not show a transaction spending it. Otherwise the attempt is retried; after the bounded retries it fails with SELECTED_UTXO_INVALIDATED. The virtual state fingerprints taken before and after are recorded in the plan (metadata.planningWindow) as evidence only.
This check is local to the node that was read. An input missing from that node's mempool may still be spent elsewhere on the network, and a competing spend can still appear before the transaction is submitted; the node then refuses the transaction.
Important Semantic Distinction
Fund recipient eligibility does NOT equal signing authority. Just because HardKAS discovers UTXOs at an address and builds a transaction plan does not mean the user actually holds the private key required to authorize those inputs. Discovery operates strictly on public DAG data.