Transaction types

Last edit

Contributors

Starknet supports the following types of transactions, as defined in the Starknet API:

DECLARE

Declares new contract classes, enabling new contract instances.

INVOKE

Invokes an existing function in a contract.

DEPLOY_ACCOUNT

Deploys new account contracts in smart wallets.

To see how these transaction types appear in the Starknet API, see starknet_api_openrpc.json.

This topic describes the available fields for these transaction types and how each transaction’s hash is calculated.

Transaction versions

When the fields that comprise a transaction change, either with the addition of a new field or the removal of an existing field, then the transaction version increases.

Deprecated transaction versions are still supported, but support will be removed in a future release of Starknet.

Table 1. Supported versions of Starknet transaction types
Transaction name Current version Deprecated versions Unsupported versions

INVOKE

v3

v1, v0

N/A

DECLARE

v3

v2, v1

v0

DEPLOY_ACCOUNT

v3

v0

N/A

DEPLOY

N/A

N/A

v0

Additionally, see information on the L1 handler transaction type.

Do not submit a transaction that uses an unsupported transaction type, because it cannot be included in a proof, and so cannot become part of a Starknet block.

While the L1HandlerTransaction type is a valid transaction type within Starknet, be aware that it cannot be broadcast through the Starknet API like the other transaction types listed in the table above. This transaction type is specifically designed for internal Starknet operations, particularly for handling messages from L1 to L2. For more details, refer to the L1 handler transaction page.

INVOKE transaction

The INVOKE transaction type invokes a function in an existing contract instance. The contract code of the account that sends the INVOKE transaction determines how to process the transaction.

Because an account’s __validate__ and __execute__ functions can contain any logic, the account ultimately determines how to handle the INVOKE transaction.

Every INVOKE transaction in Starknet undergoes the validation and execution stages, initiated by the __validate__ and __execute__ functions. The validation stage verifies that the account that sent the transaction approves it.

v3 transaction fields

Field name Type Description

account_deployment_data

List<FieldElement>

For future use.

Currently this value is always empty.

For more information, see SNIP 8: Transaction V3 Structure

calldata

List<FieldElement>

The arguments that are passed to the validate and execute functions.

chain_id

FieldElement

The id of the chain to which the transaction is sent.

fee_data_availability_mode

FieldElement

For future use.

Currently this value is always 0.

For more information, see SNIP 8: Transaction V3 Structure

nonce

FieldElement

The transaction nonce.

nonce_data_availability_mode

FieldElement

For future use.

Currently this value is always 0.

For more information, see SNIP 8: Transaction V3 Structure

paymaster_data

List<FieldElement>

For future use.

Currently this value is always empty.

For more information, see SNIP 8: Transaction V3 Structure

resource_bounds

Dict[Resource, ResourceBounds]

Used for enabling the fee market.

A dictionary that maps resource type to resource bounds. The resource is the amount of L1 or L2 gas used to pay for the transaction.

Resource

A felt. Possible values are the felt representation of the strings L1_GAS or L2_GAS.

ResourceBounds

A struct containing the following felts:

  • max_amount: The maximum amount of the resource allowed for usage during the execution.

  • max_price_per_unit: The maximum price the user is willing to pay for the resource.
    L1_GAS and L2_GAS are specified in units of fri, where 1 fri = 10-18 STRK.

sender_address

FieldElement

The address of the account initiating the transaction.

signature

List<`FieldElement>`

Additional information given by the sender, used to validate the transaction.

tip

FieldElement

For future use. Currently this value is always 0.

version

FieldElement

The transaction’s version.
When the fields that comprise a transaction change, either with the addition of a new field or the removal of an existing field, then the transaction version increases.

Transaction version, where n specifies version n transaction. For example:

3

version 3 transaction

v3 hash calculation

The INVOKE v3 transaction hash is calculated as a Poseidon hash over the given transaction elements, specifically:

invoke_v3_tx_hash = h(
    "invoke",
    version,
    sender_address,
    h(tip, l1_gas_bounds, l2_gas_bounds),
    h(paymaster_data),
    chain_id,
    nonce,
    data_availability_modes,
    h(account_deployment_data),
    h(calldata)
)

