Ethereum and EVM Compatible Blockchains (beta) Actions

action

call_contract

The evm::call_contract action encodes a contract call transaction, signs it with the provided signer data, and broadcasts it to the network.

Inputs

Name
description
Required
optional
Type
string
Description
A description of the transaction.
Name
rpc_api_url
Required
optional
Type
string
Description
The URL of the EVM API used to broadcast the transaction.
Name
signer
Required
required
Type
string
Description
A reference to a signer construct, which will be used to sign the transaction.
Name
contract_address
Required
required
Type
addon(evm::address)
Description
The address of the contract being called.
Name
contract_abi
Required
optional
Type
addon(evm::address)
Description
The contract ABI, optionally used to check input arguments before sending the transaction to the chain.
Name
function_name
Required
required
Type
string
Description
The contract function to invoke.
Name
function_args
Required
optional
Type
array[buffer]
Description
The contract function arguments
Name
amount
Required
optional
Type
integer
Description
The amount, in WEI, to transfer.
Name
type
Required
optional
Type
string
Description
The transaction type. Options are 'Legacy', 'EIP2930', 'EIP1559', 'EIP4844'. The default is 'EIP1559'.
Name
max_fee_per_gas
Required
optional
Type
integer
Description
Sets the max fee per gas of an EIP1559 transaction. This value will be retrieved from the network if omitted.
Name
max_priority_fee_per_gas
Required
optional
Type
integer
Description
Sets the max priority fee per gas of an EIP1559 transaction. This value will be retrieved from the network if omitted.
Name
chain_id
Required
optional
Type
string
Description
The chain id.
Name
nonce
Required
optional
Type
integer
Description
The account nonce of the signer. This value will be retrieved from the network if omitted.
Name
gas_limit
Required
optional
Type
integer
Description
Sets the maximum amount of gas that should be used to execute this transaction. This value will be retrieved from the network if omitted.
Name
gas_price
Required
optional
Type
integer
Description
Sets the gas price for Legacy transactions. This value will be retrieved from the network if omitted.
Name
confirmations
Required
optional
Type
integer
Description
Once the transaction is included on a block, the number of blocks to await before the transaction is considered successful and Runbook execution continues. The default is 1.
Name
pre_condition
Required
optional
Type
map
Description
Pre-conditions are assertions that are evaluated before a command is executed. They can be used to determine if the command should be executed or if a specific behavior should be executed based on the result of the assertion. This is a map type containing the keys:
- behavior: The behavior if the pre-condition assertion does not pass. Possible values are:
  - halt (default): Throws an error and halts execution of the runbook
  - log: Logs a warning and continues execution of the runbook
  - skip: Skips execution of this command and all downstream commands
- assertion: The assertion to check to determine if the pre-condition behavior should be executed. This value should evaluate to a boolean, or the std::assert_eq and other assertions from the standard library can be used.
Name
post_condition
Required
optional
Type
map
Description
Post-conditions are assertions that are evaluated after a command is executed. They can be used to determine if the command should be re-executed or if a specific behavior should be executed based on the result of the assertion. This is a map type containing the keys:
- retries: If the post-condition assertion fails, the number of times to re-execute the command before executing the post-condition behavior. The default is 0.
- backoff_ms: If the post-condition assertion fails, the number of milliseconds to wait before re-executing the command. If not specified, the default is 1000 milliseconds (1 second).
- behavior: The behavior if the post-condition assertion does not pass. Possible values are:
  - halt (default): Throws an error and halts execution of the runbook
  - log: Logs a warning and continues execution of the runbook
  - skip: Skips execution of this command and all downstream commands
  - continue: Continues execution without any action
- assertion: The assertion to check to determine if the command should be re-executed or if the post-condition behavior should be executed. This value should evaluate to a boolean, or the std::assert_eq and other assertions from the standard library can be used.

Outputs

When the call_contract action is successfully executed, the following outputs are attached to the action

Name
tx_hash
Type
string
Description
The hash of the transaction.
Name
logs
Type
object
Description
The logs of the transaction, decoded via any ABI provided by the contract call.
Name
raw_logs
Type
object
Description
The raw logs of the transaction.
Name
result
Type
string
Description
The result of simulating the execution of the transaction directly before its execution.
Name
abi_encoded_result
Type
addon(evm::sim_result)
Description
The simulation result with ABI context for using in other function calls.

