Skip to main content

starknet_simulateTransactions RPC Method

Simulate a given sequence of transactions on the requested state, and generate the execution traces.

Updated on
Mar 18, 2024
Please note that some of the transactions may revert, in which case no error is thrown, but revert details can be seen on the returned trace object. Additionally, the revert_error property in the trace will indicate any transactions that have experienced a revert. Other types of failures (e.g. unexpected error or failure in the validation phase) will result in TRANSACTION_EXECUTION_ERROR.

Parameters

block_id
string
REQUIRED

The hash of the requested block, the block number (height) of the requested block, or a block tag (latest, pre_confirmed, or l1_accepted), for the block referencing the state or call the transaction on

transactions
array
REQUIRED

The sequence of transactions to simulate, running each transaction on the state resulting from applying all the previous ones. It can take one of the following objects:

BROADCASTED_INVOKE_TXN_V3
object

The broadcasted invoke transaction v3 object which contains the following fields:

type
string
REQUIRED

The type of declare. It can take only one value - 'INVOKE'

sender_address
string
REQUIRED

The sender address

calldata
array
REQUIRED

The parameters passed to the constructor

version
string
REQUIRED

The version of the transaction scheme

signature
string
REQUIRED

The signature associated with the transaction

nonce
string
REQUIRED

The nonce value

resource_bounds
object
REQUIRED

The resource bounds for the transaction execution

l1_gas
object
REQUIRED

The max amount and max price per unit of L1 gas used in this tx

max_amount
string
REQUIRED

The max amount of the resource that can be used in the tx

max_price_per_unit
string
REQUIRED

The max price per unit of this resource for this tx

l1_data_gas
object
REQUIRED

The max amount and max price per unit of L1 data gas used in this tx

max_amount
string
REQUIRED

The max amount of the resource that can be used in the tx

max_price_per_unit
string
REQUIRED

The max price per unit of this resource for this tx

l2_gas
object
REQUIRED

The max amount and max price per unit of L2 gas used in this tx

max_amount
string
REQUIRED

The max amount of the resource that can be used in the tx

max_price_per_unit
string
REQUIRED

The max price per unit of this resource for this tx

tip
string
REQUIRED

The tip for the transaction

paymaster_data
array
REQUIRED

The data needed to allow the paymaster to pay for the transaction in native tokens

account_deployment_data
array
REQUIRED

The data needed to deploy the account contract from which this tx will be initiated

nonce_data_availability_mode
string
REQUIRED

The storage domain of the account's nonce (an account has a nonce per DA mode). It can be one of 'L1' or 'L2'

fee_data_availability_mode
string
REQUIRED

The storage domain of the account's balance from which fee will be charged. It can be one of 'L1' or 'L2'

BROADCASTED_DECLARE_TXN_V3
object

The broadcasted declare transaction v3 object which contains the following fields:

type
string
REQUIRED

The type of declare. It can take only one value - 'DECLARE'

sender_address
string
REQUIRED

The address of the account contract sending the declaration transaction

compiled_class_hash
string
REQUIRED

The hash of the Cairo assembly resulting from the Sierra compilation

version
string
REQUIRED

The version of the transaction scheme

signature
string
REQUIRED

The signature associated with the transaction

nonce
string
REQUIRED

The nonce value

contract_class
object
REQUIRED

The class to be declared

sierra_program
array
REQUIRED

The list of Sierra instructions of which the program consists

contract_class_version
string
REQUIRED

The version of the contract class object. Currently, the Starknet OS supports version 0.1.0

entry_points_by_type
object
REQUIRED

The entry points by type object which contains the following fields:

CONSTRUCTOR
array
REQUIRED

The list of Sierra instructions of which the program consists

selector
string
REQUIRED

A unique identifier of the entry point (function) in the program

function_idx
integer
REQUIRED

The index of the function in the program

EXTERNAL
array
REQUIRED

The list of Sierra instructions of which the program consists

selector
string
REQUIRED

A unique identifier of the entry point (function) in the program

function_idx
integer
REQUIRED

The index of the function in the program

L1_HANDLER
array
REQUIRED

The list of Sierra instructions of which the program consists

selector
string
REQUIRED

A unique identifier of the entry point (function) in the program

function_idx
integer
REQUIRED

The index of the function in the program

