August 2, 2014

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.

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 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.

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.

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.

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.

317 Kudos