Example using call_contract

action "call_some_contract" "evm::call_contract" {
    contract_address = input.contract_address
    function_name = "myFunction"
    function_args = [evm::bytes("0x1234")]
    signer = signer.operator
}

action

eth_call

The evm::eth_call command simulates an Ethereum transaction using the eth_call RPC endpoint.

Inputs

Name
description
Required
optional
Type
string
Description
A description of the call.
Name
rpc_api_url
Required
optional
Type
string
Description
The URL of the EVM API used to send the RPC request.
Name
contract_address
Required
required
Type
addon(evm::address)
Description
The address of the contract being called.
Name
contract_abi
Required
optional
Type
addon(evm::address)
Description
The contract ABI, optionally used to check input arguments before sending the transaction to the chain.
Name
signer
Required
required
Type
string
Description
The address that will be used as the sender of this contract call.
Name
function_name
Required
optional
Type
string
Description
The contract function to call.
Name
function_args
Required
optional
Type
array[buffer]
Description
The contract function arguments.
Name
amount
Required
optional
Type
integer
Description
The amount, in Wei, to send in the transaction.
Name
type
Required
optional
Type
string
Description
The transaction type. Options are 'Legacy', 'EIP2930', 'EIP1559', 'EIP4844'. The default is 'EIP1559'. This value will be retrieved from the network if omitted.
Name
max_fee_per_gas
Required
optional
Type
integer
Description
Sets the max fee per gas of an EIP1559 transaction. This value will be retrieved from the network if omitted.
Name
max_priority_fee_per_gas
Required
optional
Type
integer
Description
Sets the max priority fee per gas of an EIP1559 transaction. This value will be retrieved from the network if omitted.
Name
chain_id
Required
optional
Type
string
Description
The chain id.
Name
nonce
Required
optional
Type
integer
Description
The account nonce of the sender. This value will be retrieved from the network if omitted.
Name
gas_limit
Required
optional
Type
integer
Description
Sets the maximum amount of gas that should be used to execute this transaction. This value will be retrieved from the network if omitted.
Name
gas_price
Required
optional
Type
integer
Description
Sets the gas price for Legacy transactions. This value will be retrieved from the network if omitted.
Name
pre_condition
Required
optional
Type
map
Description
Pre-conditions are assertions that are evaluated before a command is executed. They can be used to determine if the command should be executed or if a specific behavior should be executed based on the result of the assertion. This is a map type containing the keys:
- behavior: The behavior if the pre-condition assertion does not pass. Possible values are:
  - halt (default): Throws an error and halts execution of the runbook
  - log: Logs a warning and continues execution of the runbook
  - skip: Skips execution of this command and all downstream commands
- assertion: The assertion to check to determine if the pre-condition behavior should be executed. This value should evaluate to a boolean, or the std::assert_eq and other assertions from the standard library can be used.
Name
post_condition
Required
optional
Type
map
Description
Post-conditions are assertions that are evaluated after a command is executed. They can be used to determine if the command should be re-executed or if a specific behavior should be executed based on the result of the assertion. This is a map type containing the keys:
- retries: If the post-condition assertion fails, the number of times to re-execute the command before executing the post-condition behavior. The default is 0.
- backoff_ms: If the post-condition assertion fails, the number of milliseconds to wait before re-executing the command. If not specified, the default is 1000 milliseconds (1 second).
- behavior: The behavior if the post-condition assertion does not pass. Possible values are:
  - halt (default): Throws an error and halts execution of the runbook
  - log: Logs a warning and continues execution of the runbook
  - skip: Skips execution of this command and all downstream commands
  - continue: Continues execution without any action
- assertion: The assertion to check to determine if the command should be re-executed or if the post-condition behavior should be executed. This value should evaluate to a boolean, or the std::assert_eq and other assertions from the standard library can be used.

Outputs

When the eth_call action is successfully executed, the following outputs are attached to the action

Name
result
Type
string
Description
The contract call result.

