Protocol for transaction validation and clearing.

The Ledger "protocol", or set of rules for transaction validation and clearing, describes the expected behavior of WebWallet implementations and external validation clients. Specifically, the "protocol" describes how primitives are used as building blocks for assembling more expressive data structures, and the algorithms to modify or verify the state of the system.



Ledger uses cryptographic hashes, digital signatures and public keys to represent consent about debts in the form of IOUs. They are used to build conventions for verifying the integrity and authenticity of transaction documents, both for clearing transaction requests and auditing transaction records.

  • Hashes Cryptographic hashes are one-way functions that generate an output string with the same number of characters regardless of the input size. The next example shows the SHA-256 digest of the string "webwallet":

  • Signatures For the purpose of generality, digital signatures are always represented as objects in order to make their properties explicit, such as the signature algorithm. However, the next example only shows the value of an ed25519 signature:

  • Public Keys Since signature verification is generalized to support multiple algorithms, WebWallet supports different types of public keys. The next example shows an ed25519 compressed public key:



Besides using regular domain names for transaction clearing providers (e.g., WebWallet uses three types of identifiers for information spaces and the elements within them: addresses, countspaces and transactions.

  • Addresses An address is an identifier for a collection of counters whose balances are controlled by the same cryptographic credentials. A counter is a data structure that contains properties of a numeric value, such as its unit of account and the constraints for modifying it. Addresses are generated by encoding a cryptographic hash derived from one or more public keys.

  • Symbol A symbol (i.e. currency) is a namespace for uniquely identified counters whose numeric values are denominated in the same unit of account. Since any address can issue its own unit of account by signing IOUs denominated in its own identifier, address and countspace identifiers look exactly the same, as shown by the examples above and below.

  • Transactions A transaction is a document that describes operations on counters based on references to previous results and instructions to modify their values. Transactions are identified by their cryptographic hashes, which are also represented as objects in order to make their properties explicit, such as the hash function. The example below shows another SHA-256 hash:



Ledger's accounting model borrows design elements from Bitcoin, including the notion of inputs and outputs. However, it differs greatly in aspects such as modeling inputs as time-bound IOUs, referencing previous outputs from current outputs (not from inputs), allowing negative balances and supporting multiple units of account.

  • Inputs WebWallet transaction inputs are IOUs. An IOU is a cryptographically signed document that acknowledges a debt and authorizes a transaction to clear it. IOU claims basically describe who (sub) owes what (amt, cru) to whom (aud), when (nbf, exp) and where (iss). Other claims are used for reference or security purposes, such as detecting replay attacks (nce).| PROPERTY | DESCRIPTION | EXAMPLE | | :--- | :--- | :--- | | iss (issuance domain) | transaction clearing domain | "" | | sub (subject) | source address, sender | "wS1EU4AtgzD6VDtsrJ..." | | aud (audience) | target address, receiver | "wT99yCRnoYrN3KvTte..." | | amt (amount) | transaction amount | "100.0" | | cru (unit of account) | countspace identifier | "wS1EU4AtgzD6VDtsrJ..." | | nce (nonce) | random value for replay attacks | "r4nd0mV41u3" | | nbf(notBefore) | threshold date for clearing | "2009-01-03T02:10:00.000Z" | | exp (expires) | expiration date | "2016-03-14T09:26:53.589Z" |

  • Outputs WebWallet transaction outputs are counters that aggregate the resulting balance (bal) of each address (adr) in each countspace (cru) after performing the operations described by the inputs. Outputs can reference previous outputs (pre) to be used as initial conditions, and must satisfy constraints such as the balance limits (lim) in order to be valid.| PROPERTY | | VALUE | | :--- | :--- | :--- | | adr (address) | output owner | "wS1EU4AtgzD6VDtsrJ..." | | bal (balance) | output balance | "100.0" | | cru (unit of account) | countspace identifier | "wS1EU4AtgzD6VDtsrJ..." | | lim (limits) | balance constraints | {"low": "0", "upp": Infinity} | | pre(previous) | previous outputs spent | ["hash::index", ...] |

  • Pointers Transaction pointers are compound identifiers used to make reference to a specific output within a transaction, and are made of two parts separated by a double semicolon ("::"): a transaction hash and an index of an outputs array. When they are listed in the "pre" array property of a transaction output, it means that the transaction is spending that previous output.

    ca978112ca1bbdcafac231b39a23dc4da786eff8147c4e72b9807785afee48bb::1   (hash::index)



A Hash Puzzle is a document that describes a problem to be solved before authorizing a transaction. Puzzles impose restrictions such as the list of public keys that are valid for signature verification, and the number of signatures required to solve them. Since addresses are essentially derived from hash puzzles, transactions must provide valid solutions in order to modify their balances.



valid public keys

[alice, bob, charlie]


2 out of 3


Merkle trees are hash based data structures in which pairs of hashes are consecutively hashed until only one is left, called the merkle root. WebWallet uses trees to secure transaction history while enabling efficient verifications of proof of membership, which can determine whether a transaction was included in a given block without knowing all of its transactions.


A graph is a data structure made of nodes and arcs, in which nodes represent entities and arcs the relationships between them. WebWallet uses graphs mainly to represent transactions and their spent outputs, determine an address balance, traverse the transaction history and implement transaction clearing almost entirely with append-only operations.


A Block is a list of transactions cleared in the same timeframe. Although transaction hashes are listed in a specific order, all transactions included in the same block are said to have been cleared "at the same time". Blocks are a way to buffer transactions in order to solve the double-spending problem through mining, but WebWallet uses blocks only for proof of membership.


Stacks are groups of blocks meant to overcome the scalability constraints related to the size of individual blocks. Stacks are made of blocks in the same way that blocks are made of transactions, by creating a Merkle tree out of block hashes. Stack hashes can later be secured using proof-of-work in the same way that blocks are secured in Bitcoin.

Last updated