Where:

  • invoke is a constant prefix string, encoded in ASCII.

  • chain_id is a constant value that specifies the network to which this transaction is sent. See Chain-Id.

  • l1_gas_bounds is constructed as follows:

    \[\underbrace{\text{L1_GAS}}_{\text{60 bits}} | \underbrace{\text{max_amount}}_{\text{64 bits}} | \underbrace{\text{max_price_per_unit}}_{\text{128 bits}}\]
  • l2_gas_bounds is constructed as follows:

    \[\underbrace{\text{L2_GAS}}_{\text{60 bits}} | \underbrace{\text{max_amount}}_{\text{64 bits}} | \underbrace{\text{max_price_per_unit}}_{\text{128 bits}}\]
  • data_availability_modes is a concatenation of fee_data_availability_mode and nonce_data_availability_mode, as follows:

    \[\underbrace{0\cdots0}_{\text{188 bits}} | \underbrace{\text{nonce_data_availability_mode}}_{\text{32 bits}} | \underbrace{\text{fee_data_availability_mode}}_{\text{32 bits}}\]
  • h is the Poseidon hash.

v1 (deprecated) transaction fields

Table 2. INVOKE v1 transaction fields
Name Type Description

sender_address

FieldElement

The address of the sender of this transaction.

calldata

List<FieldElement>

The arguments that are passed to the validate and execute functions.

signature

List<FieldElement>

Additional information given by the sender, used to validate the transaction.

max_fee

FieldElement

The maximum fee that the sender is willing to pay for the transaction

nonce

FieldElement

The transaction nonce.

version

FieldElement

The transaction’s version. The value is 1.
When the fields that comprise a transaction change, either with the addition of a new field or the removal of an existing field, then the transaction version increases.

v1 (deprecated) hash calculation

The INVOKE v1 transaction hash is calculated as a hash over the given transaction elements, specifically:

invoke_v1_tx_hash = h(
    "invoke",
    version,
    sender_address,
    0,
    h(calldata),
    max_fee,
    chain_id,
    nonce
)

Where:

  • invoke is a constant prefix string, encoded in ASCII.

  • The placeholder zero is used to align the hash computation for the different types of transactions.

  • chain_id is a constant value that specifies the network to which this transaction is sent. See Chain-Id.

  • h is the Pedersen hash

v0 (deprecated) hash calculation

The hash of a v0 INVOKE transaction is computed as follows:

invoke_v0_tx_hash = h(
    "invoke",
    version,
    contract_address,
    entry_point_selector,
    h(calldata),
    max_fee,
    chain_id
)

Where:

  • invoke is a constant prefix string, encoded in (ASCII).

  • chain_id is a constant value that specifies the network to which this transaction is sent. See Chain-Id. v2 and v3

  • h is the Pedersen hash

DECLARE transaction

The DECLARE transaction introduces new contract classes into the state of Starknet, enabling other contracts to deploy instances of those classes or use them in a library call. For more information, see contract classes.

v3 transaction fields

Field name Type Description

account_deployment_data

List<FieldElement>

For future use.

Currently this value is always empty.

For more information, see SNIP 8: Transaction V3 Structure

chain_id

FieldElement

The id of the chain to which the transaction is sent.

compiled_class_hash

FieldElement

The hash of the compiled class. For more information, see Class hash.

contract_class

ContractClass

The class definition. For more information, see Class hash.

fee_data_availability_mode

FieldElement

For future use.

Currently this value is always 0.

For more information, see SNIP 8: Transaction V3 Structure

nonce

FieldElement

The transaction nonce.

nonce_data_availability_mode

FieldElement

For future use.

Currently this value is always 0.

For more information, see SNIP 8: Transaction V3 Structure

paymaster_data

List<FieldElement>

For future use.

Currently this value is always empty.

For more information, see SNIP 8: Transaction V3 Structure

resource_bounds

Dict[Resource, ResourceBounds]

Used for enabling the fee market.

A dictionary that maps resource type to resource bounds. The resource is the amount of L1 or L2 gas used to pay for the transaction.

Resource

A felt. Possible values are the felt representation of the strings L1_GAS or L2_GAS.

ResourceBounds

A struct containing the following felts:

  • max_amount: The maximum amount of the resource allowed for usage during the execution.

  • max_price_per_unit: The maximum price the user is willing to pay for the resource.
    L1_GAS and L2_GAS are specified in units of fri, where 1 fri = 10-18 STRK.