Example using eth_call

action "call_some_contract" "evm::eth_call" {
    contract_address = input.contract_address
    function_name = "myFunction"
    function_args = [evm::bytes("0x1234")]
    signer = signer.operator.address
}

action

check_confirmations

The evm::check_confirmations action polls the network until the provided tx_hash has been confirmed by confirmations blocks.

Inputs

Name
tx_hash
Required
required
Type
buffer
Description
The transaction hash to check.
Name
rpc_api_url
Required
required
Type
string
Description
The URL of the EVM API used to poll for the transaction's inclusion in a block.
Name
chain_id
Required
required
Type
integer
Description
The chain ID of the network to check the transaction on.
Name
confirmations
Required
optional
Type
integer
Description
Once the transaction is included on a block, the number of blocks to await before the transaction is considered successful and Runbook execution continues. The default is 1.
Name
pre_condition
Required
optional
Type
map
Description
Pre-conditions are assertions that are evaluated before a command is executed. They can be used to determine if the command should be executed or if a specific behavior should be executed based on the result of the assertion. This is a map type containing the keys:
- behavior: The behavior if the pre-condition assertion does not pass. Possible values are:
  - halt (default): Throws an error and halts execution of the runbook
  - log: Logs a warning and continues execution of the runbook
  - skip: Skips execution of this command and all downstream commands
- assertion: The assertion to check to determine if the pre-condition behavior should be executed. This value should evaluate to a boolean, or the std::assert_eq and other assertions from the standard library can be used.
Name
post_condition
Required
optional
Type
map
Description
Post-conditions are assertions that are evaluated after a command is executed. They can be used to determine if the command should be re-executed or if a specific behavior should be executed based on the result of the assertion. This is a map type containing the keys:
- retries: If the post-condition assertion fails, the number of times to re-execute the command before executing the post-condition behavior. The default is 0.
- backoff_ms: If the post-condition assertion fails, the number of milliseconds to wait before re-executing the command. If not specified, the default is 1000 milliseconds (1 second).
- behavior: The behavior if the post-condition assertion does not pass. Possible values are:
  - halt (default): Throws an error and halts execution of the runbook
  - log: Logs a warning and continues execution of the runbook
  - skip: Skips execution of this command and all downstream commands
  - continue: Continues execution without any action
- assertion: The assertion to check to determine if the command should be re-executed or if the post-condition behavior should be executed. This value should evaluate to a boolean, or the std::assert_eq and other assertions from the standard library can be used.

Outputs

When the check_confirmations action is successfully executed, the following outputs are attached to the action

Name
contract_address
Type
buffer
Description
The contract address from the transaction receipt.
Name
logs
Type
array[array[string]]
Description
The decoded contract logs from the transaction receipt.

Example using check_confirmations

action "confirm_deployment" "evm::check_confirmations" {
    tx_hash = action.some_deploying_action.tx_hash
}

action

sign_transaction

The evm::sign_transaction command signs an EVM transaction.

Inputs

Name
description
Required
optional
Type
string
Description
A description of the transaction
Name
transaction_payload_bytes
Required
required
Type
string
Description
The unsigned transaction payload bytes.
Name
signer
Required
required
Type
string
Description
A reference to a signer construct, which will be used to sign the transaction payload.
Name
pre_condition
Required
optional
Type
map
Description
Pre-conditions are assertions that are evaluated before a command is executed. They can be used to determine if the command should be executed or if a specific behavior should be executed based on the result of the assertion. This is a map type containing the keys:
- behavior: The behavior if the pre-condition assertion does not pass. Possible values are:
  - halt (default): Throws an error and halts execution of the runbook
  - log: Logs a warning and continues execution of the runbook
  - skip: Skips execution of this command and all downstream commands