abi
string

The class ABI, as supplied by the user declaring the class

resource_bounds
object
REQUIRED

The resource bounds for the transaction execution

l1_gas
object
REQUIRED

The max amount and max price per unit of L1 gas used in this tx

max_amount
string
REQUIRED

The max amount of the resource that can be used in the tx

max_price_per_unit
string
REQUIRED

The max price per unit of this resource for this tx

l1_data_gas
object
REQUIRED

The max amount and max price per unit of L1 data gas used in this tx

max_amount
string
REQUIRED

The max amount of the resource that can be used in the tx

max_price_per_unit
string
REQUIRED

The max price per unit of this resource for this tx

l2_gas
object
REQUIRED

The max amount and max price per unit of L2 gas used in this tx

max_amount
string
REQUIRED

The max amount of the resource that can be used in the tx

max_price_per_unit
string
REQUIRED

The max price per unit of this resource for this tx

tip
string
REQUIRED

The tip for the transaction

paymaster_data
array
REQUIRED

The data needed to allow the paymaster to pay for the transaction in native tokens

account_deployment_data
array
REQUIRED

The data needed to deploy the account contract from which this tx will be initiated

nonce_data_availability_mode
string
REQUIRED

The storage domain of the account's nonce (an account has a nonce per DA mode). It can be one of 'L1' or 'L2'

fee_data_availability_mode
string
REQUIRED

The storage domain of the account's balance from which fee will be charged. It can be one of 'L1' or 'L2'

BROADCASTED_DEPLOY_ACCOUNT_TXN_V3
object

The broadcasted deploy account transaction v3 object which contains the following fields:

type
string
REQUIRED

The type of declare. It can take only one value - 'DEPLOY_ACCOUNT'

version
string
REQUIRED

The version of the transaction scheme

signature
string
REQUIRED

The signature associated with the transaction

nonce
string
REQUIRED

The nonce value

contract_address_salt
string
REQUIRED

The salt for the address of the deployed contract

constructor_calldata
array
REQUIRED

The parameters passed to the constructor

class_hash
string
REQUIRED

The hash of the deployed contract's class

resource_bounds
object
REQUIRED

The resource bounds for the transaction execution

l1_gas
object
REQUIRED

The max amount and max price per unit of L1 gas used in this tx

max_amount
string
REQUIRED

The max amount of the resource that can be used in the tx

max_price_per_unit
string
REQUIRED

The max price per unit of this resource for this tx

l1_data_gas
object
REQUIRED

The max amount and max price per unit of L1 data gas used in this tx

max_amount
string
REQUIRED

The max amount of the resource that can be used in the tx

max_price_per_unit
string
REQUIRED

The max price per unit of this resource for this tx

l2_gas
object
REQUIRED

The max amount and max price per unit of L2 gas used in this tx

max_amount
string
REQUIRED

The max amount of the resource that can be used in the tx

max_price_per_unit
string
REQUIRED

The max price per unit of this resource for this tx

tip
string
REQUIRED

The tip for the transaction

paymaster_data
array
REQUIRED

The data needed to allow the paymaster to pay for the transaction in native tokens

nonce_data_availability_mode
string
REQUIRED

The storage domain of the account's nonce (an account has a nonce per DA mode). It can be one of 'L1' or 'L2'

fee_data_availability_mode
string
REQUIRED

The storage domain of the account's balance from which fee will be charged. It can be one of 'L1' or 'L2'

simulation_flags
array
REQUIRED

It describes what parts of the transaction should be skipped. Possible values are - 'SKIP_VALIDATE' or 'SKIP_FEE_CHARGE'

Returns

result
array

A list of the simulation results, one per simulated transaction, each with the following fields

fee_estimation
object

The transaction's consumed resources and fee, which contains the following fields

l1_gas_consumed
string

The L1 gas consumption of the transaction

l1_gas_price
string

The L1 gas price (in fri or wei, depending on the fee token) that was used in the cost estimation

l1_data_gas_consumed
string

The L1 data gas consumption of the transaction

l1_data_gas_price
string

The L1 data gas price (in fri or wei, depending on the fee token) that was used in the cost estimation

l2_gas_consumed
string

The L2 gas consumption of the transaction

l2_gas_price
string

