The Stellar object model
Stellar attempts to encode a relatively direct model of real-world
finance. Here’s an overview of the main concepts you need to know to
start building using Stellar’s API.
Credits #
Think of the credit system as a graph. Each account is represented as
a node, and the credits are represented as per-currency weights
on the edges. For example, if Joyce owes me 10 GBP, then from my
perspective the balance between us is set to +10 GBP. If she later
gives me 15 GBP in person, then our balance should adjust down to -5
GBP.
From her perspective, everything is the same except the signs are
reverse.
Note that it’s possible to issue credits in arbitrary (even user-defined) currencies. The implications here are pretty interesting, and I’ll likely address them in a subsequent post.
Trust #
Trust lines are effectively permission for an edge’s nodes to move the balance in one direction. By default, trust is set to 0. If I set my trust for Joyce to 100 GBP, I’ve given her permission to unilaterally increase our edge’s GBP weight up to a maximum of 100 GBP — that is, I’m willing for her to claim to owe me up to 100 GBP. If she sets her trust for me to 50 GBP, she’s given me permission to decrease our edge’s GBP weight down to a minimum of -50 GBP — she’s fine with me claiming to owe her up to 50 GBP.
Think of the balance kind like a slider, which I’m only allowed to
adjust down, and which she’s only allowed to adjust up. Translated to
real-world terms, this means I’m allowed to say I owe her more, and
she’s allowed to say she owes me more. Trust acts as a clamp,
preventing either one of us from moving the slider too far (meaning we
can’t claim to owe each other outrageous amounts).
So why do you need the clamp at all? Naively, it would seem that I
should be perfectly fine with Joyce claiming to owe me a million
dollars.
The main issue is that when I trust multiple issuers for the same
currency, I am effectively (modulo some fiddly options) saying that I
consider those issuers’ credits equivalent and I’m fine with
either. If I trust Goliath National Bank and the Iron Bank each for
1000 SEK, and each has issued me a credit for 100 SEK, I could wake up
tomorrow and find that the Iron Bank owes me 200 SEK and Goliath
National Bank owes me nothing. The network reserves the right to move
around balances like that in order to make other people’s transactions
happen.
Stellar (the currency) #
Your stellar balance is distinct from your credit balance, and much
simpler. Think of it as existing in an entirely different database
table: there’s some stellar balance associated with your account,
which is stored as a non-negative integer number of microstellars. (So
stellars are divisible no further than the microstellar.)
So why is the stellar necessary at all? It’s the one part of the system that isn’t just a digital representation of something in the real world. One intuitive way to think about it is that all real-world representations come with baggage — for example, credits require this complicated notion of trust to trade them around. In contrast, it’s possible to define your own, much more convenient rules for something that exists only in the digital world. The stellar is powerful in that it can be traded between parties who don’t trust each other, and thus forms a bridge where there isn’t already a trust path.
Ledger #
Think of the distributed ledger as a database snapshot. If you run
your own stellard, it will grab the latest ledger almost instantly, at
which point you can start submitting new transactions. It will then
automatically download history, which is mostly useful for API calls
that report on previous transactions.
The ledger’s state is updated by transactions, which are saved and
recorded forever.
Exchange #
The distributed exchange is a way of moving around both stellars and credits. It acts without regard to trust.
The exchange itself is effectively a pool of submitted offers, stored within the ledger. The creator of a pending offer can also cancel it.
Each offer has a TakerGets field and a TakerPays field, which indicate what you have and what you want in return, respectively. You can trade some credit you hold (such as my 200 SEK from the Iron Bank) or new credit you’re willing to issue (such as 30 GDB issued by me). Offers can be partially fulfilled.
A taker can accept an offer without regard to their trust settings; this means that after the trade completes they may have more Iron Bank SEK than their trust line would allow. However, the taker explicitly accepted the offer, so they knew what they were getting themselves into. (As an aside, you can thus think about trust as a signed policy allowing the network to take action on your behalf while you’re offline; it doesn’t restrict you from taking actions on your own.)
Note there’s no concept of me “creating” a GDB credit before offering it. Since credits are just weights on the edges, there isn’t even room in the data model for me to hold my own credits.
Spam prevention #
Each ledger-updating action (such as setting trust, sending a payment) on the Stellar network burns a minuscule amount of stellar (10 microstellars). The hosted web client does its best to isolate you from the resulting fractional balance. This amount is chosen to be negligible to legitimate users, but prohibitively expensive to spammers.
Each active account is required to hold a minimum balance (currently 50 STR). This prevents a spammer from spinning up many accounts (which otherwise would bloat the size of the ledger).
There are a number of corner cases and configuration options not
covered here. However, this post should be enough to help you reason about what any given API call will do.
Note that Stellar’s tech is forked from Ripple’s, and this post should largely apply to Ripple as well. Over time, I expect the technologies will diverge — for example, Stellar already has inflation addresses and a few other diverging features.