- assertion: The assertion to check to determine if the pre-condition behavior should be executed. This value should evaluate to a boolean, or the std::assert_eq and other assertions from the standard library can be used.
Name
post_condition
Required
optional
Type
map
Description
Post-conditions are assertions that are evaluated after a command is executed. They can be used to determine if the command should be re-executed or if a specific behavior should be executed based on the result of the assertion. This is a map type containing the keys:
- retries: If the post-condition assertion fails, the number of times to re-execute the command before executing the post-condition behavior. The default is 0.
- backoff_ms: If the post-condition assertion fails, the number of milliseconds to wait before re-executing the command. If not specified, the default is 1000 milliseconds (1 second).
- behavior: The behavior if the post-condition assertion does not pass. Possible values are:
  - halt (default): Throws an error and halts execution of the runbook
  - log: Logs a warning and continues execution of the runbook
  - skip: Skips execution of this command and all downstream commands
  - continue: Continues execution without any action
- assertion: The assertion to check to determine if the command should be re-executed or if the post-condition behavior should be executed. This value should evaluate to a boolean, or the std::assert_eq and other assertions from the standard library can be used.

Outputs

When the sign_transaction action is successfully executed, the following outputs are attached to the action

Name
tx_hash
Type
string
Description
The hash of the transaction.

Example using sign_transaction

action "signed_tx" "evm::sign_transaction" {
    description = "Deploy a new contract"
    transaction_payload_bytes = "0x1234567890abcdef"
    signer = signer.operator
}

action

send_eth

The evm::send_eth is coming soon.

Inputs

Name
description
Required
optional
Type
string
Description
A description of the transaction.
Name
rpc_api_url
Required
optional
Type
string
Description
The URL of the EVM API used to broadcast the transaction.
Name
signer
Required
required
Type
string
Description
A reference to a signer construct, which will be used to sign the transaction.
Name
recipient_address
Required
required
Type
addon(evm::address)
Description
The EVM address of the recipient.
Name
amount
Required
optional
Type
integer
Description
The amount to send, in WEI (1 ETH = 10^18 WEI).
Name
type
Required
optional
Type
string
Description
The transaction type. Options are 'Legacy', 'EIP2930', 'EIP1559', 'EIP4844'. The default is 'EIP1559'.
Name
max_fee_per_gas
Required
optional
Type
integer
Description
Sets the max fee per gas of an EIP1559 transaction. This value will be retrieved from the network if omitted.
Name
max_priority_fee_per_gas
Required
optional
Type
integer
Description
Sets the max priority fee per gas of an EIP1559 transaction. This value will be retrieved from the network if omitted.
Name
chain_id
Required
optional
Type
string
Description
The chain id.
Name
nonce
Required
optional
Type
integer
Description
The account nonce of the signer. This value will be retrieved from the network if omitted.
Name
gas_limit
Required
optional
Type
integer
Description
Sets the maximum amount of gas that should be used to execute this transaction. This value will be retrieved from the network if omitted.
Name
gas_price
Required
optional
Type
integer
Description
Sets the gas price for Legacy transactions. This value will be retrieved from the network if omitted.
Name
confirmations
Required
optional
Type
integer
Description
Once the transaction is included on a block, the number of blocks to await before the transaction is considered successful and Runbook execution continues. The default is 1.
Name
pre_condition
Required
optional
Type
map
Description
Pre-conditions are assertions that are evaluated before a command is executed. They can be used to determine if the command should be executed or if a specific behavior should be executed based on the result of the assertion. This is a map type containing the keys:
- behavior: The behavior if the pre-condition assertion does not pass. Possible values are:
  - halt (default): Throws an error and halts execution of the runbook
  - log: Logs a warning and continues execution of the runbook
  - skip: Skips execution of this command and all downstream commands
- assertion: The assertion to check to determine if the pre-condition behavior should be executed. This value should evaluate to a boolean, or the std::assert_eq and other assertions from the standard library can be used.
Name
post_condition
Required
optional
Type
map
Description
Post-conditions are assertions that are evaluated after a command is executed. They can be used to determine if the command should be re-executed or if a specific behavior should be executed based on the result of the assertion. This is a map type containing the keys:
- retries: If the post-condition assertion fails, the number of times to re-execute the command before executing the post-condition behavior. The default is 0.
- backoff_ms: If the post-condition assertion fails, the number of milliseconds to wait before re-executing the command. If not specified, the default is 1000 milliseconds (1 second).
- behavior: The behavior if the post-condition assertion does not pass. Possible values are:
  - halt (default): Throws an error and halts execution of the runbook
  - log: Logs a warning and continues execution of the runbook
  - skip: Skips execution of this command and all downstream commands
  - continue: Continues execution without any action
