Write Article
Create Collection
Import from medium
Sign in
POSTED 03 May 2018 02:28

Dharma Protocol in a Nutshell


"Since we released the new & improved Dharma white paper last week, we’ve been blown away by the interest we’ve received from crypto denizens and general enthusiasts alike. Building an informed community of technologists, entrepreneurs, and thought leaders is crucial to our vision. To this end, the purpose of this post is to demystify the inner workings of the protocol in a succinct, plain-language explanation that is accessible to audiences technical and non-technical alike. For a more thorough deep dive on the protocol’s mechanics, study the Dharma white paper here."


This post will serve as a primer on how Dharma protocol works and what roles different constituents in the protocol play. We assume readers are comfortable with the following concepts (useful resources are linked for each one):

This primer glosses over many processes, design rationales, and limitations that are explored at length in the Dharma white paper. Moreover, the motivation for building Dharma protocol and why we think it’s exciting are elaborated on elsewhere. As always, if anything is unclear, feel free to hop in the Dharma community chat and ask a question.

First, let’s start with a basic example.

Hello, World!

Meet Alice and Bob — Alice wants to borrow 1 Ether, and Bob is a friend of Alice’s with more than 1 ether to spare. Alice and Bob come to an agreement that Bob will lend Alice 1 ether today, and, in exchange, Alice will repay Bob 1.1 ether in a week. In this transaction, Alice will be a debtor and Bob will be a creditor. Note that neither Bob nor Alice have to be humans per se —debtors and creditors can be computer programs, smart contracts, decentralized organizations, etc. — from the protocol’s perspective, Alice and Bob are simply Ethereum addresses.

One way Alice and Bob could formalize their agreement is by drafting and signing a legal contract that defines the terms of the transaction — that way, if Alice, Bob, or any third party ever come to a disagreement over how much ether Alice is expected to repay Bob, they can refer back to the signed legal contract in order to resolve the dispute. Such a legal contract would look something like this:
The undersigned agree that, in exchange for 1 ether paid to Alice by Bob today, Alice will repay Bob 1.1 ether 1 week from today.
Alice ______________
Bob _______________
Legal contracts, however, are clunky — if Bob wants to sell his rights to receive 1.1 ether from Alice to Charlie, he would have to either amend the original contract with Alice, or sign a new agreement with Charlie. Alice and Bob decide instead to enter into a debt agreement using Dharma protocol.

First, Alice and Bob have to somehow consensually record their agreement to a certain set of repayment terms. They do this with the help of a special type of smart contract we call a terms contract. A terms contract is very similar to a legal contract in that it serves as a form of social proof that a debtor and creditor have entered into a repayment agreement with one another. What makes a terms contract different from a legal contract is that:

  1. It is immutably stored on a blockchain.
  2. A creditor can easily transfer his rights to receive repayments to another party.
  3. It is easy for a machine to understand what repayment terms are defined by the terms contract.
