Transaction Validation and Assembly

Relevant source files

• crates/client/assets/schema.sdl
• crates/client/src/client.rs
• crates/client/src/client/schema/snapshots/fuel_core_client__client__schema__tx__tests__opaque_transaction_by_id_query_gql_output.snap
• crates/client/src/client/schema/snapshots/fuel_core_client__client__schema__tx__tests__transactions_by_owner_gql_output.snap
• crates/client/src/client/schema/snapshots/fuel_core_client__client__schema__tx__tests__transactions_connection_query_gql_output.snap
• crates/client/src/client/schema/snapshots/fuel_core_client__client__schema__tx__tests__transparent_transaction_by_id_query_gql_output.snap
• crates/client/src/client/schema/tx.rs
• crates/client/src/client/types.rs
• crates/fuel-core/src/schema/tx.rs
• crates/fuel-core/src/schema/tx/types.rs
• tests/tests/lib.rs
• tests/tests/tx.rs

This page documents the transaction validation and assembly mechanisms in fuel-core, which enable transactions to be validated, tested, and properly constructed before submission to the transaction pool. This includes dry-run execution for testing, predicate gas estimation, and automated transaction assembly with coin selection and fee calculation.

For information about transaction lifecycle states after submission, see Transaction Lifecycle. For details about the transaction pool's validation logic, see Transaction Pool Architecture.

Overview

Transaction validation and assembly in fuel-core provides three primary capabilities:

1. Dry Run Execution: Execute transactions in a sandboxed environment without committing state changes, used for testing and fee estimation
2. Predicate Estimation: Calculate the gas requirements for predicates within a transaction
3. Transaction Assembly: Automatically construct complete transactions by selecting UTXOs, calculating fees, and adding necessary inputs/outputs

These operations are exposed through both the GraphQL API and the client SDK, allowing applications to validate and build transactions before submission.

Dry Run Execution

Purpose and Architecture

Dry run execution allows transactions to be executed against the current (or historical) blockchain state without committing any changes. This is essential for:

• Testing transaction logic before submission
• Estimating gas consumption and fees
• Validating transaction parameters
• Debugging contract interactions

Sources: crates/fuel-core/src/schema/tx.rs124-195 crates/client/src/client.rs699-731

Configuration Parameters

The dry run operation accepts several optional parameters to control execution behavior:

Parameter	Type	Purpose
utxo_validation	Option<bool>	If false, disables UTXO existence and signature checks, allowing read-only calls with non-existent inputs
gas_price	Option<U64>	Override gas price for fee calculation
block_height	Option<U32>	Execute at a specific historical block height (requires --historical-execution flag)
record_storage_reads	bool	Record all storage reads for execution replay/debugging

Sources: crates/fuel-core/src/schema/tx.rs124-195 crates/client/assets/schema.sdl1062

Implementation Flow

The dry run process follows this sequence:

Sources: crates/fuel-core/src/schema/tx.rs124-195 crates/fuel-core/src/schema/tx.rs550-589

Result Types

Dry run execution returns a status for each transaction indicating success or failure:

Sources: crates/client/src/client/schema/tx.rs350-411 crates/client/assets/schema.sdl336-353

Storage Read Replay

When record_storage_reads is enabled, the dry run also returns a log of all storage accesses, allowing the execution to be replayed locally for debugging:

Sources: crates/fuel-core/src/schema/tx.rs574-589 crates/client/assets/schema.sdl1067-1071

Predicate Estimation

Purpose

Predicates are executable scripts that control the spending of UTXOs. Before a transaction can be executed, the gas cost of evaluating all predicates must be estimated and included in the transaction. Predicate estimation calculates these costs and updates the transaction accordingly.

Sources: crates/fuel-core/src/schema/tx.rs518-535 crates/client/src/client.rs851-860

Implementation

The estimate_predicates operation:

1. Accepts a transaction (as HexString)
2. Creates a ReadView to access current consensus parameters
3. Calls the EstimatePredicates trait method from fuel-vm
4. Returns the updated transaction with predicate_gas_used fields populated

Sources: crates/fuel-core/src/schema/tx.rs518-535

Integration with Transaction Assembly

Predicate estimation is a critical step in transaction assembly. The assemble_tx operation includes an estimate_predicates parameter that, when enabled, automatically estimates predicates before calculating final fees:

Sources: crates/fuel-core/src/schema/tx.rs372-515 crates/client/assets/schema.sdl1043-1046

Transaction Assembly

Overview

Transaction assembly is the process of taking an application-level transaction (containing only business logic) and transforming it into a complete, executable transaction by:

