Ledger (2.21.0)

Anchors are ledger records that represent a link between user wallets in the ledger. It can be used in the onboarding process of alias directories.

A circle is a ledger record that represents a role or group of signers. This can be useful for grouping signers and easing access rules management since access can be granted to circles instead of specific signer handles or public keys.

When creating a new record, additional custom data can be added in a form of a key:value pair. It is added in a custom object in the API request. For example, when adding a new wallet, request can have an additional description in a form of:

{
  ...
  "custom": {
    "type": "bank",
    "email": "info@bank.com"
  }
  ...
}

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.

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.

A policy is a ledger record that represents a set of access rules that can be applied to records. The main benefits of access policies is to simplify the interactions when creating ledger records and to allow system administrators to control access rules in a centralized way.

If enabled, Ledger logs most incoming and outgoing requests as Request records. Specifically, all API calls related to Ledger Records as well as intent processing and event dispatch calls are logged.

These records are signed by Ledger and can be accessed like any other record.

Source and target represent the origin and destination of the request. They are of the format prefix:handle where prefix can be ledger, signer, bridge or effect. ledger represents the Ledger service and signer or bridge is determined by the JWT sub claim of an incoming request. effect is used when dispatching messages and unknown when it's not possible to determine the source or target.

Record represents the record that the request refers to and is either just the record type like wallet, intent, etc. when querying collections or eg. wallet:handle when referring to a specific wallet.

Action represents the action taken and in case or REST requests uniquely identifies an endpoint in combination with Record.

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.

A schema record identifies a set of constraints used to validate ledger records. When a record has a schema defined, it will be validated before it can be stored in the ledger. This allows for a flexible data model that can be extended over time.

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.

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.

Reports are ledger records that represent individual generated reports.

Report types are determined by the report schema and report generation parameters are contained in the custom field.