DebtRegistry Specification

Version 0.0.1

Overview

The DebtRegistry contract serves as the canonical registry of all debt agreements issued via Dharma protocol. We intentionally heavily restrict the mutability of the registry such that only an extremely limited set of mutations on the registry can be executed by a well-defined set of parties. Moreover, we design the registry in a manner that is future-proof, modular, and upgradeable. First, we define some terminology:

Terminology

1. Creditor - the address of an entity who "owns" a given debt and expects to receive repayments from it.

2. TermsContract - the address of a smart contract adhering to the Terms Contract Interface -- this contract defines the expected terms of repayment and can be used to deterministically determine whether or not a given debt has been defaulted on.

3. TermsContractParameters - a string of text ingested by a given terms contract that contains parameters defining repayment terms in a given TermsContract. As an example, a TermsContract could define a generic, simple interest rate repayment scheme, and its associated TermsContractParameters string would contain the interest rate parameter. The schema of the TermsContractParameters is not enforced by the DebtRegistry, but, rather, can vary based on the TermsContract it is associated with.

4. Agents - addresses that have permission to execute a certain type of mutation on the registry (not to be confused with "agents" as defined in the Dharma white paper)

5. Owner - the address of the contract's owner. Can be an entity's address or a multisig wallet.

6. Version - an address specifying the version of the TermsContractInterface which any given entry's TermsContract adheres to. The address is not that of the Terms Contract, but, rather, is that of the RepaymentRouter used by this particular debt agreement, given that upgrades to the terms contract interface require a corresponding upgrade to the RepaymentRouter used.

7. Underwriter - refer to the the Dharma whitepaper.

8. Underwriter Risk Rating - refer to the the Dharma whitepaper.

9. Entry Hash - a hash of the debt issuance commitment associated with any given registry entry.

DebtRegistry Entry Schema

Each entry stores the following data points in some capacity:

{
  version: <Version String>
  creditor: <Creditor's Address>,
  termsContract: <Terms Contract Address>,
  termsContractParameters: <Terms Contract Parameters String>,
  underwriter: <Underwriter Address>,
  underwriterRiskRating: <Underwriter's Risk Rating>,
  entryHash: <Entry Hash>
}

Permitted Mutations

There are two types of mutations agents are allowed to make on the registry:

1. INSERT - inserting a new entry into the DebtRegistry
2. MODIFY_CREDITOR - changing the address of the creditor in an existing entry

Note that the registry does no validation on data mutations it undergoes -- it assumes agents have properly validated that entries are properly formed.

Mutation Permission Set

Each type of mutation is associated with a mutually exclusive set of agents who are authorized to make that mutation, i.e. there is a set of agents that are allowed to make INSERT operations and a separate set of agents that are allowed to make MODIFY_CREDITOR operations.

In practice, each set will likely only have the address of one agent in it at a time -- namely, the INSERT operation's permitted set will include only the DebtKernel contract address and the MODIFY_CREDITOR operation's permitted set will include only the DebtToken contract address. We intentionally heavily restrict the range of permitted functionality in order to minimize the attack surface of the registry.

Only the contract owner has the ability to authorize / revoke authorizations in each permission set.

Terms Contract Interface Version Link

We use the deployed address of a RepaymentRouter contract as the functional "version" of the terms contract interface an entry expects to interact with. This is because, were we to ever update the terms contract interface, a corresponding update to the RepaymentRouter would be necessary in order to maintain compatibility. Thus, when a debtor makes a repayment for a given debt, they use the version field to determine what the correct address is for the RepaymentRouter the given debt is expected to interact with.

Upgrade Procedures

The reason we allow each operation's permitted set to include multiple agents is for purposes of upgrading the protocol's contract -- if we wish to upgrade, say, the DebtKernel contract, we can deploy a new DebtKernel contract, add it to the MODIFY_CREDITOR operation's permitted set of addresses, and, once a majority of client applications have migrated to using the new DebtKernel contract, remove the old DebtKernel from the permitted set.