The Trustlines Protocol

The Trustlines Protocol represents a set of rules, processes, and definitions forged into deployable code, which aims to enable the mapping of trust-based relationships on to trustless infrastructure, e.g. a blockchain.

More specifically, the Trustlines Protocol implementation will include the components used to calculate paths and store transactions:

  • The Trustlines Blockchain, which is a mPoS (minimal viable Proof of Stake) sidechain to Ethereum and stores transactions
  • The relay servers, which calculates the optimal paths and relay the transactions sent by applications they are connected to.
  • The client library, a high-level API, which enables applications to interact with the smart contract system on the blockchain via the relay servers
  • The smart contract system which include the currency networks and other smart contacts supporting currency network related transactions (e.g. identity contract(s))

1. Trustlines Blockchain

The Trustlines Blockchain is a single-purpose blockchain for applications that fall in line with the Trustlines mission of promoting financial and economic inclusion of all people through decentralized peer-to-peer network protocols that serve common accounting.

The Trustlines Blockchain went live November 21st. You can read more about the launch in the Launching the Trustlines Blockchain blog post. A blockchain explorer for Trustlines Blockchain can be found at

The Trustlines Blockchain will support the Trustlines Network to provide a flexible mechanism to adapt to changes that need to be done to ensure scalability, cheap transaction costs and censorship resistance. The Trustlines Foundation, therefore, defined the following requirements for the Trustlines Blockchain:

  • Should have the capacity for up to 10M Trustlines Transfers per day
  • Transaction cost should ideally be < €0.01
  • Must be censorship-resistant
  • Must feature the Ethereum Virtual Machine.

The Trustlines Blockchain is based on Parity's Aura consensus algorithm, which was initially designed for Proof of Authority chains and comes with a client implementation (Parity).

Aura functional description

Aura uses a predefined set of known authorities that fill in as validators. These authorities are assigned time slots in a round robin fashion in which they can produce a block which increases the blockchain length. Blocks can be counted as finalized if more than 50% of validators build on top of them. This relies on an honest and online majority assumption as well as an asynchronous network.

mPoS (minimal viable Proof of Stake) implementation

Contrary to Proof of Authority blockchains such as Parity’s Aura consensus implementation, in the planned mPoS system, validators are anonymous. Introducing anonymous validators, however, creates the need to ensure that no entity can easily acquire 51% of the voting power. Popular chains like Ethereum 2.0 can achieve this by making buying 51% of the voting power prohibitively expensive. A new, unknown, blockchain such as the Trustlines Blockchain cannot plan for this.

Our mPoS implementation, therefore, replaces the known authorities with anonymous validators that are defined through a validator auction in which bids of winners will be converted to stakes of TLN on the Ethereum blockchain for nine months. The participants of the auction additionally need to be part of a whitelisted set of candidates. By adding minimal PoS (Proof of Stake) features (staking process of the validator depositing an amount of Ethereum - and slashing process of rendering the deposits permanently inaccessible if certain criteria are fulfilled), we create a consensus algorithm implementation which employs sufficient safety measures for the Trustlines Blockchain. This ensures a reduced risk of Trustlines validators acting hazardously by equivocating (signing 2 different blocks for the same time slot with their private key).

Hard forking as an additional security option

Anonymous validators and PoS features can not ensure security from various attacks or other threats such as, but not limited to, inactive validators, reorganization of blocks if validators collude, withholding blocks temporarily, building empty blocks, censoring certain transactions or filling blocks with unusable information. Therefore, if needed, and as an additional defense mechanism, the Trustlines Blockchain is intended to hard fork to address these security risks and threats.

Hard forks are a simple, yet powerful way to remove misbehaving validators or prevent other attack scenarios without the need to slash deposits of Trustlines Validators. Since we expect that there will be a well-aligned community, we assume that coordination efforts around this will be manageable and hard forking should be able to be carried out fairly easy. Any distribution of agreed on updates resulting in hard forks can occur via an update function and/or by providing a configuration file via the Trustlines Foundation GitHub organization that validators can then add directly into their configuration directory of their clients.

2. The smart contract system

