About Ledger Key Concepts

Signer

A signer is a ledger record that allows linking signing keys with additional metadata. This can be useful for recording information like additional security constraints or even linking keys to external records that are not necessarily managed by or stored in the ledger.

Cryptographic key pairs are used for signing and verification of ledger requests and every signer has to contain a key pair.

Symbol

A symbol record identifies a unit of exchange. Each ledger balance has an amount and a symbol that this amount represents. Symbols can identify currencies, loyalty points, or any other concept that can be counted. Whoever controls a symbol also controls the supply of that symbol in the ledger, i.e., owner of a symbol can issue unlimited amounts of a symbol.

While the owner controls issuance, the circulation of a symbol is controlled by those who hold balances of said symbol. This means that once you send a specific balance to someone, you cannot control it anymore, regardless if you own the symbol or not.

Wallet

Wallets are ledger records that hold balances. Each wallet has a unique handle that identifies it. This handle is used in intents, balance queries, and any other operations involving a wallet.

Handle is defined by the user, so it is useful to use something that is user friendly and easy to remember. Handles can be phone numbers, emails, bank account numbers, usernames, etc. Format and types of handles mostly depends on the use case that is being built on top of a ledger.

Wallets are used to represent anything that can hold a balance. For example, bank accounts, loyalty point accounts, subscriptions, bills, loans, etc. All of those use cases can be modeled by mapping them to wallets.

Intent

Intents describe all ledger balance movements. Each intent can contain one or more claims. A claim is a statement about an action that user or system wants to record in a ledger.

Claims can describe various actions, and number of supported actions is expected to grow over time as new use cases are supported.

All claims that are part of an intent are going to be cleared by the ledger atomically. This means that either all or none of the intent claims are going to be accepted by the ledger.

Intents must also have a unique handle. This property is used to ensure idempotency of operations in case of timeouts and retries. It can also be useful as means of efficiently retrieving past intents. Handle can be generated randomly or it can be a user supplied value, but it has to be unique for each intent.

Intents supports custom data in the same way as all other ledger records. Custom data can be used to record additional metadata about an operation. For example, you can record an invoice id that is being payed, a payment description, type of payment, location, etc.

Effect

Effects describe behaviors that can be triggered because of a change in the ledger data. Effects are the main mechanism for adding new functionality to ledgers that is use case specific.

Each change in ledger data structures broadcasts an event that can be used to notify external systems through effects. Event is identified by a signal - one of the predefined names provided by the Ledger.

Each effect is registered for specific event signal. It also has a filter which allows for more granular control of conditions that are going to trigger event forwarding. Filter can be used to select only certain events based on the event data.

Effect action defines how to forward the events to external systems or ledger plugins. For example calling the external system through webhooks.

Bridge

Bridge is a ledger record that is used to register a remote bridge service with ledger. Bridges are services which connect third party systems, for example banking cores, to ledger. If a bridge is assigned to a wallet, ledger requires confirmation from that service for each balance movement that happens on the wallet in question. These operations are confirmed by remote bridges using a two phase commit protocol.

Bridge record is used to discover and authenticate with those remote services. It contains configuration options like server URLs, authentication methods supported, supported operations, and similar.