The L2 gas price (in fri or wei, depending on the fee token) that was used in the cost estimation

overall_fee
string

The estimated fee for the transaction (in fri or wei, depending on the fee token), equals to l1_gas_consumedl1_gas_price + l1_data_gas_consumedl1_data_gas_price + l2_gas_consumed*l2_gas_price

unit
string

The units in which the fee is given. It can be one of 'WEI' or 'FRI'

transaction_trace
object

The transaction's trace, which can be one of the following objects

INVOKE_TXN_TRACE
object

The execution trace of an invoke transaction, which contains the following fields

validate_invocation
object

(Optional) The trace of the validate call, omitted when SKIP_VALIDATE is set

call_type
string

The type of call. Possible values include - 'LIBRARY_CALL', 'CALL', 'DELEGATE'

calldata
array

The arguments passed to the function

caller_address
string

The address of the invoking contract. 0 for the root invocation

calls
array

The calls made by this invocation, each with the same fields as this object

class_hash
string

The hash of the class being called

contract_address
string

The address of the contract

entry_point_selector
string

The entry point selector

entry_point_type
string

The type of entry point. Possible values include - 'EXTERNAL', 'L1_HANDLER', 'CONSTRUCTOR'

events
array

The events emitted in this invocation

order
integer

The order of the event within the transaction

keys
array

The keys associated with the event

data
array

The data associated with the event

execution_resources
object

The computational resources consumed by the call

l1_gas
integer

The L1 gas consumed by the call

l2_gas
integer

The L2 gas consumed by the call

is_reverted
boolean

Whether the invocation reverted

messages
array

The messages sent by this invocation to L1

order
integer

The order of the message within the transaction

payload
array

The payload of the message

to_address
string

The target L1 address the message is sent to

result
array

The value returned from the function invocation

execute_invocation
object

The trace of the execute call. If the transaction reverted, this is an object with a single 'revert_reason' field instead

revert_reason
string

The revert reason, returned in place of the invocation fields when the execution reverted

call_type
string

The type of call. Possible values include - 'LIBRARY_CALL', 'CALL', 'DELEGATE'

calldata
array

The arguments passed to the function

caller_address
string

The address of the invoking contract. 0 for the root invocation

calls
array

The calls made by this invocation, each with the same fields as this object

class_hash
string

The hash of the class being called

contract_address
string

The address of the contract

entry_point_selector
string

The entry point selector

entry_point_type
string

The type of entry point. Possible values include - 'EXTERNAL', 'L1_HANDLER', 'CONSTRUCTOR'

events
array

The events emitted in this invocation

order
integer

The order of the event within the transaction

keys
array

The keys associated with the event

data
array

The data associated with the event

execution_resources
object

The computational resources consumed by the call

l1_gas
integer

The L1 gas consumed by the call

l2_gas
integer

The L2 gas consumed by the call

is_reverted
boolean

Whether the invocation reverted

messages
array

The messages sent by this invocation to L1

order
integer

The order of the message within the transaction

payload
array

The payload of the message

to_address
string

The target L1 address the message is sent to

result
array

The value returned from the function invocation

fee_transfer_invocation
object

(Optional) The trace of the fee transfer, omitted when SKIP_FEE_CHARGE is set

call_type
string

The type of call. Possible values include - 'LIBRARY_CALL', 'CALL', 'DELEGATE'

calldata
array

The arguments passed to the function

caller_address
string

The address of the invoking contract. 0 for the root invocation

calls
array

The calls made by this invocation, each with the same fields as this object

class_hash
string

The hash of the class being called

contract_address
string

The address of the contract

entry_point_selector
string

The entry point selector

entry_point_type
string

The type of entry point. Possible values include - 'EXTERNAL', 'L1_HANDLER', 'CONSTRUCTOR'

events
array

The events emitted in this invocation

order
integer

The order of the event within the transaction

keys
array

The keys associated with the event

data
array

The data associated with the event

execution_resources
object

The computational resources consumed by the call

l1_gas
integer

The L1 gas consumed by the call

l2_gas
integer

The L2 gas consumed by the call

is_reverted
boolean

Whether the invocation reverted

messages
array

The messages sent by this invocation to L1

order
integer

The order of the message within the transaction

payload
array

The payload of the message

to_address
string

The target L1 address the message is sent to