The smart contract system is a collection of smart contracts deployed on the Trustlines Blockchain. Transfers within the Trustlines Network are executed by the smart contracts. All trustlines (i.e. credit lines and balances between users) are notarized on the Trustlines Blockchain. Furthermore, the smart contracts enforce the rules determining how trustlines can be created, used and updated.

Currency networks

The Trustlines currency networks are the foundation of the trustlines functionalities and are implemented on-chain. This contract type is the core smart contract that end users can interact with. The contract records all properties a currency network has (e.g. symbol, name of currency network and fee structure) and account information (e.g. users - blockchain addresses, balances and trustlines). Trustlines are modeled as “accounts” within the currency networks and keep a record of the credit lines two parties have agreed upon as well as their current balance.

Identity contracts

The identity contracts enable the feature that users do not have to pay for their transaction costs but can use the delegate service offered by a person to let that person pay for the transactions. This can be used by e.g. businesses that want to create specific business cases in which they pay for the transactions of their customers or third parties that want to encourage users to use the Trustlines Blockchain without them needing to deal with transaction costs.

To do this, the user will sign a message providing information about the trustlines transfer to be executed. The delegate service will forward a transaction containing this message and signature to an identity contract deployed on the Trustlines Blockchain. By doing so, the delegate service pays for the blockchain specific fees. The identity contract can then verify the signature provided by the user and execute its trustlines transfer depicted in the message. We use identity contracts as specified in EIP 1077 (or at least similar to the former) to implement delegates.

3. Relay servers

The relay servers are an optional bridge between client apps and the Trustlines Blockchain. They offer services that are not feasible to be implemented on-chain or within the client apps. They are a back-end service that implements main features to connect the users to the smart contract system:

  1. Forwarding user signed transactions from a mobile app to the Trustlines Blockchain
  2. Indexing and storing event information
  3. Sending relevant blockchain events (including push notifications) to the mobile app
  4. Discovering a path between a sender and a receiver in the graph of trustlines by using Dijkstra's Algorithm, considering the shortest path in a number of hops.

Users do not need to trust relay servers with their accounts (private keys), as transactions are signed locally on their device and validated by the currency networks on the Trustlines Blockchain.

4. The client library

The clientlib is a Javascript library which makes it easy to build applications on top of the Trustlines Protocol since it encapsulates app client functionalities in a ready to use way. It provides a high-level API to enable applications to interact with the smart contract system on the Trustlines Blockchain via a relay server.

Useful terms and definitions from the Trustlines Protocol

Trustline balance

The trustline balance accounts for what two parties to a trustline agreement owe each other. The party with a negative balance issued the IOU, whereas the party with the positive balance received the IOU.

The amount of a user’s positive balance equals to a negative balance of the other party of an agreement and vice versa. A user cannot issue an IOU of a higher amount to the other party of the agreement than the nominal value of the given credit line given by that party except if the creditor reduces the credit line so that it is lower than the balance.

Credit line

An (informal) agreement between two trusting users (e.g. friends), which allows one user to draw on credit given by the other. A credit line exists in the context of a currency network and therefore implicitly states the currency in which the accounting is done.


A trustline can be defined as a bilateral credit/trust relationship between individual entities or people. It encompasses two credit lines (each party giving one to the other party) as well as a balance which indicates if and how much credit one party has drawn from the other.

Multi-hop transfer (rippling)

A multi-hop payment refers to the mechanism used when multiple users in a currency network cooperate (implicitly as part of the agreement with the network) to facilitate a transfer between users that have no direct trustline agreement. The path encompasses all involved users and their trustlines. The IOU transfer is exclusively between sender and receiver (who exchanged something of value to receive an IOU in one of their trustlines).

When a currency network is pictured as a graph, a chosen path is the list of edges that connect the two parties during a transfer. Each edge can also be referred to as a hop and an "N hops" transfer would indicate that N edges (and N+1 participants) have been involved in a trustlines transfer. If the number of hops N is larger than 1, then N-1 participants helped to facilitate the trustlines transfer.

As the balances along a path are all updated, we also say that the balance updates are rippled through the system.