🧑Accounts
Dive in the Account data structure
Last updated
Dive in the Account data structure
Last updated
Accounts are one of the most important data structures on the Stellar blockchain. They hold asset balances, sign transactions and issue assets. Lets dive into its core concepts.
Every account has a public key and a private key (also known as a secret key). The public key is the account identifier and can be shared freely without any issues. However, the secret key must never be exposed, as it is used to sign transactions. If the secret key is compromised, you lose control of the account.
Here's an example of public and secret keys for a typical account:
They are two 56-character strings made up of uppercase letters and numbers. The public key always starts with a "G" and the secret key with an "S". Together, the public and secret keys make up what is known as a KeyPair.
In this simple example we see how to create an account:
The key code in the example is represented by these lines:
Using Keypair.random(), we generate a valid Keypair. Then, we pass the public key from this Keypair to Operation.createAccount(), along with the initial balance of the account in lumens.
To exist on the network, an account must have a minimum balance of XLM, which is twice the base reserve:
Minimum balance = 2 * Base reserve.
The base reserve is simply a unit used to calculate the minimum balance of an account. Currently, it is set to 0.5 XLM. Therefore, an account must have at least 1 XLM at all times to operate on the network.
However, a single XLM might not be enough, because the minimum balance increases by a base reserve as we add subentries, such as:
Trustlines
Offers
Additional signers
Data entries
Any asset other than XLM requires explicit acceptance for an account to hold a balance of that asset. This acceptance is established through trustlines and involves operations that must be sent in a transaction and recorded in the ledger.
We use the changeTrust method of the Operation class to set the trustline of an account:
In addition to allowing an account to accept payments of an asset, the trustline also sets limits for the amount of that asset that can be held in the account.
Note: if no limit is set, the maximum possible amount is allowed, which is (2^63 - 1)/10^7, or 922,337,203.6854775807. If set to 0, the trustline for that asset is removed.
These are some of the properties you can find in the Account data structure:
Id and Account Id: These are the public key of the account
Sequence number: Since all transactions sent to the network have a source account, the sequence number is used to identify and verify the order of transactions. You cannot send two transactions to the network with the same sequence number. Once a transaction is sent to the network, the sequence number of the source account increments by one, regardless of whether the transaction was accepted or rejected. When working with the SDK, you won't need to manually increment the sequence number because it does this automatically for you.
Thresholds: are defined as access levels for an operation. Each operation falls into a threshold category based on its impact or potential disruption.
For example:
Low Threshold: Operations like bump sequence (which modifies the sequence number) or claiming a claimable balance fall into this category.
Medium Threshold: Operations such as payments, change trust (which involves adding, removing, or modifying trustlines), creating claimable balances, and creating offers are categorized under this threshold.
High Threshold: Operations like account merge and set options (where the weight of the signature is modified or signers are added to an account, among other things) are classified here.
These thresholds are represented as numbers between 0 and 255, are set arbitrarily and representing the minimum sum of signature weights required to perform these operations.
Asset Balances: The asset balances are represented by an array containing each asset's balance for which the account has a trustline. This array includes attributes such as the amount of the asset the account holds, the maximum limit it can possess, and asset information like the code and the issuing account.
It's important to note that it is entirely possible to have a balance of 0 for an asset that is not XLM.
Signers: Before transactions are submitted to the network, they must be signed by all accounts involved in its operations, as well as by the source account of the transaction, which pays the fee for the submission to the network.
For example:
If the transaction includes a payment operation from Account A to Account B, Account A must sign the transaction.
If Account B does not have a trustline for the asset sent by Account A and we include an operation to add that trustline, then Account B must also sign the transaction. Account B does not need to sign if it already has a trustline for the asset being sent, such as lumens.
In the signers section, the accounts that can sign for the account in question and their weights are listed. In our case, the only signer for the account is itself with a weight of one. As we discussed in the thresholds section, all thresholds are set to 0, so this account can sign all operations that affect it.
Sponsoring: The last attributes we'll look at relate to the concept of Sponsored Reserves, which allow one account to cover the base reserve requirement of another account. For example, instead of an account needing to reserve XLM to create a trustline, these XLM can be held in another account (the sponsoring account). In our code example, the account is not sponsoring any other accounts, nor is it being sponsored by any other accounts.
Finally, let's look at how to delete accounts. This process affects not only the account to be deleted but also another account, as the account to be deleted must merge with another account.
Before diving into the code, lets see it graphically for clarity:
Let's assume we have Account A, which we need to delete, and it has a balance of 5 lumens.
To delete it, we need another account, which in this case is Account B, with a balance of 20 lumens.
After successfully executing the deletion operation, Account A no longer exists in the ledger, and Account B now has a balance of 25 lumens.
Now let's see it in code.
Note: If an account has subentries (such as trustlines, signers, etc.), it cannot be merged until all these subentries are removed.
