Transactions and States

The Aptos blockchain stores three types of data:

• Transactions: Transactions represent an intended operation being performed by an account on the blockchain (e.g., transferring assets).
• States: The (blockchain ledger) state represents the accumulation of the output of execution of transactions, the values stored within all resources.
• Events: Ancillary data published by the execution of a transaction.

Note

Only transactions can change the ledger state.

Transactions

Aptos transactions contain information such as the sender’s account address, authentication from the sender, the desired operation to be performed on the Aptos blockchain, and the amount of gas the sender is willing to pay to execute the transaction.

Transaction states

A transaction may end in one of the following states:

• Committed on the blockchain and executed. This is considered as a successful transaction.
• Committed on the blockchain and aborted. The abort code indicates why the transaction failed to execute.
• Discarded during transaction submission due to a validation check such as insufficient gas, invalid transaction format, or incorrect key.
• Discarded after transaction submission but before attempted execution. This could be caused by timeouts or insufficient gas due to other transactions affecting the account.

The sender’s account will be charged gas for any committed transactions.

During transaction submission, the submitter is notified of successful submission or a reason for failing validations otherwise.

A transaction that is successfully submitted but ultimately discarded may have no visible state in any accessible Aptos node or within the Aptos network. A user can attempt to resubmit the same transaction to re-validate the transaction. If the submitting node believes that this transaction is still valid, it will return an error stating that an identical transaction has been submitted.

The submitter can try to increase the gas cost by a trivial amount to help make progress and adjust for whatever may have been causing the discarding of the transaction further downstream.

Note

See Aptos Blockchain Deep Dive for a comprehensive description of the Aptos transaction lifecycle.

Contents of a Transaction

A signed transaction on the blockchain contains the following information:

• Signature: The sender’s digital signature authenticates the transaction. Multi-agent and fee-payer transactions include additional signatures.
• Sender address: The sender’s account address.
• Sender public key: The public key that corresponds to the private key used to sign the transaction. The derived authentication key must match the account.
• Payload: The operation to run. Commonly this is an entry function in published Move bytecode. It can also be a transaction script, a multisig payload, or (on supporting networks) an encrypted payload. The payload includes type arguments and inputs. A typical example is transferring APT from the sender to another address.
• Gas unit price: What the sender pays per unit of gas, in Octas. Higher prices raise the chance the next block includes the transaction.
• Maximum gas amount: The maximum gas units the sender will spend. Execution aborts if computation, IO, and converted storage fees exceed this cap.
• Replay protection: Either a sequence number that must match the sender’s on-chain sequence number at execution, or an orderless nonce (AIP-123). Orderless transactions set sequence_number to u64::MAX and expire within 60 seconds.
• Expiration time: A timestamp after which the transaction is no longer valid.
• Chain ID: Distinguishes Mainnet, Testnet, Devnet, and local networks so a signed transaction cannot be replayed on another chain.

Types of transaction payloads

Within a given transaction, the two most common types of payloads include:

• An entry point
• A script (payload)

The official TypeScript, Python, Go, and Rust SDKs support both. Examples in this documentation often call 0x1::aptos_account::transfer.

All operations on the Aptos blockchain should be available via entry point calls. While one could submit multiple transactions calling entry points in series, many such operations may benefit from being called atomically from a single transaction. A script payload transaction can call any entry point or public function defined within any module.

Note

See the tutorial on Your First Transaction for generating valid transactions.

Tip

See Transaction Payloads and BCS for the entry function, script, multisig, versioned, and encrypted payload formats and their BCS layouts.

Note

The Aptos REST API supports generating BCS-encoded transactions from JSON. This is useful for rapid prototyping, but be cautious using it in Mainnet as this places a lot of trust on the fullnode generating the transaction.

Tip

See also: Encrypted Pending Transactions — submit a transaction whose Move payload stays encrypted while pending, on networks that support the feature (AIP-144).

States

The Aptos blockchain’s ledger state, or global state, represents the state of all accounts in the Aptos blockchain. Each validator node in the blockchain must know the latest version of the global state to execute any transaction.

Anyone can submit a transaction to the Aptos blockchain to modify the ledger state. Upon execution of a transaction, a transaction output is generated. A transaction output contains zero or more operations to manipulate the ledger state called write sets emitting a vector of resulting events, the amount of gas consumed, and the executed transaction status.

Proofs

The Aptos blockchain uses proofs to verify the authenticity and correctness of the blockchain data.

Data within the Aptos blockchain is replicated across the network. Each validator and fullnode’s storage is responsible for persisting the agreed upon blocks of transactions and their execution results to the database.

The blockchain is represented as an ever-growing Merkle tree, where each leaf appended to the tree represents a single transaction executed by the blockchain.

All operations executed by the blockchain and all account states can be verified cryptographically. These cryptographic proofs ensure that:

• The validator nodes agree on the state.
• The client does not need to trust the entity from which it is receiving data. For example, if a client fetches the last n transactions from an account, a proof can attest that no transactions were added, omitted or modified in the response. The client may also query for the state of an account, ask whether a specific transaction was processed, and so on.

Versioned database

The ledger state is versioned using an unsigned 64-bit integer corresponding to the number of transactions the system has executed. This versioned database allows the validator nodes to:

• Execute a transaction against the ledger state at the latest version.
• Respond to client queries about ledger history at both current and previous versions.

Transactions change ledger state

The above figure shows how executing transaction T_i changes the state of the Aptos blockchain from S_i-1 to S_i.

In the figure:

• Accounts A and B: Represent Alice’s and Bob’s accounts on the Aptos blockchain.
• S_i-1 : Represents the (i-1)th state of the blockchain. In this state, Alice’s account A has a balance of 110 APT, and Bob’s account B has a balance of 52 APT.
• T_i : This is the i-th transaction executed on the blockchain. In this example, it represents Alice sending 10 APT to Bob.
• Apply(): This is a deterministic function that always returns the same final state for a specific initial state and a specific transaction. If the current state of the blockchain is S_i-1, and transaction T_i is executed on the state S_i-1, then the new state of the blockchain is always S_i. The Aptos blockchain uses the Move language to implement the deterministic execution function Apply().
• S_i : This is the _i_th state of the blockchain. Applying T_i produces S_i = Apply(S_i-1, T_i). Alice’s balance drops by 10 to 100 APT and Bob’s balance rises by 10 to 62 APT.

Size limits

The gas schedule publishes on-chain limits for transaction size and execution output. Current genesis defaults:

Limit Type	Current Per Transaction Limit
transaction	64KB
governance transaction	1MB
a single write op	1MB
all write ops combined	10MB
number of write ops	8192
a single event	1MB
all events combined	10MB