Transactions

Overview

Transactions are cryptographically signed instructions from accounts that update the state of the Starknet network. Starknet supports only three types of transactions, with each type going through the same lifecycle to receive its execution and finality statuses. Every transaction that was executed successfully is issued a receipt, which includes its statuses, as well as other information about it.

Additional information

• Transaction fields and hash calculations reference in References
• starknet_api_openrpc.json in the starknet-specs GitHub repository

Transaction types

Starknet supports the following types of transactions:

DECLARE	Introduces a new contract class to Starknet, enabling other contracts to either deploy instances of it or use it via a library call For more information about contract classes and instances, see the Cairo Book.
INVOKE	Invokes a function in an existing contract instance, undergoing validation and execution initiated by the caller account’s __validate__ and __execute__ functions (respectively). The validation stage verifies that the caller account approves the transaction. Because an account’s _validate_ and _execute_ functions can contain any logic, the caller account ultimately determines how to handle the INVOKE transaction.
DEPLOY_ACCOUNT	Deploys a new account contract to Starknet. For more information about deploying a new account, see Accounts.

The L1HandlerTransaction type is also a valid transaction type within Starknet, be it cannot be broadcast through the Starknet API like other transaction types, as it was specifically designed for internal Starknet operations (particularly, handling messages from L1 to L2).

The DEPLOY transaction type existed in Starknet for deploying account before being replaced by DEPLOY_ACCOUNT. DEPLOY only had one version (v0) and is now unsupported by Starknet.

Each transaction type is versioned, with versions increasing when the fields that comprise the transaction change, either with the addition of a new field or the removal of an existing field. The following table summarizes the current, deprecated, and unsupported versions of each transaction type:

Type	Current version	Deprecated versions	Unsupported versions
INVOKE	v3	None	v1, v0
DECLARE	v3	None	v2, v1, v0
DEPLOY_ACCOUNT	v3	None	v1

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

Sending transaction that use deprecated versions is still supported, but support will be removed in an upcoming Starknet release.

Transaction lifecycle

The high-level steps in the Starknet transaction lifecycle are as follows:

1. Transaction submission: A transaction is submitted to a sequencer by a full node.
2. Mempool validation: The sequencer’s mempool performs preliminary validation of the transaction, such as ensuring that its invoker’s balance exceeds the transaction’s max_fee value, assuring the transaction’s calldata length is within the legal limit, and more. If the transaction is invalid, it does not proceed.
3. Sequencer validation: The sequencer performs preliminary validation of the transaction before executing it to ensure that the transaction is still valid. If the transaction is invalid, it does not proceed.
4. Execution: The sequencer batches all transactions that passed the preliminary validation into a block, and applies them to the state sequentially. If a transaction fails during execution, it is included in the block with as reverted.
5. Proof generation and verification: The prover uses the Starknet operating system to computes the proof for the correct execution of all transactions in the block, and transmits it to the L1 verifier, which verifies it. At this point, the L1 state is updated to include the transaction.

Mempools

Up to and including Starknet v0.13.5, transactions were received and ordered by the sequencer in a first-in-first-out (FIFO) fashion. Starting from Starknet v0.14.0, each sequencer will instead maintain a mempool, decouping the transaction order of arrival from the transaction ordering in blocks, for which they are can decide their own policy.

The introduction of mempools will have the following implications on how transactions are processed:

• Nonces: Transactions with a nonce greater than the sender’s current nonce + $x$ will be rejected by the mempool, where:

  • A sender’s current nonce is the sender’s nonce in the latest finalized state at the time the transaction is received
  • X is 200 for INVOKE and DEPLOY_ACCOUNT transactions and $x = 0$ for DECLARE transactions (i.e., no declares with future nonces)

• Fee escalation: A transaction in the mempool can be replaced by a transaction sent from the same account with the same nonce and both tip and max_l2_gas_price increased by at least 10%. If the transaction was submitted with zero tip, it can still be replaced by another transaction with zero tip.

  There are unlikely edge cases in which a transaction is not replaced despite submitting a valid transaction to replace it, such as the existing transaction entering a block while the new one is still processed in the gateway.

• Transaction time-to-live (TTL): Transactions that cannot be included in a block and have exceeded their TTL, currently configured to be 5 mins, are periodically evicted from the mempool

• DECLARE transactions time-to-mature (TTM): Before being inserted into the mempool, DECLARE transactions are sent to a “waiting room” until they exceed their TTM, where TTM < TTL but is still TBD. While in the “waiting room”, DECLARE transactions can’t be replaced, and transactions sent with the same nonce as a transaction in the “waiting room” by the same account are rejected

Transaction statuses

Since Starknet version 0.14.0, the finality statuses are the following:

