Principle and design goals

Technology implementation

Consensus mechanism

uorumsbasedonslices.Thefollowingsubsection provides some examples and discussion. Finally, we define the key properties of safety and liveness that a consensus protocol should hope to achieve.

Accounts and transactions

Stella Crypto Account

Accounts

Accounts are the central data structure in Stellar. Accounts are identified by a public key and saved in the ledger. Everything else in the ledger, such as offers or trustlines, are owned by a particular account.
Accounts are created with the Create Account operation.
Account access is controlled by public/private key cryptography. For an account to perform a transaction–e.g., make a payment–the transaction must be signed by the private key that corresponds to that account’s public key. You can also set up more complicated multi-signature schemes for authorizing transactions on an account.

Account fields,Accounts have the following fields:

Account ID
The public key that was first used to create the account. You can replace the key used for signing the account’s transactions with a different public key, but the original account ID will always be used to identify the account.
Balance
The number of lumens held by the account. The balance is denominated in 1/10,000,000th of a lumen, the smallest divisible unit of a lumen.
Sequence number
The current transaction sequence number of the account. This number starts equal to the ledger number at which the account was created.
Number of subentries
Number of other entries the account owns. This number is used to calculate the account’s minimum balance.
Inflation destination
(optional) Account designated to receive inflation. Every account can vote to send inflation to a destination account.
Flags
Currently there are three flags, used by issuers of assets.
Authorization required (0x1): Requires the issuing account to give other accounts permission before they can hold the issuing account’s credit.
Authorization revocable (0x2): Allows the issuing account to revoke its credit held by other accounts.
Authorization immutable (0x4): If this is set then none of the authorization flags can be set and the account can never be deleted.
Home domain
A domain name that can optionally be added to the account. Clients can look up a stellar.toml from this domain. This should be in the format of a fully qualified domain name such as example.com.
The federation protocol can use the home domain to look up more details about a transaction’s memo or address details about an account. For more on federation, see the federation guide.
Thresholds
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.
Signers
Used for multi-sig. This field lists other public keys and their weights, which can be used to authorize transactions for this account.
Liabilities
Starting in protocol version 10, each account also tracks its lumen liabilities. Buying liabilities equal the total amount of lumens offered to buy aggregated over all offers owned by this account, and selling liabilities equal the total amount of lumens offered to sell aggregated over all offers owned by this account. An account must always have balance sufficiently above the minimum reserve to satisfy its lumen selling liabilities, and a balance sufficiently below the maximum to accomodate its lumen buying liabilities.
Transactions
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.
Each transaction has the following attributes:
Source account
This is the account that originates the transaction. The transaction must be signed by this account, and the transaction fee must be paid by this account. The sequence number of this transaction is based off this account.
Fee
Each transaction sets a fee that is paid by the source account. If this fee is below the network minimum the transaction will fail. The more operations in the transaction, the greater the required fee.
Sequence number
Each transaction has a sequence number. Transactions follow a strict ordering rule when it comes to processing of transactions per account. For the transaction to be valid, the sequence number must be 1 greater than the sequence number stored in the source account entry when the transaction is applied. As the transaction is applied, the source account’s stored sequence number is incremented by 1 before applying operations. If the sequence number on the account is 4, then the incoming transaction should have a sequence number of 5. After the transaction is applied, the sequence number on the account is bumped to 5.
Note that if several transactions with the same source account make it into the same transaction set, they are ordered and applied according to sequence number. For example, if 3 transactions are submitted and the account is at sequence number 5, the transactions must have sequence numbers 6, 7, and 8.
List of operations
Transactions contain an arbitrary list of operations inside them. Typically there is just one operation, but it’s possible to have multiple (up to 100). Operations are executed in order as one ACID transaction, meaning that either all operations are applied or none are. If any operation fails, the whole transaction fails. If operations are on accounts other than the source account, then they require signatures of the accounts in question.
List of signatures
Up to 20 signatures can be attached to a transaction. See Multi-sig for more information. A transaction is considered invalid if it includes signatures that aren’t needed to authorize the transaction—superfluous signatures aren’t allowed.
Signatures are required to authorize operations and to authorize changes to the source account (fee and sequence number).
Memo
optional The memo contains optional extra information. It is the responsibility of the client to interpret this value. Memos can be one of the following types:
MEMO_TEXT : A string encoded using either ASCII or UTF-8, up to 28-bytes long.
MEMO_ID : A 64 bit unsigned integer.
MEMO_HASH : A 32 byte hash.
MEMO_RETURN : A 32 byte hash intended to be interpreted as the hash of the transaction the sender is refunding.
Time bounds
optional The UNIX timestamp (in seconds), determined by ledger time, of a lower and upper bound of when this transaction will be valid. If a transaction is submitted too early or too late, it will fail to make it into the transaction set. maxTime equal 0 means that it’s not set.
Transaction sets
Between ledger closings, all the nodes in the network are collecting transactions. When it is time to close the next ledger, the nodes collect these transactions into a transaction set. SCP is run by the network to reach agreement on which transaction set to apply to the last ledger.
Life cycle
Creation: The user creates a transaction, fills out all the fields, gives it the correct sequence number, adds whatever operations it wants, etc. Try it with js-stellar-sdk.
Signing: Once the transaction is filled out, all the needed signatures must be collected and added to the transaction envelope. Commonly it’s just the signature of the account doing the transaction, but more complicated setups can require collecting signatures from multiple parties. See multi-sig.
Submitting: After signing, the transaction should be valid and can now be submitted to the Stellar network. Transactions are typically submitted using horizon, but you can also submit the transaction directly to an instance of stellar-core.
Propagating: Once stellar-core receives a transaction, either given to it by a user or another stellar-core, it does preliminary checks to see if the transaction is valid. Among other checks, it makes sure that the transaction is correctly formed and the source account has enough to cover the transaction fee. Stellar-core doesn’t check things that require inspecting the state of the ledger beyond looking up the source account—e.g., that the destination account to which the transaction is trying to send exists, that the account has enough of this asset to sell, that it’s a valid path. If the preliminary checks pass, then stellar-core propagates the transaction to all the other servers to which it’s connected. In this way, a valid transaction is flooded to the whole Stellar network.
Including in a transaction set: When it’s time to close the ledger, stellar-core takes all the transactions it has heard about since last ledger close and collects them into a transaction set. If it hears about any incoming transactions now, it puts them aside for next ledger close. Stellar-core nominates the transaction set it has collected. SCP resolves the differences between the various transaction sets proposed and decides on the one transaction set that the network will apply.
Application: Once SCP agrees on a particular transaction set, that set is applied to the ledger. At this point, a fee is taken from the source account for every transaction in that set. Operations are attempted in the order they occur in the transaction. If any operation fails, the whole transaction fails, and the effects of previous operations in that transaction are rolled back. After all the transactions in the set are applied, a new ledger is created and the process starts over.