result
array

The value returned from the function invocation

execution_resources
object

The resources consumed by the transaction, including from L1 handler and validation

l1_gas
integer

The L1 gas consumed by the transaction

l1_data_gas
integer

The L1 data gas consumed by the transaction

l2_gas
integer

The L2 gas consumed by the transaction

state_diff
object

The state diff produced by the transaction, which contains the following fields

declared_classes
array

The declared class hash and compiled class hash

class_hash
string

The hash of the declared class

compiled_class_hash
string

The Cairo assembly hash corresponding to the declared class

deployed_contracts
array

The contracts deployed as part of the state update

address
string

The address of the contract

class_hash
string

The hash of the contract code

deprecated_declared_classes
array

The hashes of the declared deprecated (Cairo 0) classes

nonces
array

The updated nonce per contract address

contract_address
string

The address of the contract

nonce
string

The nonce for the given address at the end of the block

replaced_classes
array

The list of contracts whose class was replaced

class_hash
string

The new class hash

contract_address
string

The address of the contract whose class was replaced

storage_diffs
array

The storage updates per contract address

address
string

The address of the contract whose storage was updated

storage_entries
array

The changed storage entries, each with a 'key' and a 'value'

type
string

The type of the traced transaction. It can take only one value - 'INVOKE'

DECLARE_TXN_TRACE
object

The execution trace of a declare transaction, which contains the following fields

validate_invocation
object

(Optional) The trace of the validate call, omitted when SKIP_VALIDATE is set

call_type
string

The type of call. Possible values include - 'LIBRARY_CALL', 'CALL', 'DELEGATE'

calldata
array

The arguments passed to the function

caller_address
string

The address of the invoking contract. 0 for the root invocation

calls
array

The calls made by this invocation, each with the same fields as this object

class_hash
string

The hash of the class being called

contract_address
string

The address of the contract

entry_point_selector
string

The entry point selector

entry_point_type
string

The type of entry point. Possible values include - 'EXTERNAL', 'L1_HANDLER', 'CONSTRUCTOR'

events
array

The events emitted in this invocation

order
integer

The order of the event within the transaction

keys
array

The keys associated with the event

data
array

The data associated with the event

execution_resources
object

The computational resources consumed by the call

l1_gas
integer

The L1 gas consumed by the call

l2_gas
integer

The L2 gas consumed by the call

is_reverted
boolean

Whether the invocation reverted

messages
array

The messages sent by this invocation to L1

order
integer

The order of the message within the transaction

payload
array

The payload of the message

to_address
string

The target L1 address the message is sent to

result
array

The value returned from the function invocation

fee_transfer_invocation
object

(Optional) The trace of the fee transfer, omitted when SKIP_FEE_CHARGE is set

call_type
string

The type of call. Possible values include - 'LIBRARY_CALL', 'CALL', 'DELEGATE'

calldata
array

The arguments passed to the function

caller_address
string

The address of the invoking contract. 0 for the root invocation

calls
array

The calls made by this invocation, each with the same fields as this object

class_hash
string

The hash of the class being called

contract_address
string

The address of the contract

entry_point_selector
string

The entry point selector

entry_point_type
string

The type of entry point. Possible values include - 'EXTERNAL', 'L1_HANDLER', 'CONSTRUCTOR'

events
array

The events emitted in this invocation

order
integer

The order of the event within the transaction

keys
array

The keys associated with the event

data
array

The data associated with the event

execution_resources
object

The computational resources consumed by the call

l1_gas
integer

The L1 gas consumed by the call

l2_gas
integer

The L2 gas consumed by the call

is_reverted
boolean

Whether the invocation reverted

messages
array

The messages sent by this invocation to L1

order
integer

The order of the message within the transaction

payload
array

The payload of the message

to_address
string

The target L1 address the message is sent to

result
array

The value returned from the function invocation

execution_resources
object

The resources consumed by the transaction, including from L1 handler and validation

l1_gas
integer

The L1 gas consumed by the transaction

l1_data_gas
integer

The L1 data gas consumed by the transaction

l2_gas
integer

The L2 gas consumed by the transaction

state_diff
object

The state diff produced by the transaction, which contains the following fields

declared_classes
array

The declared class hash and compiled class hash

class_hash
string

The hash of the declared class