Type	Status	Description
Finality	NOT_RECEIVED	The transaction is not yet known to any sequencer.
	RECEIVED	A full node has successfully submitted the transaction to a sequencer. As there is currently no P2P protocol between full nodes for updating on each other about received transactions, querying a different node than the one that submitted the transaction for its status will result in a Transaction hash not found error. Therefore, relying on RECEIVED statuses requires initiating sticky HTTP sessions with your full node provider.
	CANDIDATE	The transaction was written to the feeder gateway’s storage by a sequencer. As the transaction hasn’t been executed yet, no execution information is available and only the transaction hash is written to the feeder gateway’s storage.
	PRE_CONFIRMED	The transaction was successfully executed by a sequencer and its receipt was written to the feeder gateway’s storage.
	ACCEPTED_ON_L2	The transaction was included in a block finalized by the consensus protocol.
	ACCEPTED_ON_L1	The Starknet state on L1 moved to a block height which is greater than or equal to the height of the block containing the transaction.
Execution	REVERTED	The transaction failed during execution by a sequencer, and was included in a block as reverted. Since the DEPLOY_ACCOUNT and DECLARE transactions don’t have an execution phase, they cannot be reverted.
	SUCCEEDED	The transaction was successfully executed by a sequencer and is included in a block.

State implications of reverted transactions

When a transaction is marked as REVERTED, the following state implications occur:

Nonce increases	The nonce value for the account of the failed transaction iterates despite the failure.
Fee charge	The sequencer charges a fee for the execution of the transaction up to the point of failure, and a respective Transfer event is emitted.
Partial reversion	All changes that occurred during the validation stage are not reverted. However, all changes that occurred during the execution stage are reverted, including all messages to L1 or any events that were emitted during this stage. Events might still be emitted from the validation stage or the fee charge stage.
Fee calculation	The fee charged for REVERTED transactions is the smaller of the following two values: • The maximum fee that the user is willing to pay, either max_fee (pre-v3 transactions) or $\texttt{max\_amount} \cdot \texttt{max\_price\_per\_unit}$ (v3 transactions). • The total consumed resources. Consumed resources are resources used for the execution of the transaction up to the point of failure, including Cairo steps, builtins, syscalls, L1 messages, events, and state diffs during the validation and execution stages.

Transaction receipt

A transaction receipt can be obtained by using the Starknet API’s starknet_getTransactionReceipt endpoint and contains the following fields:

transaction_hash	The hash of the transaction.
actual_fee	The actual fee paid for the transaction.
finality_status	The finality status of the transaction.
execution_status	The execution status of the transaction.
block_hash	The hash of the block that includes the transaction
block_number	The sequential number of the block that includes the transaction
messages_sent	A list of messages sent to L1.
events	The events emitted.
execution_resource	A summary of the execution resources used by the transaction.
type	The type of the transaction.

The following is an example of a transaction receipt:

{
  "jsonrpc": "2.0",
  "result": {
    "actual_fee": "0x221db5dbf6db",
    "block_hash": "0x301fc0d09c5810600af7bb9610be10596ad6f4e6d28a60d397dd148f0962a88",
    "block_number": 906096,
    "events": [
      {
        "data": [
          "0x181de8b0cd32999a5cc962c5f724bc0f6a322f02957b80e1d5fef49a87588b7",
          "0x0",
          "0x9184e72a000",
          "0x0"
        ],
        "from_address": "0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
        "keys": [
          "0x99cd8bde557814842a3121e8ddfd433a539b8c9f14bf31ebf108d12e6196e9"
        ]
      },
      {
        "data": [
          "0x764da020183e28a48ee38a9474f84e7e5ff13194",
          "0x9184e72a000",
          "0x0",
          "0x181de8b0cd32999a5cc962c5f724bc0f6a322f02957b80e1d5fef49a87588b7"
        ],
        "from_address": "0x73314940630fd6dcda0d772d4c972c4e0a9946bef9dabf4ef84eda8ef542b82",
        "keys": [
          "0x194fc63c49b0f07c8e7a78476844837255213824bd6cb81e0ccfb949921aad1"
        ]
      },
      {
        "data": [
          "0x181de8b0cd32999a5cc962c5f724bc0f6a322f02957b80e1d5fef49a87588b7",
          "0x1176a1bd84444c89232ec27754698e5d2e7e1a7f1539f12027f28b23ec9f3d8",
          "0x221db5dbf6db",
          "0x0"
        ],
        "from_address": "0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7",
        "keys": [
          "0x99cd8bde557814842a3121e8ddfd433a539b8c9f14bf31ebf108d12e6196e9"
        ]
      }
    ],
    "execution_status": "SUCCEEDED",
    "finality_status": "ACCEPTED_ON_L2",
    "messages_sent": [
      {
        "from_address": "0x73314940630fd6dcda0d772d4c972c4e0a9946bef9dabf4ef84eda8ef542b82",
        "payload": [
          "0x0",
          "0x764da020183e28a48ee38a9474f84e7e5ff13194",
          "0x9184e72a000",
          "0x0"
        ],
        "to_address": "0xc3511006c04ef1d78af4c8e0e74ec18a6e64ff9e"
      }
    ],
    "transaction_hash": "0xdeadbeef",
    "type": "INVOKE"
  },
  "id": 1
}