In order for the last point to be feasible, terms contracts must adhere to the terms contract interface — a smart contract “template” that enumerates which methods must be implemented by a terms contract. An abridged version of the terms contract interface is as follows:
interface TermsContract {
  function registerRepayment(...) {};
  function getExpectedRepaymentValue(...) {};
  function getValueRepaid(...) {};
Let’s construct a terms contract for Alice and Bob’s agreement using pseudo code. Remember it must codify that, in exchange for 1 ether today, Alice owes Bob 1.1 ether in 1 week. For reasons we elaborate on later, we can actually simplify the terms to represent only Alice’s repayment obligation to Bob as follows:

contract AliceRepaymentAgreement implements TermsContractInterface {
  int totalRepaid = 0;
  Date agreementStartDate = January 3, 2009;
  function registerRepayment(int repaymentAmount) onlyDebtKernel {
    totalRepaid = totalRepaid + repaymentAmount;
  function getExpectedRepaymentValue() {
    if (currentTime >= agreementStartDate + 1 week) {
      return 1.1 ether;
    } else {
      return 0 ether;

  function getValueRepaid() {
    return totalRepaid;
We now have a smart contract that programmatically defines the terms of repayment Alice is expected to adhere to, and that can be queried at any given time in order to determine whether Alice has defaulted on her repayments (i.e. getValueRepaid() < getExpectedRepaymentValue() ). Alice now deploys this terms contract to the Ethereum blockchain, and the terms contract now has an Ethereum address we’ll call. 

Note: Debtors need not deploy a new smart contract for each debt agreement, as this would be expensive. The mechanism by which terms contracts can be re-used and generally repurposed is described in the white paper.

Alice now proceeds to construct a debt order using the deployed terms contract’s address. Debt orders are the fundamental primitive of Dharma protocol — they are signed data messages that communicate a debtor’s desire to receive a loan under certain repayment conditions. We will not cover the specific schemas and processes associated with generating and signing debt orders in this post — for our example’s purposes, imagine Alice constructs a string of text that says:
I, holder of public key Y, in exchange for 1 ether paid upfront, agree to repay the debt under the conditions defined in terms contract X.
Alice can now take this string, cryptographically sign it using the private key associated with her public key Y , and send the signed message to Bob via any channel she desires — an email, a Facebook message, carrier pigeon, etc. Note that nothing in the message specifies Bob as the creditor in the transaction. This is deliberate — anyone with access to the signed debt order and a willingness to pay the desired principle can “fill” the debt order and become the creditor in the transaction. This will become important later.

Bob now takes the signed debt order and submits it to the debt kernel smart contract. The debt kernel is a smart contract that acts as a central registry and hub for all administrative logic in the protocol. When Bob submits Alice’s signed debt order to the debt kernel, the following happens:
  1. The repayment terms defined by the terms contract X are immutably recorded in the debt kernel’s registry as having been committed to by the holder of public key Y (i.e. Alice).
  2. Alice is transferred the desired principle amount from Bob’s account, and Bob is issued a unique debt token that is associated with the committed debt agreement and terms contract X.
Alice has now been credited with 1 ether, while Bob has been debited 1 ether and credited with 1 debt token that is unique to Alice’s repayment agreement. Bob’s debt token is a means of establishing who Alice is expected to repay in the debt agreement — whichever address controls the debt token at any given time is the address that will receive Alice’s repayments.

A week passes and Alice wants to repay her debt to Bob. The following happens:
  1. Alice sends her repayment to the debt kernel smart contract
  2. The debt kernel registers Alice’s repayment with the terms contract associated with the debt she is repaying
  3. The debt kernel forwards Alice’s repayment to whichever address currently controls the associated debt token, which, in this case, is Bob’s address
Et Voilà — Alice and Bob were able to issue and administer a tokenized debt agreement without having to rely on any brokers or intermediaries.

This is great, but leaves a lot to be desired — if Alice and Bob are friends or family then Alice might have a social incentive to repay her debt, but the vast majority of the world’s debt agreements are made between strangers. The above scheme lacks a means of incentivizing Alice to repay Bob’s loan, or, for that matter, a mechanism for helping Alice find potential creditors like Bob.

We introduce two classes of utility players to fill these gaps: underwriters and relayers.


Underwriters are trusted entities that, in any given debt issuance, do the following in exchange for fees paid by both the debtor and creditor:
  1. Evaluate the likelihood D that any debtor will repay a creditor according to terms defined in the terms contract.
  2. Immutably attest to the predicted likelihood D on the debt kernel’s on-chain registry.
  3. Do everything in their power to make sure that, with a likelihood of D, the debt is repaid in full.
In the context of Alice and Bob’s debt agreement, we can introduce an underwriter Charlie into the equation, who, for this example’s purposes, we will imagine as a publicly known online lender (e.g. LendingClub, SoFi, etc.). Alice would begin the process by going to Charlie’s website and requesting that he attest to a debt order she has constructed. If Charlie agrees, we can modify the previously constructed debt order to include Charlie’s attestation — something to the effect of:
I, holder of public key Y, in exchange for 1 ether paid upfront, agree to repay the debt under the conditions defined in terms contract X.
And I, holder of public key Z, in exchange for 0.001 ether paid by both the creditor and debtor of this transaction, underwrite this debt agreement as having a 90% likelihood of being repaid.
The new debt order would be signed by both Alice and Charlie, and, when Bob submits the order to the debt kernel, Charlie’s prediction would be immutably recorded. Alice and Bob would be debited 0.001 ether each in addition to the normal debt issuance transaction’s proceedings, and Charlie would be credited 0.002 ether.

Crucial to the underwriter scheme is the notion that creditors and debtors alike can empirically evaluate an underwriter’s on-chain historical performance by comparing the predictions he has attested to with the repayment status of those debts. Herein lies the incentive for underwriters like Charlie to do whatever is in their power to make sure debtors repay — if Charlie’s predictions line up with reality well, the market ought to gravitate towards leveraging his services more often and at a higher fee.

How an underwriter chooses to deter defaults is intentionally out of the scope of what Dharma protocol defines, but there are innumerable routes an underwriter can take to incentivize repayment both on and off chain. At a minimum, underwriters can leverage the traditional, offline collections mechanisms most lenders rely on today — courts, contracts, collections agencies, etc.

More interesting, though, are mechanisms which leverage smart contracts to deter defaults — for instance, on-chain collateralization schemes where, as a prerequisite for receiving an underwriter’s attestation, a debtor is required to lock a certain number of tokens into a smart contract that releases the tokens to a creditor if the terms contract indicates that the debt has begun to default.

These mechanisms will be elaborated on in future posts — what is important to understand is that, at a protocol level, Dharma is agnostic to the deterrence methodology.

Note: There are several aspects of the underwriting mechanism that are either simplified or omitted in this explanation. Most importantly, a crucial caveat not discussed above is the risk of fraudulent underwriters and the necessity that underwriters be trusted entities (see here).


Alice can now broadcast her signed, underwritten debt order via any channel that lets her reach potential creditors. In practicality, the majority of borrowers would likely prefer not to solicit funds from their friends and family on social media. If we want to create debt markets that hold a candle to their traditional counterparts, we need to construct some sort of mechanism for connecting debtors to potential creditors. We introduce relayers — a concept borrowed from the 0x protocol — to fill this gap.

Relayers are centralized entities that “relay” debt orders from debtors to potential creditors, and collect a fee in the event that an order is filled. Their job is simple — to provide creditors with a centralized interface for browsing through different debt orders, and to give debtors a means of broadcasting their orders to a broad, general audience.

In Alice and Bob’s example, we can introduce a relayer Dave into the transaction. Let’s imagine Dave is a Chinese entrepreneur who builds a debt crowdfunding platform tailored to Chinese retail investors — Dave accepts debt orders from a host of underwriters around the world, and earns a fee anytime those debt orders are filled by creditors on his platform. Alice would send her debt order to Dave, who would list her order on his platform after amending it to include his fee allocation and signature — i.e.:
I, holder of public key Y, in exchange for 1 ether paid upfront, agree to repay the debt under the conditions defined in terms contract X.
And I, holder of public key Z, in exchange for 0.001 ether paid by both the creditor and debtor of this transaction, underwrite this debt agreement as having a 90% likelihood of being repaid.
And I, holder of public key R, in exchange for 0.001 ether paid by both the creditor and debtor of this transaction, have relayed this transaction to potential creditors on my platform.
In a manner similar to that of the underwriter scheme, Dave will be paid the defined fee once Alice’s order is filled by Bob on Dave’s platform.

Note that relayers can come in many different flavors — here we imagine Dave as hosting a centralized debt crowdfunding platform, but we could conceive of relayers who act as thin APIs catering to developers and arbitragers writing auto-investment bots, or, on the opposite side of the spectrum, operating entirely offline and manually relaying large packages of debt to institutional investors. Future posts will elaborate on some of the more novel strategies relayers can take in the Dharma debt issuance scheme.


We can summarize the above as follows:

  • Dharma protocol is an end-to-end mechanism for issuing, underwriting, and administering debt instruments of virtually any type as tradeable, programmable tokens.
  • The repayment terms of any debt agreement in Dharma protocol are codified by a type of smart contract we refer to as a terms contract.
  • Potential debtors request loans using a signed message packet we refer to as a debt order.
  • Debt orders can be sent to prospective creditors via any channel — email, Twitter, Slack, Relayers, etc.
  • Creditors “fill” a debt order by submitting a debtor’s signed debt order to a smart contract we refer to as the debt kernel, an action that synchronously transfers the principle amount from the creditor to the debtor and issues the creditor a tradeable debt token that is unique to the debt agreement.
  • Underwriters are trusted, centralized entities that, for a fee, vouch for the creditworthiness of a borrower and do everything in their power to make sure that the given debt is properly repaid.
  • Relayers are entities that, for a fee, facilitate the funding of debt orders by broadcasting signed debt orders to potential creditors on debtors’ behalves.
Again, it’s important to note that this post glosses over many important details, processes, and limitations of the protocol — if your interest is sufficiently piqued, we suggest doing a deep dive into the technical white paper. Additionally, you can subscribe to the Dharma Mailing List for weekly content, progress updates, and early access to releases we’ll be rolling out over the coming months.

We’re excited about the community we’re building around Dharma protocol, and look forward to hearing your questions, thoughts, and constructive feedback on the Dharma community chat channel.

Welcome aboard!

— N

  • Introduction

  • Hello, World!

  • Underwriters

  • Relayers

  • Summary