#include <tx_execution.hpp>

Public Member Functions
	TxExecution (ExecutionInterface &call_execution, ContextProviderInterface &context_provider, ContractDBInterface &contract_db, HighLevelMerkleDBInterface &merkle_db, WrittenPublicDataSlotsTreeCheckInterface &written_public_data_slots_tree, RetrievedBytecodesTreeCheckInterface &retrieved_bytecodes_tree, SideEffectTrackerInterface &side_effect_tracker, FieldGreaterThanInterface &field_gt, Poseidon2Interface &poseidon2, CallStackMetadataCollectorInterface &call_stack_metadata_collector, EventEmitterInterface< TxEvent > &event_emitter, bool skip_fee_enforcement=false)

TxExecutionResult	simulate (const Tx &tx)
	Simulates the entire transaction execution phases.

Private Member Functions
void	insert_non_revertibles (const Tx &tx)
	Insert the non-revertible accumulated data into the Merkle DB and emit corresponding events. It might error if the limits for the number of allowable inserts are exceeded or a nullifier collision occurs, either of which results in an unprovable tx.

void	insert_revertibles (const Tx &tx)
	Insert the revertible accumulated data into the Merkle DB and emit corresponding events. A side-effect limit error is recoverable (the caller reverts to post-setup); a nullifier collision is unrecoverable (the tx is unprovable).

void	emit_public_call_request (const PublicCallRequestWithCalldata &call, TransactionPhase phase, const FF &transaction_fee, bool success, const Gas &start_gas, const Gas &end_gas, const TxContextEvent &state_before, const TxContextEvent &state_after)
	Handle a public call request and emit a TxPhaseEvent event with the embedded event type EnqueuedCallEvent.

void	pay_fee (const AztecAddress &fee_payer, const FF &fee, const uint128_t &fee_per_da_gas, const uint128_t &fee_per_l2_gas)
	Pay the fee for the transaction and emit a TxPhaseEvent event with the embedded event type CollectGasFeeEvent.

void	emit_l2_to_l1_message (bool revertible, const ScopedL2ToL1Message &l2_to_l1_message)
	Handle an L2 to L1 message insertion and emit a TxPhaseEvent event with the embedded event type PrivateEmitL2L1MessageEvent. The side effect tracker is used to track the L2 to L1 messages.

void	emit_nullifier (bool revertible, const FF &nullifier)
	Handle a nullifier insertion and emit a TxPhaseEvent event with the embedded event type PrivateAppendTreeEvent.

void	emit_note_hash (bool revertible, const FF &note_hash)
	Handle a note hash insertion and emit a TxPhaseEvent event with the embedded event type PrivateAppendTreeEvent.

void	pad_trees ()
	Pad the note hash and nullifier trees and emit a TxPhaseEvent event with the embedded event type PadTreesEvent.

void	cleanup ()
	Emit a TxPhaseEvent event with the embedded event type CleanupEvent. This is used to finalize the accounting of some state changes and side effects.

void	emit_empty_phase (TransactionPhase phase)
	Emit a TxPhaseEvent event with the embedded event type EmptyPhaseEvent. This is used to indicate that a phase has no events, but in tracegen we use it to populate a so-called padded (placeholder) row.

std::string	get_debug_function_name (const AztecAddress &contract_address, const std::vector< FF > &calldata)
	Get the debug function name for a given contract address and calldata.

Detailed Description

Definition at line 34 of file tx_execution.hpp.

Constructor & Destructor Documentation

◆ TxExecution()

bb::avm2::simulation::TxExecution::TxExecution	(	ExecutionInterface &	call_execution,
		ContextProviderInterface &	context_provider,
		ContractDBInterface &	contract_db,
		HighLevelMerkleDBInterface &	merkle_db,
		WrittenPublicDataSlotsTreeCheckInterface &	written_public_data_slots_tree,
		RetrievedBytecodesTreeCheckInterface &	retrieved_bytecodes_tree,
		SideEffectTrackerInterface &	side_effect_tracker,
		FieldGreaterThanInterface &	field_gt,
		Poseidon2Interface &	poseidon2,
		CallStackMetadataCollectorInterface &	call_stack_metadata_collector,
		EventEmitterInterface< TxEvent > &	event_emitter,
		bool	skip_fee_enforcement = `false`
	)

inline

Definition at line 36 of file tx_execution.hpp.

Member Function Documentation

◆ cleanup()

void bb::avm2::simulation::TxExecution::cleanup ( )

private

Emit a TxPhaseEvent event with the embedded event type CleanupEvent. This is used to finalize the accounting of some state changes and side effects.

Definition at line 690 of file tx_execution.cpp.

◆ emit_empty_phase()

void bb::avm2::simulation::TxExecution::emit_empty_phase ( TransactionPhase phase )

private

Emit a TxPhaseEvent event with the embedded event type EmptyPhaseEvent. This is used to indicate that a phase has no events, but in tracegen we use it to populate a so-called padded (placeholder) row.

Parameters

phase The phase to emit the empty phase event for.

Definition at line 707 of file tx_execution.cpp.

◆ emit_l2_to_l1_message()