1. Selecting input coins to cover required balances
2. Selecting additional coins to cover transaction fees
3. Adding Change or Destroy outputs for remaining assets
4. Adding Variable outputs if needed during execution
5. Adding Contract inputs/outputs if contracts are used
6. Reserving witness slots for signature verification
7. Setting the script gas limit
8. Optionally estimating predicates

Sources: crates/fuel-core/src/schema/tx.rs372-515 crates/client/assets/schema.sdl997-1050

Input Parameters

The assemble_tx operation requires the following parameters:

Parameter	Type	Description
tx	HexString	The base transaction containing application logic only
block_horizon	U32	Number of blocks into the future to estimate gas price for
required_balances	Vec<RequiredBalance>	List of assets and amounts needed by the application, with change policies
fee_address_index	U16	Index into required_balances indicating which address pays the fee
exclude_input	Option<ExcludeInput>	UTXOs and messages to exclude from coin selection
estimate_predicates	Option<bool>	Whether to estimate predicate gas before fee calculation
reserve_gas	Option<U64>	Additional gas to reserve when calculating fees

Sources: crates/fuel-core/src/schema/tx.rs372-409 crates/client/assets/schema.sdl1021-1050

RequiredBalance Structure

Each required balance specifies an asset, amount, and how change should be handled:

Sources: crates/client/assets/schema.sdl1233-1238 crates/client/assets/schema.sdl142-152

Assembly Process Flow

The transaction assembly implementation is delegated to the AssembleTx struct, which handles different transaction types:

Sources: crates/fuel-core/src/schema/tx.rs467-515 crates/fuel-core/src/schema/tx/assemble_tx.rs

Validation and Error Handling

The assembly process includes multiple validation checks:

1. Input Count Validation: Ensures required balances and excluded inputs don't exceed max_inputs from consensus parameters
2. Fee Address Index Validation: Verifies the fee payer index is within bounds
3. Change Policy Consistency: Ensures the same asset doesn't have conflicting change policies
4. Duplicate Asset Check: Validates no duplicate entries in required balances
5. Sufficient Balance Check: Confirms accounts have enough assets to cover requirements
6. Consensus Rule Validation: Ensures the final transaction adheres to all consensus parameter constraints

Sources: crates/fuel-core/src/schema/tx.rs414-437

Final Dry Run

After assembly completes, a final dry run is performed to validate the transaction and obtain execution status:

Sources: crates/fuel-core/src/schema/tx.rs488-514

Result Structure

The assembly operation returns an AssembleTransactionResult containing:

• transaction: The fully assembled transaction ready for submission
• status: The dry run execution status (success or failure with details)
• gasPrice: The gas price used for fee calculation

Sources: crates/client/assets/schema.sdl8-12 crates/client/src/client/types/assemble_tx.rs

Client SDK Interface

FuelClient Methods

The Rust client SDK exposes these validation and assembly methods:

Sources: crates/client/src/client.rs699-860

Usage Example Pattern

A typical client usage pattern for transaction assembly:

1. Create application-level transaction with business logic
2. Define required balances for assets needed
3. Call assemble_tx to build complete transaction
4. Optionally perform additional dry runs for testing
5. Submit via submit or submit_and_await_commit

Sources: tests/tests/tx.rs86-359

GraphQL Schema Definition

The GraphQL schema defines the validation and assembly operations:

Operation	Type	Description
dryRun	Query	Execute transactions without committing (also available as deprecated Mutation)
dryRunRecordStorageReads	Query	Dry run with storage read recording
storageReadReplay	Query	Retrieve storage reads for a historical block
estimatePredicates	Query	Estimate predicate gas costs
assembleTx	Query	Assemble complete transaction with coin selection

Sources: crates/client/assets/schema.sdl945-1172

Historical Execution Support

When the --historical-execution flag is enabled, dry run and storage read replay operations can execute transactions at specific historical block heights. This requires the HistoricalRocksDB storage backend to maintain past state snapshots.

Sources: crates/fuel-core/src/schema/tx.rs146-151 crates/fuel-core/src/schema/tx.rs599-604

Integration Points

Transaction validation and assembly integrates with several other fuel-core systems:

• Executor Service: Performs actual transaction execution for dry runs (see Core Execution Engine)
• Transaction Pool: Uses validation logic before accepting transactions (see Transaction Pool Architecture)
• Block Producer: Provides dry run execution capabilities (see Block Production Pipeline)
• Gas Price Service: Supplies gas price estimates for fee calculation (see Gas Price Service)
• Storage Layer: Provides consistent views and historical state access (see Storage Layer)

Sources: crates/fuel-core/src/schema/tx.rs1-117