sender_address

FieldElement

The address of the account initiating the transaction.

signature

List<`FieldElement>`

Additional information given by the sender, used to validate the transaction.

tip

FieldElement

For future use. Currently this value is always 0.

version

FieldElement

The transaction’s version.
When the fields that comprise a transaction change, either with the addition of a new field or the removal of an existing field, then the transaction version increases.

Transaction version, where n specifies version n transaction. For example:

3

version 3 transaction

v3 hash calculation

The hash of a v3 DECLARE transaction is computed as follows:

declare_v3_tx_hash = h(
    "declare",
    version,
    sender_address,
    h(tip, l1_gas_bounds, l2_gas_bounds),
    h(paymaster_data),
    chain_id,
    nonce,
    data_availability_modes,
    h(account_deployment_data),
    class_hash,
    compiled_class_hash
)

Where:

  • declare is a constant prefix string, encoded in ASCII.

  • chain_id is a constant value that specifies the network to which this transaction is sent. See Chain-Id.

  • l1_gas_bounds is constructed as follows:

    \[\underbrace{\text{L1_GAS}}_{\text{60 bits}} | \underbrace{\text{max_amount}}_{\text{64 bits}} | \underbrace{\text{max_price_per_unit}}_{\text{128 bits}}\]
  • l2_gas_bounds is constructed as follows:

    \[\underbrace{\text{L2_GAS}}_{\text{60 bits}} | \underbrace{\text{max_amount}}_{\text{64 bits}} | \underbrace{\text{max_price_per_unit}}_{\text{128 bits}}\]
  • data_availability_modes is a concatenation of fee_data_availability_mode and nonce_data_availability_mode, as follows:

    \[\underbrace{0\cdots0}_{\text{188 bits}} | \underbrace{\text{nonce_data_availability_mode}}_{\text{32 bits}} | \underbrace{\text{fee_data_availability_mode}}_{\text{32 bits}}\]
  • h is the Poseidon hash.

  • class_hash is the hash of the contract class. See Class Hash for details about how the hash is computed

  • compiled_class_hash is the hash of the compiled class generated by the Sierra→Casm compiler that is used in Starknet

v2 (deprecated) transaction fields

Table 3. DECLARE v2 transaction fields
Name Type Description

chain_id

FieldElement

The id of the chain to which the transaction is sent.

contract_class

ContractClass

The (Cairo 1.0) class.

compiled_class_hash

FieldElement

The hash of the compiled class (see here for more information)

sender_address

FieldElement

The address of the account initiating the transaction.

signature

List<FieldElement>

Additional information given by the sender, used to validate the transaction.

max_fee

FieldElement

The maximum fee that the sender is willing to pay for the transaction.

nonce

FieldElement

The transaction nonce.

version

FieldElement

The transaction’s version. The value is 2.
When the fields that comprise a transaction change, either with the addition of a new field or the removal of an existing field, then the transaction version increases.

v2 (deprecated) hash calculation

The hash of a v2 DECLARE transaction is computed as follows:

declare_v2_tx_hash = h(
    "declare",
    version,
    sender_address,
    0,
    h(class_hash),
    max_fee,
    chain_id,
    nonce,
    compiled_class_hash
)

Where:

  • h is the Poseidon hash function

  • class_hash is the hash of the contract class. See Class Hash for details about how the hash is computed

  • compiled_class_hash is the hash of the compiled class generated by the Sierra→Casm compiler that is used in Starknet

v1 (deprecated) transaction fields

This transaction version was used to declare Cairo 0 classes.

Table 4. DECLARE v1 transaction fields
Name Type Description

contract_class

ContractClass

The class object.

sender_address

FieldElement

The address of the account initiating the transaction.

max_fee

FieldElement

The maximum fee that the sender is willing to pay for the transaction.

signature

List<FieldElement>

Additional information given by the sender, used to validate the transaction.

nonce

FieldElement

The transaction nonce.

version

FieldElement

The transaction’s version. Possible values are 1 or 0.
When the fields that comprise a transaction change, either with the addition of a new field or the removal of an existing field, then the transaction version increases.

v1 (deprecated) hash calculation

The hash of a v1 DECLARE transaction is computed as follows:

