Building Transactions

Transactions are the commands that modify the state of the ledger. They include sending payments, creating offers, making account configuration changes, etc.

Every transaction has a source account. This is the account that pays the fee and uses up a sequence number for the transaction.

Transactions are made up of one or more operations. Each operation also has a source account, which defaults to the transaction’s source account.

TransactionBuilder

The TransactionBuilder class is used to construct new transactions. TransactionBuilder is given an account that is used as transaction’s source account. The transaction will use the current sequence number of the given Account object as its sequence number and increments the given account’s sequence number when build() is called on the TransactionBuilder.

Operations can be added to the transaction calling append_operation for each operation you wish to add to the transaction. See Operation for a list of possible operations you can add. append_operation returns the current TransactionBuilder object so you can chain multiple calls. But you don’t need to call it directly, we have prepared a lot of easy-to-use functions for you, such as append_payment_op can add a payment operation to the TransactionBuilder.

After adding the desired operations, call the build() method on the TransactionBuilder. This will return a fully constructed TransactionEnvelope. The transaction object is wrapped in an object called a TransactionEnvelope, the returned transaction will contain the sequence number of the source account. This transaction is unsigned. You must sign it before it will be accepted by the Stellar network.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
from stellar_sdk import TransactionBuilder, Network, Keypair, Account

root_keypair = Keypair.from_secret("SA6XHAH4GNLRWWWF6TEVEWNS44CBNFAJWHWOPZCVZOUXSQA7BOYN7XHC")
# Create an Account object from an address and sequence number.
root_account = Account(account_id=root_keypair.public_key, sequence=1)

transaction = TransactionBuilder(
    source_account=root_account,
    # If you want to submit to pubnet, you need to change `network_passphrase` to `Network.PUBLIC_NETWORK_PASSPHRASE`
    network_passphrase=Network.TESTNET_NETWORK_PASSPHRASE,
    base_fee=100) \
    .append_payment_op(  # add a payment operation to the transaction
    destination="GASOCNHNNLYFNMDJYQ3XFMI7BYHIOCFW3GJEOWRPEGK2TDPGTG2E5EDW",
    asset_code="XLM",
    amount="125.5") \
    .append_set_options_op(  # add a set options operation to the transaction
    home_domain="overcat.me") \
    .set_timeout(30) \
    .build()  # mark this transaction as valid only for the next 30 seconds

Sequence Numbers

The sequence number of a transaction has to match the sequence number stored by the source account or else the transaction is invalid. After the transaction is submitted and applied to the ledger, the source account’s sequence number increases by 1.

There are two ways to ensure correct sequence numbers:

  1. Read the source account’s sequence number before submitting a transaction

  2. Manage the sequence number locally

During periods of high transaction throughput, fetching a source account’s sequence number from the network may not return the correct value. So, if you’re submitting many transactions quickly, you will want to keep track of the sequence number locally.

Adding Memos

Transactions can contain a memo field you can use to attach additional information to the transaction. You can do this by passing a Memo object when you construct the TransactionBuilder.

There are 5 types of memos:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
from stellar_sdk import TransactionBuilder, Network, Keypair, Account

root_keypair = Keypair.from_secret("SA6XHAH4GNLRWWWF6TEVEWNS44CBNFAJWHWOPZCVZOUXSQA7BOYN7XHC")
# Create an Account object from an address and sequence number.
root_account = Account(account_id=root_keypair.public_key, sequence=1)

transaction = TransactionBuilder(source_account=root_account, network_passphrase=Network.TESTNET_NETWORK_PASSPHRASE,
                                 base_fee=100).add_text_memo("Happy birthday!").append_payment_op(
    destination="GASOCNHNNLYFNMDJYQ3XFMI7BYHIOCFW3GJEOWRPEGK2TDPGTG2E5EDW", amount="2000",
    asset_code="XLM").set_timeout(30).build()

Transaction and TransactionEnvelope

These two concepts may make the novices unclear, but the official has given a good explanation.

Transactions are commands that modify the ledger state. Among other things, Transactions are used to send payments, enter orders into the distributed exchange, change settings on accounts, and authorize another account to hold your currency. If you think of the ledger as a database, then transactions are SQL commands.

Once a transaction is ready to be signed, the transaction object is wrapped in an object called a Transaction Envelope, which contains the transaction as well as a set of signatures. Most transaction envelopes only contain a single signature along with the transaction, but in multi-signature setups it can contain many signatures. Ultimately, transaction envelopes are passed around the network and are included in transaction sets, as opposed to raw Transaction objects.