Transactions are the commands that modify the state of the ledger. They include sending payments, creating offers, making account configuration changes, etc.
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 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
object as its sequence number and increments the given account’s sequence number
build() is called on the TransactionBuilder.
Operations can be added to the transaction calling
each operation you wish to add to the transaction.
See Operation for a list of possible operations you can add.
returns the current
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
can add a payment operation to the
After adding the desired operations, call the
method on the
This will return a fully constructed
The transaction object is wrapped in an object called a
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""" 2This example demonstrates how to use TransactionBuilder 3to quickly build a transaction. For a beginner, 4most of the work can be done with TransactionBuilder. 5 6See: https://stellar-sdk.readthedocs.io/en/latest/building_transactions.html#building-transactions 7""" 8from stellar_sdk import Account, Keypair, Network, TransactionBuilder 9 10root_keypair = Keypair.from_secret( 11 "SA6XHAH4GNLRWWWF6TEVEWNS44CBNFAJWHWOPZCVZOUXSQA7BOYN7XHC" 12) 13# Create an Account object from an address and sequence number. 14root_account = Account(account_id=root_keypair.public_key, sequence=1) 15 16transaction = ( 17 TransactionBuilder( 18 source_account=root_account, 19 # If you want to submit to pubnet, you need to change `network_passphrase` to `Network.PUBLIC_NETWORK_PASSPHRASE` 20 network_passphrase=Network.TESTNET_NETWORK_PASSPHRASE, 21 base_fee=100, 22 ) 23 .append_payment_op( # add a payment operation to the transaction 24 destination="GASOCNHNNLYFNMDJYQ3XFMI7BYHIOCFW3GJEOWRPEGK2TDPGTG2E5EDW", 25 asset_code="XLM", 26 amount="125.5", 27 ) 28 .append_set_options_op( # add a set options operation to the transaction 29 home_domain="overcat.me" 30 ) 31 .set_timeout(30) 32 .build() 33) # mark this transaction as valid only for the next 30 seconds
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:
Read the source account’s sequence number before submitting a transaction
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.
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:
stellar_sdk.memo.NoneMemo- empty memo,
stellar_sdk.memo.TextMemo`- 28-byte ascii encoded string memo,
stellar_sdk.memo.IdMemo- 64-bit number memo,
stellar_sdk.memo.HashMemo- 32-byte hash - ex. hash of an item in a content server,
stellar_sdk.memo.ReturnHashMemo- 32-byte hash used for returning payments - contains hash of the transaction being rejected.
1""" 2This example shows how to add memo to a transaction. 3 4See: https://developers.stellar.org/docs/glossary/transactions/#memo 5See: https://stellar-sdk.readthedocs.io/en/latest/building_transactions.html#building-transactions 6""" 7from stellar_sdk import Account, Keypair, Network, TransactionBuilder 8 9root_keypair = Keypair.from_secret( 10 "SA6XHAH4GNLRWWWF6TEVEWNS44CBNFAJWHWOPZCVZOUXSQA7BOYN7XHC" 11) 12# Create an Account object from an address and sequence number. 13root_account = Account(account_id=root_keypair.public_key, sequence=1) 14 15transaction = ( 16 TransactionBuilder( 17 source_account=root_account, 18 network_passphrase=Network.TESTNET_NETWORK_PASSPHRASE, 19 base_fee=100, 20 ) 21 .add_text_memo("Happy birthday!") 22 .append_payment_op( 23 destination="GASOCNHNNLYFNMDJYQ3XFMI7BYHIOCFW3GJEOWRPEGK2TDPGTG2E5EDW", 24 amount="2000", 25 asset_code="XLM", 26 ) 27 .set_timeout(30) 28 .build() 29)
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.