- assertion: The assertion to check to determine if the command should be re-executed or if the post-condition behavior should be executed. This value should evaluate to a boolean, or the std::assert_eq and other assertions from the standard library can be used.

Outputs

When the send_eth action is successfully executed, the following outputs are attached to the action

Name
tx_hash
Type
string
Description
The hash of the transaction.

Example using send_eth

// Coming soon

action

deploy_contract

The evm::deploy_contract is coming soon.

Inputs

Name
description
Required
optional
Type
string
Description
A description of the transaction
Name
rpc_api_url
Required
optional
Type
string
Description
The URL of the EVM API used to broadcast the transaction.
Name
chain_id
Required
optional
Type
string
Description
The chain id.
Name
signer
Required
required
Type
string
Description
A reference to a signer construct, which will be used to sign the transaction.
Name
contract
Required
required
Type
object
Description
The contract to deploy. At a minimum, this should be an object with a key bytecode and the contract bytecode. The abi field can also be provided to add type checking for the constructor arguments. The evm::get_contract_from_foundry_project and evm::get_contract_from_hardhat_project functions can be used to retrieve the contract object. This is an object type containing the keys:
- abi: The contract abi.
- bytecode: The compiled contract bytecode.
- source: The contract source code.
- compiler_version: The solc version used to compile the contract.
- contract_name: The name of the contract being deployed.
- optimizer_enabled: Whether the optimizer is enabled during contract compilation.
- optimizer_runs: The number of runs the optimizer performed.
- evm_version: The EVM version used to compile the contract.
- via_ir: Coming soon
Name
initializer
Required
optional
Type
map
Description
An optional array of initializer functions + arguments to call on the contract that is deployed to the proxy contract. This is a map type containing the keys:
- function_name: The name of the initializer function to call.
- function_args: The arguments to pass to the initializer function.
Name
constructor_args
Required
optional
Type
array[string]
Description
The optional constructor arguments for the deployed contract.
Name
create_opcode
Required
optional
Type
string
Description
The create opcode to use for deployment. Options are 'create' and 'create2'. The default is 'create2'.
Name
create2
Required
optional
Type
map
Description
Options for deploying the contract with the CREATE2 opcode, overwriting txtx default options. This is a map type containing the keys:
- salt: The salt value used to calculate the contract address. This value must be a 32-byte hex string.
- factory_address: To deploy the contract with an alternative factory, provide the address of the factory contract.
- factory_abi: The ABI of the alternative create2 factory contract, optionally used to check input arguments before sending the transaction to the chain.
- factory_function_name: If an alternative create2 factory is used, the name of the function to call.
- factory_function_args: If an alternative create2 factory is used, the arguments to pass to the function.
Name
proxied
Required
optional
Type
bool
Description
Deploys the contract via a proxy contract. The default is false.
Name
proxy
Required
optional
Type
map
Description
Options for deploying the contract via a proxy contract, overwriting txtx default options. This is a map type containing the keys:
- create_opcode: The create opcode to use for deployment. Options are 'create' and 'create2'. The default is 'create2'.
- create2: Options for deploying the contract with the CREATE2 opcode, overwriting txtx default options. This is a map type containing the keys:
  - salt: The salt value used to calculate the contract address. This value must be a 32-byte hex string.
  - factory_address: To deploy the contract with an alternative factory, provide the address of the factory contract.
  - factory_abi: The ABI of the alternative create2 factory contract, optionally used to check input arguments before sending the transaction to the chain.
  - factory_function_name: If an alternative create2 factory is used, the name of the function to call.
  - factory_function_args: If an alternative create2 factory is used, the arguments to pass to the function.