compiled_class_hash
string

The Cairo assembly hash corresponding to the declared class

deployed_contracts
array

The contracts deployed as part of the state update

address
string

The address of the contract

class_hash
string

The hash of the contract code

deprecated_declared_classes
array

The hashes of the declared deprecated (Cairo 0) classes

nonces
array

The updated nonce per contract address

contract_address
string

The address of the contract

nonce
string

The nonce for the given address at the end of the block

replaced_classes
array

The list of contracts whose class was replaced

class_hash
string

The new class hash

contract_address
string

The address of the contract whose class was replaced

storage_diffs
array

The storage updates per contract address

address
string

The address of the contract whose storage was updated

storage_entries
array

The changed storage entries, each with a 'key' and a 'value'

type
string

The type of the traced transaction. It can take only one value - 'DECLARE'

DEPLOY_ACCOUNT_TXN_TRACE
object

The execution trace of a deploy account transaction, which contains the following fields

validate_invocation
object

(Optional) The trace of the validate call, omitted when SKIP_VALIDATE is set

call_type
string

The type of call. Possible values include - 'LIBRARY_CALL', 'CALL', 'DELEGATE'

calldata
array

The arguments passed to the function

caller_address
string

The address of the invoking contract. 0 for the root invocation

calls
array

The calls made by this invocation, each with the same fields as this object

class_hash
string

The hash of the class being called

contract_address
string

The address of the contract

entry_point_selector
string

The entry point selector

entry_point_type
string

The type of entry point. Possible values include - 'EXTERNAL', 'L1_HANDLER', 'CONSTRUCTOR'

events
array

The events emitted in this invocation

order
integer

The order of the event within the transaction

keys
array

The keys associated with the event

data
array

The data associated with the event

execution_resources
object

The computational resources consumed by the call

l1_gas
integer

The L1 gas consumed by the call

l2_gas
integer

The L2 gas consumed by the call

is_reverted
boolean

Whether the invocation reverted

messages
array

The messages sent by this invocation to L1

order
integer

The order of the message within the transaction

payload
array

The payload of the message

to_address
string

The target L1 address the message is sent to

result
array

The value returned from the function invocation

constructor_invocation
object

The trace of the constructor call

call_type
string

The type of call. Possible values include - 'LIBRARY_CALL', 'CALL', 'DELEGATE'

calldata
array

The arguments passed to the function

caller_address
string

The address of the invoking contract. 0 for the root invocation

calls
array

The calls made by this invocation, each with the same fields as this object

class_hash
string

The hash of the class being called

contract_address
string

The address of the contract

entry_point_selector
string

The entry point selector

entry_point_type
string

The type of entry point. Possible values include - 'EXTERNAL', 'L1_HANDLER', 'CONSTRUCTOR'

events
array

The events emitted in this invocation

order
integer

The order of the event within the transaction

keys
array

The keys associated with the event

data
array

The data associated with the event

execution_resources
object

The computational resources consumed by the call

l1_gas
integer

The L1 gas consumed by the call

l2_gas
integer

The L2 gas consumed by the call

is_reverted
boolean

Whether the invocation reverted

messages
array

The messages sent by this invocation to L1

order
integer

The order of the message within the transaction

payload
array

The payload of the message

to_address
string

The target L1 address the message is sent to

result
array

The value returned from the function invocation

fee_transfer_invocation
object

(Optional) The trace of the fee transfer, omitted when SKIP_FEE_CHARGE is set

call_type
string

The type of call. Possible values include - 'LIBRARY_CALL', 'CALL', 'DELEGATE'

calldata
array

The arguments passed to the function

caller_address
string

The address of the invoking contract. 0 for the root invocation

calls
array

The calls made by this invocation, each with the same fields as this object

class_hash
string

The hash of the class being called

contract_address
string

The address of the contract

entry_point_selector
string

The entry point selector

entry_point_type
string

The type of entry point. Possible values include - 'EXTERNAL', 'L1_HANDLER', 'CONSTRUCTOR'

events
array

The events emitted in this invocation

order
integer

The order of the event within the transaction

keys
array

The keys associated with the event

data
array

The data associated with the event

execution_resources
object

The computational resources consumed by the call

l1_gas
integer

The L1 gas consumed by the call

l2_gas
integer