declare_v1_tx_hash = h(
    "declare",
    version,
    sender_address,
    0,
    h(class_hash),
    max_fee,
    chain_id,
    nonce
)

Where:

  • declare is a constant prefix string, encoded in ASCII.

  • class_hash is the hash of the contract class. See Class Hash for details about how the hash is computed.

  • The placeholder zero is used to align the hash computation for the different types of transactions.

  • chain_id is a constant value that specifies the network to which this transaction is sent. See Chain-Id.

  • h is the Pedersen hash

v0 (unsupported) hash calculation

This transaction version was used to declare Cairo 0 classes.

The hash of a v0 DECLARE transaction is computed as follows:

declare_v0_tx_hash = h(
    "declare",
    version,
    sender_address,
    0,
    h(),
    max_fee,
    chain_id,
    class_hash
)

Where:

  • declare is a constant prefix string, encoded in ASCII.

  • The placeholder zeros are used to align the hash computation for the different types of transactions.

  • h is the Pedersen hash

  • chain_id is a constant value that specifies the network to which this transaction is sent. See Chain-Id.

  • class_hash is the hash of the contract class. See Class Hash for details about how the hash is computed.

DEPLOY_ACCOUNT transaction

Since StarkNet v0.10.1 the DEPLOY_ACCOUNT transaction replaces the DEPLOY transaction for deploying account contracts.

To use it, you should first pre-fund your new account address so that you can pay the transaction fee. You can then send the DEPLOY_ACCOUNT transaction.

For more information, see Deploying a new account.

v3 transaction fields

Field name Type Description

chain_id

FieldElement

The id of the chain to which the transaction is sent.

class_hash

FieldElement

The hash of the desired account class. For more information, see Class hash.

constructor_calldata

List<FieldElement>

The arguments to the account constructor.

contract_address_salt

FieldElement

A random salt that determines the account address.

fee_data_availability_mode

FieldElement

For future use.

Currently this value is always 0.

For more information, see SNIP 8: Transaction V3 Structure

nonce

FieldElement

The transaction nonce.

nonce_data_availability_mode

FieldElement

For future use.

Currently this value is always 0.

For more information, see SNIP 8: Transaction V3 Structure

paymaster_data

List<FieldElement>

For future use.

Currently this value is always empty.

For more information, see SNIP 8: Transaction V3 Structure

resource_bounds

Dict[Resource, ResourceBounds]

Used for enabling the fee market.

A dictionary that maps resource type to resource bounds. The resource is the amount of L1 or L2 gas used to pay for the transaction.

Resource

A felt. Possible values are the felt representation of the strings L1_GAS or L2_GAS.

ResourceBounds

A struct containing the following felts:

  • max_amount: The maximum amount of the resource allowed for usage during the execution.

  • max_price_per_unit: The maximum price the user is willing to pay for the resource.
    L1_GAS and L2_GAS are specified in units of fri, where 1 fri = 10-18 STRK.

signature

List<`FieldElement>`

Additional information given by the sender, used to validate the transaction.

tip

FieldElement

For future use. Currently this value is always 0.

version

FieldElement

The transaction’s version.
When the fields that comprise a transaction change, either with the addition of a new field or the removal of an existing field, then the transaction version increases.

Transaction version, where n specifies version n transaction. For example:

3

version 3 transaction

v3 hash calculation

The hash of a DEPLOY_ACCOUNT transaction is computed as follows:

deploy_account_v3_tx_hash = h(
    "deploy_account",
    version,
    contract_address,
    h(tip, l1_gas_bounds, l2_gas_bounds),
    h(paymaster_data),
    chain_id,
    nonce,
    data_availability_modes,
    h(constructor_calldata),
    class_hash,
    contract_address_salt
)