Name
amount
Required
optional
Type
integer
Description
The amount, in WEI, to send with the deployment.
Name
type
Required
optional
Type
string
Description
The transaction type. Options are 'Legacy', 'EIP2930', 'EIP1559', 'EIP4844'. The default is 'EIP1559'.
Name
max_fee_per_gas
Required
optional
Type
integer
Description
Sets the max fee per gas of an EIP1559 transaction. This value will be retrieved from the network if omitted.
Name
max_priority_fee_per_gas
Required
optional
Type
integer
Description
Sets the max priority fee per gas of an EIP1559 transaction. This value will be retrieved from the network if omitted.
Name
nonce
Required
optional
Type
integer
Description
The account nonce of the signer. This value will be retrieved from the network if omitted.
Name
gas_limit
Required
optional
Type
integer
Description
Sets the maximum amount of gas that should be used to execute this transaction. This value will be retrieved from the network if omitted.
Name
gas_price
Required
optional
Type
integer
Description
Sets the gas price for Legacy transactions. This value will be retrieved from the network if omitted.
Name
expected_contract_address
Required
optional
Type
string
Description
The contract address that the deployment should yield. If the deployment does not yield this address, the action will fail. If this field is omitted, the any deployed address will be accepted.
Name
confirmations
Required
optional
Type
integer
Description
Once the transaction is included on a block, the number of blocks to await before the transaction is considered successful and Runbook execution continues. The default is 1.
Name
verify
Required
optional
Type
bool
Description
Indicates whether the contract should be verified after deployment. The default is true. Set this value to false to prevent verification event when verifier args are provided.
Name
verifier
Required
optional
Type
map
Description
Specifies the verifier options for contract verifications. This is a map type containing the keys:
- provider_api_url: The verification provider API url.
- provider_url: The verification provider url, used to display a link to the verified contract.
- provider: The provider to use for contract verification; either 'etherscan', 'blockscout', or 'sourcify'.
- api_key: The verification provider API key.
- throw_on_error: Dictates if the verification process should throw an error if the contract is not verified. The default is false.
Name
pre_condition
Required
optional
Type
map
Description
Pre-conditions are assertions that are evaluated before a command is executed. They can be used to determine if the command should be executed or if a specific behavior should be executed based on the result of the assertion. This is a map type containing the keys:
- behavior: The behavior if the pre-condition assertion does not pass. Possible values are:
  - halt (default): Throws an error and halts execution of the runbook
  - log: Logs a warning and continues execution of the runbook
  - skip: Skips execution of this command and all downstream commands
- assertion: The assertion to check to determine if the pre-condition behavior should be executed. This value should evaluate to a boolean, or the std::assert_eq and other assertions from the standard library can be used.
Name
post_condition
Required
optional
Type
map
Description
Post-conditions are assertions that are evaluated after a command is executed. They can be used to determine if the command should be re-executed or if a specific behavior should be executed based on the result of the assertion. This is a map type containing the keys:
- retries: If the post-condition assertion fails, the number of times to re-execute the command before executing the post-condition behavior. The default is 0.
- backoff_ms: If the post-condition assertion fails, the number of milliseconds to wait before re-executing the command. If not specified, the default is 1000 milliseconds (1 second).
- behavior: The behavior if the post-condition assertion does not pass. Possible values are:
  - halt (default): Throws an error and halts execution of the runbook
  - log: Logs a warning and continues execution of the runbook
  - skip: Skips execution of this command and all downstream commands
  - continue: Continues execution without any action
- assertion: The assertion to check to determine if the command should be re-executed or if the post-condition behavior should be executed. This value should evaluate to a boolean, or the std::assert_eq and other assertions from the standard library can be used.

Outputs

When the deploy_contract action is successfully executed, the following outputs are attached to the action

Name
tx_hash
Type
string
Description
The hash of the transaction.
Name
abi
Type
string
Description
The deployed contract ABI, if it was provided as a contract input.
Name
contract_address
Type
string
Description
The address of the deployed transaction.
Name
logs
Type
object
Description
The logs of the transaction, decoded via any ABI provided by the contract call.
Name
raw_logs
Type
object
Description
The raw logs of the transaction.
Name
verification_results
Type
array[object]
Description
The contract verification results, if the action was configured to verify the contract.

Example using deploy_contract

action "my_contract" "evm::deploy_contract" {
    contract = evm::get_contract_from_foundry_project("MyContract")
    signer = signer.deployer
    create2 {
        salt = "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
    }
}