void bb::avm2::simulation::TxExecution::emit_l2_to_l1_message	(	bool	revertible,
		const ScopedL2ToL1Message &	l2_to_l1_message
	)

private

Handle an L2 to L1 message insertion and emit a TxPhaseEvent event with the embedded event type PrivateEmitL2L1MessageEvent. The side effect tracker is used to track the L2 to L1 messages.

Parameters

revertible	Whether the L2 to L1 message is revertible.
l2_to_l1_message	The L2 to L1 message to insert.

Exceptions

TxExecutionException if the maximum number of L2 to L1 messages is reached.

Definition at line 472 of file tx_execution.cpp.

◆ emit_note_hash()

void bb::avm2::simulation::TxExecution::emit_note_hash	(	bool	revertible,
		const FF &	note_hash
	)

private

Handle a note hash insertion and emit a TxPhaseEvent event with the embedded event type PrivateAppendTreeEvent.

Parameters

revertible	Whether the note hash is revertible.
note_hash	The note hash to insert. If revertible, it is siloed but not unique. Otherwise, it is unique.

Exceptions

TxExecutionException if the maximum number of note hashes is reached.

Definition at line 429 of file tx_execution.cpp.

◆ emit_nullifier()

void bb::avm2::simulation::TxExecution::emit_nullifier	(	bool	revertible,
		const FF &	nullifier
	)

private

Handle a nullifier insertion and emit a TxPhaseEvent event with the embedded event type PrivateAppendTreeEvent.

Parameters

revertible	Whether the nullifier is revertible.
nullifier	The nullifier to insert.

Exceptions

TxExecutionException	if the maximum number of nullifiers is reached.
NullifierCollisionException	if the nullifier collides with an existing one (unrecoverable).

Definition at line 378 of file tx_execution.cpp.

◆ emit_public_call_request()

void bb::avm2::simulation::TxExecution::emit_public_call_request	(	const PublicCallRequestWithCalldata &	call,
		TransactionPhase	phase,
		const FF &	transaction_fee,
		bool	success,
		const Gas &	start_gas,
		const Gas &	end_gas,
		const TxContextEvent &	state_before,
		const TxContextEvent &	state_after
	)

private

Handle a public call request and emit a TxPhaseEvent event with the embedded event type EnqueuedCallEvent.

Parameters

call	The public call request with calldata.
phase	The phase in which the call is executed.
transaction_fee	The transaction fee to be paid.
success	Whether the call succeeded.
start_gas	The gas used at the start of the call.
end_gas	The gas used at the end of the call.
state_before	The state before the call.
state_after	The state after the call.

Definition at line 343 of file tx_execution.cpp.

◆ get_debug_function_name()

std::string bb::avm2::simulation::TxExecution::get_debug_function_name	(	const AztecAddress &	contract_address,
		const std::vector< FF > &	calldata
	)

private

Get the debug function name for a given contract address and calldata.

Parameters

contract_address	The address of the contract.
calldata	The calldata of the function.

Returns: The debug function name or a placeholder string if the debug function name is not found.

Definition at line 724 of file tx_execution.cpp.

◆ insert_non_revertibles()

void bb::avm2::simulation::TxExecution::insert_non_revertibles ( const Tx & tx )

private

Insert the non-revertible accumulated data into the Merkle DB and emit corresponding events. It might error if the limits for the number of allowable inserts are exceeded or a nullifier collision occurs, either of which results in an unprovable tx.

Parameters

tx	The transaction to insert the non-revertible accumulated data into.

Exceptions

TxExecutionException	if the maximum number of nullifiers, note hashes, or L2 to L1 messages is reached.
NullifierCollisionException	if a nullifier collision occurs (unrecoverable).

Definition at line 511 of file tx_execution.cpp.

◆ insert_revertibles()

void bb::avm2::simulation::TxExecution::insert_revertibles ( const Tx & tx )

private

Insert the revertible accumulated data into the Merkle DB and emit corresponding events. A side-effect limit error is recoverable (the caller reverts to post-setup); a nullifier collision is unrecoverable (the tx is unprovable).

Parameters

tx	The transaction to insert the revertible accumulated data into.

Exceptions

TxExecutionException	if the maximum number of nullifiers, note hashes, or L2 to L1 messages is reached.
NullifierCollisionException	if a nullifier collision occurs (unrecoverable).

Definition at line 564 of file tx_execution.cpp.

◆ pad_trees()

void bb::avm2::simulation::TxExecution::pad_trees ( )

private

Pad the note hash and nullifier trees and emit a TxPhaseEvent event with the embedded event type PadTreesEvent.

Definition at line 673 of file tx_execution.cpp.

◆ pay_fee()

void bb::avm2::simulation::TxExecution::pay_fee	(	const AztecAddress &	fee_payer,
		const FF &	fee,
		const uint128_t &	fee_per_da_gas,
		const uint128_t &	fee_per_l2_gas
	)

private

Pay the fee for the transaction and emit a TxPhaseEvent event with the embedded event type CollectGasFeeEvent.

Parameters

fee_payer	The address of the fee payer.
fee	The fee to be paid.
fee_per_da_gas	The fee per DA gas.
fee_per_l2_gas	The fee per L2 gas.