Where:

  • deploy_account is a constant prefix string, encoded in ASCII.

  • chain_id is a constant value that specifies the network to which this transaction is sent. See Chain-Id.

  • l1_gas_bounds is constructed as follows:

    \[\underbrace{\text{L1_GAS}}_{\text{60 bits}} | \underbrace{\text{max_amount}}_{\text{64 bits}} | \underbrace{\text{max_price_per_unit}}_{\text{128 bits}}\]
  • l2_gas_bounds is constructed as follows:

    \[\underbrace{\text{L2_GAS}}_{\text{60 bits}} | \underbrace{\text{max_amount}}_{\text{64 bits}} | \underbrace{\text{max_price_per_unit}}_{\text{128 bits}}\]
  • data_availability_modes is a concatenation of fee_data_availability_mode and nonce_data_availability_mode, as follows:

    \[\underbrace{0\cdots0}_{\text{188 bits}} | \underbrace{\text{nonce_data_availability_mode}}_{\text{32 bits}} | \underbrace{\text{fee_data_availability_mode}}_{\text{32 bits}}\]
  • h is the Poseidon hash.

  • class_hash is the hash of the contract class. See Class Hash for details about how the hash is computed.

  • contract_address is the address of the newly deployed account. For information on how this address is calculated, see Contract address.

v1 (deprecated) transaction fields

Table 5. DEPLOY_ACCOUNT transaction fields
Name Type Description

class_hash

FieldElement

The hash of the desired account class.

constructor_calldata

List<FieldElement>

The arguments to the account constructor.

contract_address_salt

FieldElement

A random salt that determines the account address.

signature

List<FieldElement>

Additional information given by the sender, used to validate the transaction.

max_fee

FieldElement

The maximum fee that the sender is willing to pay for the transaction

nonce

FieldElement

The transaction nonce.

version

FieldElement

The transaction’s version. The value is 1.

v1 (deprecated) hash calculation

The hash of a DEPLOY_ACCOUNT transaction is computed as follows:

deploy_account_v1_tx_hash = h(
    "deploy_account",
    version,
    contract_address,
    0,
    h(class_hash, contract_address_salt, constructor_calldata),
    max_fee,
    chain_id,
    nonce
)

Where:

  • deploy_account is a constant prefix string, encoded in ASCII.

  • The placeholder zero is used to align the hash computation for the different types of transactions.

  • h is the Pedersen hash

  • chain_id is a constant value that specifies the network to which this transaction is sent. See Chain-Id.

  • class_hash is the hash of the contract class. See Class Hash for details about how the hash is computed.

DEPLOY (unsupported) transaction hash calculation

If you need to retrieve the hash of an existing DEPLOY transaction, you can use this information to calculate the hash of the transaction.

Before you can calculate the transaction hash, get the deployed contract address. The DEPLOY transaction’s hash is calculated as shown in the following pseudo code:

deploy_tx_hash = h(
    "deploy",
    version,
    contract_address,
    sn_keccak("constructor"),
    h constructor_calldata),
    0,
    chain_id
)

Where:

  • The placeholder zero is used to align the hash computation for the different types of transactions.

  • deploy and constructor are constant strings encoded in ASCII.

  • h is the Pedersen hash and sn_keccak is Starknet Keccak.

  • chain_id is a constant value that specifies the network to which this transaction is sent. See Chain-Id.

  • contract_address is calculated as described here.

Signature

While Starknet does not have a specific signature scheme built into the protocol, the Cairo language, in which smart contracts are written, does have an efficient implementation for ECDSA signature with respect to a STARK-friendly curve.

The generator used in the ECDSA algorithm is \(G=\left(g_x, g_y\right)\) where:

\(g_x=874739451078007766457464989774322083649278607533249481151382481072868806602\) \(g_y=152666792071518830868575557812948353041420400780739481342941381225525861407\)

v3 transaction fee estimation

Estimate the fees of transactions with the starknet_estimateFee API call, which is part of Starknet’s API v0.7.0 and above. For more information, see the Starknet JSON RPC specification. For more information on how to construct the appropriate resource_bounds based on the response of starknet_estimateFee, see How to use the new fee estimates? on the Starknet community forum.

Chain ID

Chain IDs are given as numbers, representing the ASCII encoding of specific constant strings, as illustrated by the following Python snippet:

chain_id = int.from_bytes(value, byteorder="big", signed=False)

The following constants are currently used. They correspond to the chain IDs that Starknet currently supports:

  • SN_MAIN for Starknet’s main network.

  • SN_SEPOLIA for Starknet’s public testnet on Sepolia.

Sepolia testnet replaces Goerli testnet.

Goerli testnet support is now removed.

For more information, including bridge support for Sepolia, see Starknet Goerli Deprecation in the Starknet Dev News newsletter.