Agreements Framework v1 Definition

[xPi2]

My proposal for the Agreement entity in the Court system is based on @luisivan draft.
Consider the arbitrator as the Court.

Overview

An agreement can be defined as an arbitrated escrow contract between two or more parties.
Agreements allow reliable relationships between non-trusted parties using a trusted arbitrator with the capacity to punish breaches and misbehaviour from the parties.

Creation

When users create an agreement, they define some parameters that will be held public:

• A hash of the terms / meta-evidence file of the agreement. This will be used by joining parties to verify to what they are agreeing to without having to publicly disclose the details. In case of disputa this hash will be also used by the arbitrators to verify claims & allegations by the parties.
• The collateral amount needed by each party to join the agreement. In the case of dispute the arbitrator will distribute this colateral as needed. Arbitration fees are discounted from this colateral. The parties will be able to withdrawn their colateral once the agreement is settled.

Agreements can be created open for any party that provides the required collateral to join, or restricted specifying the expected parties and which amount is expected from each party.

Participation

Once the agreement is created, the parties can join by depositing the required colateral.

When joining the agreement, the parties commit to comply to the terms & conditions of the agreement itself and the agreement framework in which is held. They acknowledge the power of the arbitrator to mediate & resolve disputes between the parties.

Termination

An agreement is terminated by the consensus of the parties involved, or in the case of a dispute, when the arbitrator resolves.

Once the agreement is terminated, all parties can withdrawn their position from the agreement. When withdraw the parties recover the colateral they deposited in the case of an optimistic settlement or what is left in case of a dispute.

Dispute

If the parties do not achieve needed consensus to settle an agreement they can raise a dispute for the arbitrator to mediate.

The arbitration fee will be discounted from the deposited capital only when the arbitrator resolves a dispute successfully.

Dispute resolution

When an agreement is in dispute the arbitrator can resolve providing the needed adjustment to the agreements positions.
This adjustments will be made in a single transaction together with the agreement termination. Ideally this transaction will have a delay that would allow the parties to appeal the resolution before is settled.

Technical Specs

Agreement

An agreement is composed by 5 key components:

• The termsHash is a hash of the detailed terms & conditions that all parties agree to when joining an agreement. This terms can be held privately until a dispute is raised, in which case, this hash will be used to verify the allegations submitted to the arbitrator by both parties.
• The criteria is the requirement to join an agreement. Indicates the amount of tokens required to join an agreement, or in the case of an advanced criteria, the root of a Merkle tree composed of the allowed accounts and amount of tokens per account to join.
• The party contains an array of addresses that have joined the agreement.
• The position contains an array of positions that take part in the agreement, where each position consists of the following:
• • The partyId indicates the id of the party in the party array that holds that position.
• • The balance indicates the amount of tokens held in the agreement by the party.
• • The status indicates the status of the position in the agreement. Currently idle or terminated (WIP).

Agreement Framework

• The arbitrator is the account with the power to resolve disputes.
• The arbitrationFee is the amount of tokens required by party to pay for the arbitration services. This will only be discounted from parties positions on a successful arbitration.
• The agreement is the array of agreements held in the framework.

Methods

• Create a new agreement providing the terms hash & criteria to join.
• Join an existing agreement depositing the required amount.
• Join an existing agreement proofing that you are an allowed party and depositing the required amount.
• Agree to terminate an agreement in which you take part. Will require the termination request from all the parties to be actually terminated.
• Start a dispute over an agreement in which you take part.
• Resolve a dispute providing needed adjustment to the positions of the agreements. Only callable by the arbitrator when the agreement is in dispute.

[xPi2]

How should the appeal process work? Should we let the implementation details to each type of agreement?

[luisivan]

As discussed, for now the appeals process can just be a vote for the DAO to chime in, in case of juror misconduct.

[xPi2]

I've updated the proposal with latest changes

[luisivan]

Question that emerged when I started designing: We need a way for users to identify agreements easily from the UI, without having to open the file with the terms. I see two ways:

• Including a variable to name the agreement in the contract
• Standardizing that the first line of the agreement file (which I think we should standardize using MarkDown for) is the agreement name. Then from the frontend we can parse the terms file (we would need the user to upload it), extract the first title and use it as the name

[xPi2]

IMO we shouldn't store the name of the agreement in the contract.
By your suggestion I guess we should add to the scope of the project a minimal backend services to improve UX. We could use Supabase for example.

[luisivan]

Are you thinking we would store the terms in the server? That would be too privacy-intrusive/miss the point of private agreements, but the alternatives are:

1. Each person is responsible for safeguarding the terms in their devices
2. The terms get uploaded and encrypted for the participants (we would have they addresses, so we can encrypt the terms for them)

I like #2, it indeed adds the need for a backend but it should literally do storage, as the browser can encrypt the terms for each of the participants in the criteria, and then each user's browser would download the encrypted version, decrypt it and parse it.

That wouldn't work with open agreements in which anyone can join in, but for those the terms would have to be public anyway.

[xPi2]

I didn't say "store the terms" Lol.
I don't want to store the terms anywhere. Still, we can store simple mappings by user of agreement aliases, address aliases, etc. Such as you can see in DApps like Parcel or even Gnosis Safe. User logs in by signing (like Parcel); we fetch user data by signature instead of by address. So, even though someone could access your stored values, it's not easy to relate to anyone (ideally, none of the stored values will be sensitive).

[luisivan]

So, just to clarify, when you mean mappings of user agreement aliases, does that mean the "name" that the user sets to an agreement?

That would require each user to label the agreement and the addresses, right? I still think an easier way would to upload and encrypt the terms for the participants.