Operations and Transactions

Operations and transactions: how they work

To perform actions with an account on the Stellar network, you compose operations, bundle them into a transaction, and then sign and submit the transaction to the network.

Operations

Operations are individual commands that modify the ledger. Operations are used to send payments, enter orders into the decentralized exchange, change settings on accounts, and authorize accounts to hold assets.

All operations fall into one of three threshold categories: low, medium, or high, and each threshold category has a weight between 0 and 255 (which can be determined using set_options). Thresholds determine what signature weight is required for the operation to be accepted. For example, let’s say an account sets the medium threshold weight to 5. If the account wants to successfully establish a trustline with the changeTrust operation, the weight of the signature(s) must be greater than or equal to 5.

To learn more about signature weight, see the Signature and Multisignature Encyclopedia Entry

View a comprehensive list of Stellar operations and their threshold levels in the List of Operations section

Transactions

The Stellar network encodes transactions using a standardized protocol called External Data Representation (XDR). You can read more about this in our XDR Encyclopedia Entry.

Accounts can only perform one transaction at a time.

Transactions comprise a bundle of between 1-100 operations and are signed and submitted to the ledger by accounts. Transactions always need to be authorized by the source account’s public key to be valid, which involves signing the transaction object with the public key’s associated secret key. A transaction plus its signature(s) is called a transaction envelope.

A transaction may need more than one signature- this happens if it has operations that affect more than one account or if it has a high threshold weight. Check out the Signature and Multisignature Encyclopedia Entry for more information.

Transactions are atomic. Meaning if one operation in a transaction fails, all operations fail, and the entire transaction is not applied to the ledger.

Operations are executed for the source account of the transaction unless an operation override is defined.

Transaction attributes

Transaction and operation validity

Before being successfully submitted to the Stellar network, transactions go through several validity checks. These checks are grouped into three categories:

Preconditions (optional)

Preconditions are checked first.

All preconditions are optional. Time bounds are encouraged, but the other preconditions are used in more specialized circumstances. You can set multiple preconditions as long as the combination is logically sound.

Time bounds

Valid if within set time bounds of the transaction

Time bounds are an optional UNIX timestamp (in seconds), determined by ledger time, of a lower and upper bound of when a transaction will be valid. If a transaction is submitted too early or too late, it will fail to make it into the transaction set.

Setting time bounds on transactions is highly encouraged, and many SDKs enforce them.

If maxTime is 0, upper time bounds are not set. In this case, if a transaction does not make it to the transaction set, it is kept in memory and continuously tries to make it to the next transaction set. Because of this, we advise that all transactions are created with time bounds to invalidate transactions after a certain amount of time, especially if you plan to resubmit your transaction at a later time.

Ledger bounds

Valid if within the set ledger bounds of the transaction

Ledger bounds apply to ledger numbers. With these defined, a transaction will only be valid for ledger numbers that fall within the determined range.

The lower bound is inclusive (less than or equal to) while the upper bound is not (just greater than).

If the upper bound is set to 0, this indicates there is no upper bound.

Minimum sequence number

If a minimum sequence number is set, the transaction will only be valid when its source account’s sequence number (call it S) is large enough. Specifically, it’s valid when S satisfies minSeqNum <= S < tx.seqNum.

If this precondition is omitted, the default behavior applies: the transaction’s sequence number must be exactly one greater than the account’s sequence number.

Note that after a transaction is executed, the account will always set its sequence number to the transaction’s sequence number.

Minimum sequence age

Transaction is valid after a particular duration (expressed in seconds) elapses since the account’s sequence number age.

Minimum sequence age is a precondition relating to time, but unlike time bounds, which express absolute times, minimum sequence age is relative to when the transaction source account’s sequence number was touched.

Minimum sequence ledger gap

Valid if submitted in a ledger meeting or exceeding the source account’s sequence number age

This is similar to the minimum sequence age, except it is expressed as a number of ledgers rather than a duration of time.

Extra signers

Valid if submitted with signatures that fulfill each of the extra signers

A transaction can specify up to two extra signers as a precondition, meaning it must have signatures that correspond to those extra signers, even if those signatures would not otherwise be required to authorize the transaction (i.e., for its sources account or operations).

The additional signers can be of any type besides the pre-authorized transaction signer since to pre-authorize a transaction, you need to know its hash, but be hash must include the extra signers. This Catch-22 relationship means including this type of extra signer will return an error.

Operation validity

When a transaction is submitted to a node, the node checks the validity of each operation in the transaction before attempting to include it in a candidate transaction set. These initial operation validity checks are intended to be fast and simple, with more intensive checks coming after the fees have been consumed. For an operation to pass this validity check, it has to meet the following conditions:

The signatures on the transaction must be valid for the operation

The signatures are from valid signers for the source account of the operation. The combined weight of all signatures for the source account of the operation meets the threshold for the operation.

