The pre-confirmations system provides early execution feedback for transactions before block finalization. When the block producer executes transactions during block production, it immediately broadcasts execution results (receipts, gas usage, fees, and output UTXOs) to the network. This enables applications to receive near-instant confirmation of transaction outcomes without waiting for block commitment.
This document covers the pre-confirmation generation, signing, and broadcasting mechanisms. For transaction lifecycle states including pre-confirmation statuses, see Transaction Lifecycle. For transaction status tracking and subscription mechanisms, see Transaction Status Tracking.
Sources: CHANGELOG.md2726-2856 crates/services/executor/src/executor.rs269-319
Diagram: Pre-confirmations System Data Flow
The system operates in two phases: generation on the block producer node and propagation to sentry nodes. The executor creates preconfirmation messages during transaction execution, which are then signed and broadcast via P2P. Receiving nodes use these messages to update local transaction statuses and manage their transaction pools.
Sources: crates/fuel-core/src/service/adapters/executor.rs109-138 CHANGELOG.md2726-2882
The Preconfirmation structure contains the transaction ID and its execution status:
Diagram: Preconfirmation Data Model
The Success and Failure variants include the complete execution results: gas consumed, fees paid, receipts from VM execution, and dynamic outputs (Change/Variable outputs with their UTXOIds). The SqueezedOut variant indicates the transaction was evicted from the block due to resource constraints.
Sources: crates/types/src/services/preconfirmation.rs (referenced from executor), crates/services/executor/src/executor.rs269-319
| Field | Source | Calculation |
|---|---|---|
tx_id | Transaction | tx.id(chain_id) |
tx_pointer | Block context | TxPointer::new(block_height, tx_index) |
total_gas | Execution result | From TransactionExecutionResult |
total_fee | Execution result | From TransactionExecutionResult |
receipts | VM execution | Arc-wrapped receipts from interpreter |
outputs | Transaction outputs | Filtered Change/Variable with non-zero amounts |
Sources: crates/services/executor/src/executor.rs269-319
The PreconfirmationSenderPort trait defines the interface for sending preconfirmations:
Diagram: Preconfirmation Sender Implementations
Two implementations exist:
TransparentPreconfirmationSender: A no-op implementation used in testing and when preconfirmations are disabledPreconfirmationSender: Production implementation that forwards to both the tx status manager and signature serviceSources: crates/services/executor/src/executor.rs259-267 crates/fuel-core/src/service/adapters/executor.rs109-138 crates/services/executor/src/ports.rs
Diagram: Preconfirmation Generation During Block Execution
During block production, after each transaction executes successfully in the VM, the executor immediately converts the execution result to a preconfirmation message. The try_send method is used to avoid blocking if the downstream channel is full—dropped preconfirmations are acceptable since the transaction status will eventually be confirmed when the block is imported.
Sources: crates/services/executor/src/executor.rs269-473 crates/services/upgradable-executor/src/executor.rs402-451
Diagram: Executor Initialization with Preconfirmation Support
The preconfirmation sender is passed during the produce_without_commit call. This design allows the executor to remain agnostic about how preconfirmations are handled—the caller injects the appropriate sender implementation based on the execution mode (production vs. dry-run vs. validation).
Sources: crates/services/executor/src/executor.rs392-420 crates/services/upgradable-executor/src/executor.rs439-473
The PreconfirmationSender implementation updates the transaction status manager synchronously before forwarding to the signature service:
This two-phase approach ensures that:
Sources: crates/fuel-core/src/service/adapters/executor.rs109-138
Preconfirmations use a dedicated gossipsub topic for broadcasting:
| Topic Name | Message Type | Purpose |
|---|---|---|
TX_PRECONFIRMATIONS | Vec<Preconfirmation> | Broadcast signed preconfirmation messages to network |
Sources: CHANGELOG.md2726
The signature service signs preconfirmation messages before broadcasting:
Diagram: Signature and Broadcasting Pipeline
The signature service runs as a separate task that consumes preconfirmations from the mpsc channel, signs them using configured delegate keys, and forwards to the P2P layer for broadcasting.
Sources: CHANGELOG.md2780-2856
When a node receives preconfirmation messages via P2P:
Diagram: Preconfirmation Reception on Sentry Nodes
Receiving nodes use preconfirmations to update their local view of transaction states and manage the transaction pool. Squeezed-out transactions are immediately removed, while successful preconfirmations may trigger promotion of dependent transactions in the mempool.
Sources: CHANGELOG.md2882-2885 CHANGELOG.md2800
Preconfirmations can be controlled via CLI flags:
| Flag | Default | Description |
|---|---|---|
--expensive-subscriptions | false | Enables preconfirmation subscriptions via GraphQL API |
--subscribe-to-transactions | false | Enables transaction gossip subscription (includes preconfirmations) |
When disabled, the system uses TransparentPreconfirmationSender which drops all preconfirmation messages.
Sources: CHANGELOG.md3068-3083
Preconfirmation failures are handled gracefully:
| Error Condition | Handling Strategy |
|---|---|
| Signature service channel full | Drop preconfirmations, continue block production |
| Invalid signature on reception | Report peer reputation, discard message |
| Network delivery failure | Best-effort delivery, no retry (idempotent) |
| Tx status manager update failure | Log error, continue processing |
The system is designed to never block block production due to preconfirmation processing failures. All preconfirmation operations are opportunistic—they improve user experience when successful but their failure does not affect consensus correctness.
Sources: crates/fuel-core/src/service/adapters/executor.rs109-138 CHANGELOG.md2824
For testing, two simplified implementations are provided:
| Implementation | Use Case | Behavior |
|---|---|---|
TransparentPreconfirmationSender | Unit tests, validation | Returns empty vec, drops all preconfirmations |
TimeoutOnlyTxWaiter | Testing without block time windows | Immediately returns timeout |
These allow testing of executor logic without requiring the full preconfirmation infrastructure.
Refresh this wiki