Smart contract system

Stellar Smart Contracts

Stellar can be used to build sophisticated smart contracts. Smart contracts are computer programs that can automatically execute an agreement based on programmed logic.
The concept of integrating technology and legal contracts dates back to the 1950s when scholars built computational methods that could enforce legal rules without involving traditional legal processes. Smart contracts were formally defined by Nick Szabo in 1997:
Smart contracts combine protocols with user interfaces to formalize and secure relationships over computer networks. Objectives and principles for the design of these systems are derived from legal principles, economic theory, and theories of reliable and secure protocols.
In recent years, blockchain technology has enabled a new breed of smart contracts with immutable storage of agreement terms, cryptographic authorization, and integrated transfers of value.
For the Stellar Network, smart contracts are manifested as Stellar Smart Contracts. A Stellar Smart Contract (SSC) is expressed as compositions of transactions that are connected and executed using various constraints. The following are examples of constraints that can be considered and implemented when creating SSCs:
Multisignature - What keys are needed to authorize a certain operation? What parties need to agree on a circumstance in order to execute the steps?
Multisignature is the concept requiring signatures of multiple parties to sign transactions stemming from an account. Through signature weights and thresholds, representation of power in signatures is created.
Batching/Atomicity - What operations must all occur together or fail? What must happen in order to force this to fail or pass?
Batching is the concept of including multiple operations in one transaction. Atomicity is the guarantee that given a series of operations, upon submission to the network if one operation fails, all operation in the transaction fails.
Sequence - In what order should a series of transactions be processed? What are the limitations and dependencies?
The concept of sequence is represented on the Stellar Network through sequence number. Utilizing sequence numbers in transaction manipulation, it can be guaranteed that specific transactions do not succeed if an alternative transaction is submitted.
Time Bounds - When can a transaction be processed?
Time bounds are limitations on the time period over which a transaction is valid. Using time bounds enables time periods to be represented in an SSC.
This overview presents two common design patterns that can be used to create SSCs on the Stellar Network. The transactions can be translated to API requests or can be executed using Stellar Laboratory.