The operation must be well-formed

Typically this means checking the parameters for the operation to see if they’re in a valid format. For example, only positive values can be set for the amount of a payment operation.

The operation must be valid in the current protocol version of the network

Deprecated operations, such as inflation, are invalid by design.

Transaction validity

Finally, the following transaction checks take place:

Source account

The source account must exist on the ledger.

Fee

The fee must be greater than or equal to the network minimum fee for the number of operations submitted as part of the transaction. This does not guarantee that the transaction will be applied, only that it is valid. In addition, the source account must be able to pay the fee specified. If multiple transactions are submitted but only a subset of them can be paid for, they are checked for validity in order of sequence number.

Fee-bump (if applicable)

See Validity of a Fee-Bump Transaction section

Sequence number

The sequence number must be one greater than the sequence number stored in the source account entry when the transaction is applied unless sequence number preconditions are set. When checking the validity of multiple transactions with the same source account in a candidate transaction set, they must all be valid transactions and their sequence numbers must be offset by one. Then they are ordered and applied according to their sequence number.

List of operations

Each operation must pass all the validity checks for an operation, described in the Operation Validity section above.

List of signatures

Meet signature requirements for each operation in the transaction
Appropriate network passphrase is part of the transaction hash signed by each signer
Combined weight of the signatures for the source account of the transaction meets the low threshold for the source account.

Memo (if applicable)

The memo type must be a valid type, and the memo itself must adhere to the formatting of the memo type.

Transaction lifecycle

1. Creation (Transaction Creator)

A user creates a transaction by setting the source account, sequence number, list of operations and their respective parameters, fee or fee-bump, and optionally a memo and/or preconditions.

2. Signing (Transaction Signers)

Once the transaction is complete, it becomes a transaction envelope containing the transaction itself and a list of signers. All the required signatures must be collected and added to the transaction envelope’s list of signers. Commonly, it’s just the signature of the account doing the transaction, but more complicated setups can require collecting signatures from multiple parties.

3. Submitting (Transaction Submitter)

After signing, the transaction can now be submitted to the Stellar network. If the transaction is invalid, it will be rejected immediately by Stellar Core, the account’s sequence number will not be incremented, and no fee will be consumed from the source account. Multiple transactions for the same account can be submitted, provided each sequence number is off by one (unless minimum sequence number preconditions are set). If they are all valid, Stellar Core will craft a transaction set with each of those transactions applied in sequence number order. Transactions are typically submitted using Horizon, but you can also submit the transaction directly to an instance of Stellar Core.

4. Propagating (Validator)

Once Stellar Core has determined that a transaction is valid, it will propagate the transaction to all other servers to which it’s connected. This way, a valid transaction is flooded to the entire Stellar network.

5. Crafting a candidate transaction set (Validator)

When it’s time to close the ledger, each Stellar Core validator takes all valid transactions it is aware of since the last ledger close and collects them into a candidate transaction set. If it hears about any incoming transactions now, it puts them aside for the next ledger close. If the number of operations in the candidate transaction set is greater than the maximum number of operations per ledger, transactions will be prioritized by their fee for inclusion in the set.

6. Nominating a transaction set (Validator)

Once each validator has crafted a candidate transaction set, the set is nominated to the network.

7. Stellar Consensus Protocol (SCP) determines the final transaction set (Validator Network)

SCP resolves any differences between candidate transaction sets and ultimately determines a single transaction set to apply, the close time of the ledger, and any upgrades to the protocol that need to be applied network-wide at the apply time.

If a transaction doesn’t make it into the transaction set, it is kept around in memory to be added to the next transaction set on a best-effort basis.

If a transaction is kept in memory after a certain number of ledger closes, it will be banned for several additional ledgers. This means no attempt will be made to include it in a candidate transaction set additional ledgers during this time.

8. Transaction apply order is determined (Validator Network)

Once SCP agrees on a particular transaction set, the apply order is computed for the transaction set. This shuffles the set's order to create uncertainty for competing transactions and maintains the order of sequence numbers for multiple transactions per account.

9. Fees are collected (Validator)

Fees are collected for all transactions simultaneously.

10. Application (Validator)

Each transaction is applied in the previously-determined order. For each transaction, the account’s sequence number is consumed (increased by 1), the transaction’s validity is rechecked, and each operation is applied in the order they occur in the transaction. Operations may fail at this stage due to errors that can occur outside of the transaction and operation validity checks. For example, an insufficient balance for a payment is not checked at submission and would fail at this time. The entire transaction will fail if any operation fails, and all previous operations will be rolled back.

11. Protocol Upgrades (Validator)

Finally, upgrades are run if an upgrade took place. This can include arbitrary logic to upgrade the ledger state for protocol upgrades, along with ledger header modifications, including the protocol version, base fee, maximum number of operations per ledger, etc. Once this has been completed, the life cycle begins anew.