---
tags: Smart Invoice
---

# Smart Invoice w/ Escrow ADR -- Design Document

As the first deliverable for this Aragon Conviction Funding [grant](https://conviction.aragon.org/#/proposal/9) [proposal](https://forum.aragon.org/t/dao-payment-escrow-with-aragon-court-arbitration/2269), this document specifies the design for the Smart Invoice w/ Escrow ADR, including integrating Aragon Court.

## Background
Raid Guild is a DAO-based web3 freelancer cooperative. Clients hire us to design and build web3 products for them. We recently built a disputable escrow tool that minimizes risk for all parties involved. Clients deposit funds into the escrow contract, then funds are released to us as project milestones are reached. If there’s a dispute over milestone deliverables a dispute can be raised for an alternative dispute resolution (ADR) provider to distribute funds appropriately.

Under this proposal, we are adding Aragon Court as an ADR option and generalizing/productizing the tool so that any DAO (or individual) can use it to accept payment from their clients. The benefit to the DAO (service provider) is knowing with certainty that the client can pay before starting any work. The benefit to the client is increased control over the release of funds to the DAO based on receipt of deliverables as specified in the project agreement. The embedded dispute resolution service -- for which Aragon Court will be an option -- ensures that funds will be fairly dispersed even in the event of a dispute.

### Key Questions
Phase 1 of our work covered research and design. This document summarizes the result of our research, focusing primarily on how we are addressing the following key questions:

1. How can Aragon Court be added as an arbitration provider / dispute resolver to the existing LexGuildLocker contract?
2. How can the escrow service (contract, front-end, and private back-end) be productized for use by any DAO?
3. How can variable sized milestones be supported?
4. Can / should we enable Aragon Conviction Voting to send to an escrow?

## Design
### Aragon Court Integration
> How can Aragon Court be added as an arbitration provider / dispute resolver to the existing LexGuildLocker contract?

This shall involve the following changes to the contract:
- Add extra parameter in `Locker` struct to identity type of ADR, namely LexDAO or Aragon Court.
- Extend `LexGuildLocker` contract to implement necessary methods of Aragon's `IArbitrable` interface.
- Enumerate `ruling` possibilities ranging from [0, 100] to [100, 0] distribution of remaining funds.
- Update `lock` method
- pay the court fees by calling `getDisputeFees()`.
- to call `createDispute` method of Aragon Court with number of `ruling` as created in previous step.

**Note:** In the case of Aragon Court, the UX will change slightly as there may be extra steps to ensure that the Locker has necessary funds to raise the Dispute with Aragon.
<!--
[TODO]
- IArbitrable and IArbitrator
- enumerate `ruling` possibilities
- outstanding question: Aragon Court fee -->

### Productization / General DAO availability
> How can the escrow service (contract, front-end, and private back-end) be productized for use by any DAO?

The existing Raid Guild escrow app uses a private database (Airtable) to keep project & transaction metadata privately viewable only by Raid Guild and its clients. To maintain this capability in the current design would require replacing the web2 database with a web3-native storage and access control solution. Unfortunately, none of the existing options we researched -- Textile Buckets and Threads; avionDB -- currently meet our specifications for access control. It is likely possible to extend those implementations for our purposes, but that effort falls outside the present scope. Perhaps as technologies mature, we can implement the privacy features in a future version.

From a UX perspective, any person can create a Smart Invoice w/ Escrow by providing project and payment data in the UI. The invoice creator must provide a name and link to project agreement (e.g., a text document) to assist with arbitration. Since all data is stored on-chain, users with privacy concerns may opt to obscure project identity by using a codename and link to a document that requires permission to view.


#### Single Dapp
For the present scope, we will remove the private metadata component. That change allows us to create a single dapp that can be used by any DAO or individual parties.

All the code will be open source, so the dapp can be re-implemented or customized to meet specialized needs.

#### Front End Application: "Smart Invoice"
We envision this single application serving as a tool for DAOs and their counterparties to pay each other for services securely. Traditionally, services rendered are paid for once the service provider invoices the client. With this escrow application, service providers can now send invoices *upfront*, with appropriate payment and dispute resolution supported by ADR. We call these "Smart Invoices".


With this system, the client is able to control when each payment is released.


#### DAO usage
Managing an escrow requires the ability to make several interactions with the escrow. The service provider needs to be able to Lock funds to trigger a dispute with the client, and the client needs to be able to a) Release funds as milestones are met, and b) Lock funds to trigger a dispute with the service provider.

Each of these interactions involves a sending a transaction, which can be difficult for DAOs and multisigs to make via a typical web front end. To allow DAOs to use this app, our front end will generate and display the transaction hex for all relevant transactions. DAO representatives can then use that hex code to create a transaction from their DAO or multisig interface (e.g., Aragon Agent, Moloch Minion, Gnosis Safe).

### Notes and additional details
> Can / should we enable Aragon Conviction Funding to send to an escrow?

Our recommendation for enabling this capability is that the Aragon Conviction Funding (ACF) module should be extended to enable arbitrary contract calls. There are two main reasons for this:
1. Depositing is not the only instance where ACF would want to be able to interact with the escrow. It would also need to Release funds as the grantee meets the established milestones as well as Lock funds (i.e. send to arbitration) if a dispute with the grantee arises. Those interactions would require contract calls, too.
2. The requisite changes to the existing LexGuildLocker contract would be substantial and fall outside the present scope.

> How can variable sized milestones be supported?

We will update the `milestones` escrow parameter to take a schedule of arbitrarily-sized payments (i.e. `milestones = uint256[]`) instead of denoting the number of uniform payments.