The L2 gas consumed by the call

is_reverted
boolean

Whether the invocation reverted

messages
array

The messages sent by this invocation to L1

order
integer

The order of the message within the transaction

payload
array

The payload of the message

to_address
string

The target L1 address the message is sent to

result
array

The value returned from the function invocation

execution_resources
object

The resources consumed by the transaction, including from L1 handler and validation

l1_gas
integer

The L1 gas consumed by the transaction

l1_data_gas
integer

The L1 data gas consumed by the transaction

l2_gas
integer

The L2 gas consumed by the transaction

state_diff
object

The state diff produced by the transaction, which contains the following fields

declared_classes
array

The declared class hash and compiled class hash

class_hash
string

The hash of the declared class

compiled_class_hash
string

The Cairo assembly hash corresponding to the declared class

deployed_contracts
array

The contracts deployed as part of the state update

address
string

The address of the contract

class_hash
string

The hash of the contract code

deprecated_declared_classes
array

The hashes of the declared deprecated (Cairo 0) classes

nonces
array

The updated nonce per contract address

contract_address
string

The address of the contract

nonce
string

The nonce for the given address at the end of the block

replaced_classes
array

The list of contracts whose class was replaced

class_hash
string

The new class hash

contract_address
string

The address of the contract whose class was replaced

storage_diffs
array

The storage updates per contract address

address
string

The address of the contract whose storage was updated

storage_entries
array

The changed storage entries, each with a 'key' and a 'value'

type
string

The type of the traced transaction. It can take only one value - 'DEPLOY_ACCOUNT'

L1_HANDLER_TXN_TRACE
object

The execution trace of an L1 handler transaction, which contains the following fields

function_invocation
object

The trace of the L1 handler call. If the transaction reverted, this is an object with a single 'revert_reason' field instead

call_type
string

The type of call. Possible values include - 'LIBRARY_CALL', 'CALL', 'DELEGATE'

calldata
array

The arguments passed to the function

caller_address
string

The address of the invoking contract. 0 for the root invocation

calls
array

The calls made by this invocation, each with the same fields as this object

class_hash
string

The hash of the class being called

contract_address
string

The address of the contract

entry_point_selector
string

The entry point selector

entry_point_type
string

The type of entry point. Possible values include - 'EXTERNAL', 'L1_HANDLER', 'CONSTRUCTOR'

events
array

The events emitted in this invocation

order
integer

The order of the event within the transaction

keys
array

The keys associated with the event

data
array

The data associated with the event

execution_resources
object

The computational resources consumed by the call

l1_gas
integer

The L1 gas consumed by the call

l2_gas
integer

The L2 gas consumed by the call

is_reverted
boolean

Whether the invocation reverted

messages
array

The messages sent by this invocation to L1

order
integer

The order of the message within the transaction

payload
array

The payload of the message

to_address
string

The target L1 address the message is sent to

result
array

The value returned from the function invocation

execution_resources
object

The resources consumed by the transaction, including from L1 handler and validation

l1_gas
integer

The L1 gas consumed by the transaction

l1_data_gas
integer

The L1 data gas consumed by the transaction

l2_gas
integer

The L2 gas consumed by the transaction

state_diff
object

The state diff produced by the transaction, which contains the following fields

declared_classes
array

The declared class hash and compiled class hash

class_hash
string

The hash of the declared class

compiled_class_hash
string

The Cairo assembly hash corresponding to the declared class

deployed_contracts
array

The contracts deployed as part of the state update

address
string

The address of the contract

class_hash
string

The hash of the contract code

deprecated_declared_classes
array

The hashes of the declared deprecated (Cairo 0) classes

nonces
array

The updated nonce per contract address

contract_address
string

The address of the contract

nonce
string

The nonce for the given address at the end of the block

replaced_classes
array

The list of contracts whose class was replaced

class_hash
string

The new class hash

contract_address
string

The address of the contract whose class was replaced

storage_diffs
array

The storage updates per contract address

address
string

The address of the contract whose storage was updated

storage_entries
array

The changed storage entries, each with a 'key' and a 'value'

type
string

The type of the traced transaction. It can take only one value - 'L1_HANDLER'

Request
Don't have an account yet?
Create your Quicknode endpoint in seconds and start building
Get started for free