Exceptions

TxExecutionException if the fee payer does not have enough balance to pay the fee.

Definition at line 618 of file tx_execution.cpp.

◆ simulate()

TxExecutionResult bb::avm2::simulation::TxExecution::simulate ( const Tx & tx )

Simulates the entire transaction execution phases.

There are multiple distinct transaction phases that are executed in order:

Non-revertible insertions:
- nullifiers (0)
- note hashes (1)
- L2 to L1 messages (2)
Setup phase (3), where the setup enqueued calls are executed.
Revertible insertions:
- nullifiers (4)
- note hashes (5)
- L2 to L1 messages (6)
App Logic phase (7), where the app logic enqueued calls are executed.
Teardown phase (8), where the teardown enqueued call is executed.
Collect Gas Fees (9)
Tree padding (10)
Cleanup (11)

If an error occurs during non-revertible insertions or a Setup phase enqueued call fails, the transaction is considered unprovable and an unrecoverable exception is thrown. If a side-effect limit is reached during revertible insertions or App Logic phase fails, all the state changes are reverted to the post-setup state and we continue with the Teardown phase. A nullifier collision during revertible insertions is ALSO unprovable (not revertible): the nullifier originated from private, so a collision indicates the tx should never have been proposed. The NullifierCollisionException propagates out of simulate() as-is. If an error occurs during Teardown phase, all the state changes are reverted to the post-setup state and we continue with the Collect Gas Fees phase.

The phase values and their order are reflected in the enum TransactionPhase in aztec_types.hpp. These values are emitted as part of the TxPhaseEvent.

Parameters

tx	The transaction to simulate.

Returns: The result of the transaction simulation.

Exceptions

NullifierCollisionException	if a private nullifier collision occurs in either the non-revertible or revertible insertion phase.
TxExecutionException	if the maximum number of nullifiers, note hashes, or L2 to L1 messages is reached as part of the non-revertible insertions. a Setup phase enqueued call fails. the fee payer does not have enough balance to pay the fee. Note: Other low-level exceptions of other types are not caught and will be thrown.

Definition at line 84 of file tx_execution.cpp.

Member Data Documentation

◆ call_execution

ExecutionInterface& bb::avm2::simulation::TxExecution::call_execution

private

Definition at line 67 of file tx_execution.hpp.

◆ call_stack_metadata_collector

CallStackMetadataCollectorInterface& bb::avm2::simulation::TxExecution::call_stack_metadata_collector

private

Definition at line 73 of file tx_execution.hpp.

◆ context_provider

ContextProviderInterface& bb::avm2::simulation::TxExecution::context_provider

private

Definition at line 68 of file tx_execution.hpp.

◆ contract_db

ContractDBInterface& bb::avm2::simulation::TxExecution::contract_db

private

Definition at line 69 of file tx_execution.hpp.

◆ events

EventEmitterInterface<TxEvent>& bb::avm2::simulation::TxExecution::events

private

Definition at line 74 of file tx_execution.hpp.

◆ field_gt

FieldGreaterThanInterface& bb::avm2::simulation::TxExecution::field_gt

private

Definition at line 71 of file tx_execution.hpp.

◆ merkle_db

HighLevelMerkleDBInterface& bb::avm2::simulation::TxExecution::merkle_db

private

Definition at line 70 of file tx_execution.hpp.

◆ poseidon2

Poseidon2Interface& bb::avm2::simulation::TxExecution::poseidon2

private

Definition at line 72 of file tx_execution.hpp.

◆ skip_fee_enforcement

bool bb::avm2::simulation::TxExecution::skip_fee_enforcement

private

Definition at line 77 of file tx_execution.hpp.

◆ tx_context

TxContext bb::avm2::simulation::TxExecution::tx_context

private

Definition at line 76 of file tx_execution.hpp.

The documentation for this class was generated from the following files:

src/barretenberg/vm2/simulation/gadgets/tx_execution.hpp
src/barretenberg/vm2/simulation/gadgets/tx_execution.cpp

Private Attributes
ExecutionInterface &	call_execution

ContextProviderInterface &	context_provider

ContractDBInterface &	contract_db

HighLevelMerkleDBInterface &	merkle_db

FieldGreaterThanInterface &	field_gt

Poseidon2Interface &	poseidon2

CallStackMetadataCollectorInterface &	call_stack_metadata_collector

EventEmitterInterface< TxEvent > &	events

TxContext	tx_context

bool	skip_fee_enforcement

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ TxExecution()

Member Function Documentation

◆ cleanup()

◆ emit_empty_phase()

◆ emit_l2_to_l1_message()

◆ emit_note_hash()

◆ emit_nullifier()

◆ emit_public_call_request()

◆ get_debug_function_name()

◆ insert_non_revertibles()

◆ insert_revertibles()

◆ pad_trees()

◆ pay_fee()

◆ simulate()

Member Data Documentation

◆ call_execution

◆ call_stack_metadata_collector

◆ context_provider

◆ contract_db

◆ events

◆ field_gt

◆ merkle_db

◆ poseidon2

◆ skip_fee_enforcement

◆ tx_context