Cryptography

Distributed storage protocol

Cross-chain and exchange technology

Distributed Exchange

In addition to supporting the issuing and movement of assets, the Stellar network also acts as a decentralized distributed exchange of any type of asset that people have added to the network. Its ledger stores both balances held by user accounts and offers that user accounts make to buy or sell assets.

Offers

An account can make offers to buy or sell assets using the Manage Offer operation. In order to make an offer, the account must hold the asset it wants to sell. Similarly, the account must trust the issuer of the asset it’s trying to buy.
When an account makes an offer, the offer is checked against the existing orderbook for that asset pair. If the offer crosses an existing offer, it is filled at the price of the existing offer. Let’s say that you make an offer to buy 10 XLM for 2 BTC. If an offer already exists to sell 10 XLM for 2 BTC, your offer will take that offer–you’ll be 2 BTC poorer but 10 XLM richer.
If the offer doesn’t cross an existing offer, the offer is saved in the orderbook until it is either taken by another offer, taken by a payment, canceled by the account that created the offer, or invalidated because the account making the offer no longer has the asset for sale.
Starting in protocol version 10, it is no longer possible for an offer to be invalidated because the account owning the offer no longer has the asset for sale. Each offer contributes selling liabilities for the selling asset and buying liabilities for the buying asset, which are aggregated in the account (for lumens) or trustline (for other assets) owned by the account creating the offer. Any operation that would cause an account to be unable to satisfy its liabilities, such as sending away too much balance, will fail. This guarantees that any offer in the orderbook can be executed entirely.
Offers in Stellar behave like limit orders in traditional markets.
For offers placed at the same price, the older offer is filled before the newer one.

Orderbook

An orderbook is a record of outstanding orders on the Stellar network. This record sits between any two assets–in this case, let’s say the assets are sheep and wheat. The orderbook records every account wanting to buy sheep for wheat on one side and every account wanting to sell sheep for wheat on the other side.
Some assets will have a very thin or nonexistent orderbook between them. That’s fine: as discussed in greater detail below, paths of orders can facilitate exchange between two thinly traded assets.

Passive offers

Passive offers allow markets to have zero spread. If you want to offer USD from anchor A for USD from anchor B at a 1:1 price, you can create two passive offers so the two offers don’t fill each other.
A passive offer is an offer that does not take a counteroffer of equal price. It will only fill if the prices are not equal. For example, if the best offer to buy BTC for XLM has a price of 100XLM/BTC, and you make a passive offer to sell BTC at 100XLM/BTC, your passive offer does not take that existing offer. If you instead make a passive offer to sell BTC at 99XLM/BTC it would cross the existing offer and fill at 100XLM/BTC.

Cross-asset payments

Suppose you are holding sheep and want to buy something from a store that only accepts wheat. You can create a payment in Stellar that will automatically convert your sheep into wheat. It goes through the sheep/wheat orderbook and converts your sheep at the best available rate.
You can also make more complicated paths of asset conversion. Imagine that the sheep/wheat orderbook has a very large spread or is nonexistent. In this case, you might get a better rate if you first trade your sheep for brick and then sell that brick for wheat. So a potential path would be 2 hops: sheep->brick->wheat. This path would take you through the sheep/brick orderbook and then the brick/wheat orderbook.
These paths of asset conversion can contain up to 6 hops, but the whole payment is atomic–it will either succeed or fail. The payment sender will never be left holding an unwanted asset.
This process of finding the best path of a payment is called pathfinding. Pathfinding involves looking at the current orderbooks and finding which series of conversions gives you the best rate. It is handled outside of Stellar Core by something like Horizon.

Preferred currency

Because cross-asset payments are so simple with Stellar, users can keep their money in whatever asset they prefer to hold. Preferred currency creates a very flexible, open system.
Imagine a world where, anytime you travel, you never have to exchange currency except at the point of sale. A world where you can choose to keep all your assets in, for example, Google stock, cashing out small amounts as you need to pay for things. Cross-asset payments make this world possible.

Special technology

Economic model and incentive

Governance mechanism

Applications