| title | order |
|---|---|
Accounts |
Accounts are the central data structure in Stellar. They hold balances, sign transactions, and issue assets. All entries that persist on the ledger are owned by a particular account.
In addition to a valid keypair, an account needs a balance of XLM sufficient to meet the network reserve before it exists on the ledger.
Stellar relies on public key cryptography to ensure that transactions are secure: every account requires a valid keypair consisting of a public key and a private key. The public key is, as the name suggests, public. It’s visible on the ledger, anyone can look it up, and it’s what others use to send payments to the account, identify the issuer of an asset, and verify that a given transaction is authorized.
The private key, however, is something an account holder should guard closely. It’s kind of like the combination to a lock — anyone who knows it can access the account, sign transactions, send funds, etc. Do not share your private key with anyone.
You can use any Stellar wallet or SDK to generate a valid keypair.
A keypair alone doesn’t create an account: before an account exists on the ledger, it needs an XLM balance sufficient to meet the minimum network reserve. The minimum reserve, which is determined by validator vote, is intended to disincentivize the creation of tons of unused accounts in order to prevent ledger spam and maintain the efficiency and scalability of the network.
There is a specific operation, Create Account, which you use to make a payment to a valid public key that does not exist on the ledger, thereby creating the account.
Accounts have the following fields:
The public key that was used to create the account. Even if you replace the signer with a different key, the original account ID will always be used to identify the account.
The current transaction sequence number of the account. This number starts equal to the ledger number at which the account was created, and increments upward as the account signs transactions.
Number of entries the account owns. This number is used to calculate the account's minimum balance: each subentry increases an account’s reserve by 0.5XLM. Subentries include:
- Trustlines
- Offers
- Signers
- Data entries
Operations have varying levels of access. This field specifies thresholds for low-, medium-, and high-access levels, as well as the weight of the master key. For more info, see multi-sig.
A fully qualified domain name such as example.com linked to the account. A home domain is required of asset issuers, who use it to publish meta-information for Stellar wallets and potential token holders, and for organizations running validators, who use it to self-identify their nodes.
To add a home domain to an account, use the Set Options operation.
Asset issuers set flags at the account level (via Set Options) if they want to control access to the assets they issue. There are four flags:
- Authorization required (0x1): Requires the issuing account to grant an account permission to hold an asset. With this flag set, an issuer can either grant full authorization to transact with its asset or it can grant limited authorization allowing the holder to maintain orders on the order books, but not to otherwise transact with the asset.
- Authorization revocable (0x2): Allows the issuing account to reduce the authorization level of an account from full to partial, from full to none, or from partial to none.
- Authorization immutable (0x4): Prevents the issuer from setting either of the above flags or deleting the issuing account.
- Clawback enabled (0x8): Enables clawbacks for all assets issued by this account. Note that this only applies along trustlines established after this flag has been set. If you'd like to selectively enable clawback on certain trustlines, you can use SetTrustLineFlags to clear their clawback flag.
Each account has a balance for each token or pool share the account holds, including XLM.
Each account also tracks its liabilities. Buying liabilities equal the total amount of an asset offered to buy aggregated over all offers owned by this account, and selling liabilities equal the total amount of an asset offered to sell aggregated over all offers owned by this account.
An account must always have a balance sufficiently above the minimum reserve to satisfy its lumen selling liabilities, and a balance sufficiently below the maximum to accommodate its lumen buying liabilities.
You can add signers to an account, and this field lists other public keys and their weights that can be used to authorize transactions. For more info, see multisig.