Add Raise and Resolve Dispute diagram (#427)

* Add Raise / Resolve Dispute diagram * Added Boson_Protocol_V2_-_Happy_Path_Exchange.png * Refactor/renamed happy-path-exchange.md to sequences.md * Updated all doc menus to have Sequences instead of Happy Path Exchange as the option. * In sequences.md, - added Raise and Resolve Dispute section with diagram and discussion * Updated Boson_Protocol_V2_-_Happy_Path_Exchange.png to align and size elements and similar to the raise/resolve diagram * Update sequences.md - Removed erroneous paragraph that indicated the escalation fee had to be paid at redeem time. Co-authored-by: Heather <[email protected]>
bosonprotocol · Oct 10, 2022 · 8b89237 · 8b89237
1 parent 646716d
commit 8b89237
Show file tree

Hide file tree

Showing 12 changed files with 24 additions and 18 deletions.
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 <h1 align="center">Boson Protocol V2</h1>
 
-### Intro | [Audits](docs/audits.md) | [Setup](docs/setup.md) | [Tasks](docs/tasks.md) | [Architecture](docs/architecture.md) | [Domain Model](docs/domain.md) | [State Machines](docs/state-machines.md) | [Happy Path Exchange](docs/happy-path-exchange.md) 
+### Intro | [Audits](docs/audits.md) | [Setup](docs/setup.md) | [Tasks](docs/tasks.md) | [Architecture](docs/architecture.md) | [Domain Model](docs/domain.md) | [State Machines](docs/state-machines.md) | [Sequences](docs/sequences.md) 
 
 ## Status
 Done or in progress are:
@@ -20,7 +20,7 @@ Done or in progress are:
   - ✅ Support for EIP-712 meta-transactions
   - ✅ Protocol facet contracts and interfaces
   - ✅ Remediated audits
-  - 👉 Generated contract documentation
+  - ✅ Generated contract documentation
 
 ## Developers
   - [Audits](docs/audits.md) - See the results of our latest security audits
@@ -29,7 +29,7 @@ Done or in progress are:
   - [Architecture](docs/architecture.md) - Start with the big picture
   - [Domain Model](docs/domain.md) - Entities and their relationships
   - [State Machines](docs/state-machines.md) - State Machines in the Core Exchange Mechanism
-  - [Happy Path Exchange](docs/happy-path-exchange.md) - Timeline of the simplest exchange
+  - [Sequences](docs/sequences.md) - Timeline of the simplest exchange
   - [Contributing](#contributing) - Guidelines for contributing to this repo
   - [License](#license) - License information
 

diff --git a/docs/architecture.md b/docs/architecture.md
@@ -2,7 +2,7 @@
 
 <h1 align="center">Boson Protocol V2</h1>
 
-### [Intro](../README.md) | [Audits](audits.md) | [Setup](setup.md) | [Tasks](tasks.md) | Architecture | [Domain Model](domain.md) | [State Machines](state-machines.md) | [Happy Path Exchange](happy-path-exchange.md)
+### [Intro](../README.md) | [Audits](audits.md) | [Setup](setup.md) | [Tasks](tasks.md) | Architecture | [Domain Model](domain.md) | [State Machines](state-machines.md) | [Sequences](sequences.md)
 
 ## Contract Architecture
 The V2 architecture takes a completely different approach versus V1. Considering new requirements and lessons learned, this version is geared to give us:

diff --git a/docs/audits.md b/docs/audits.md
@@ -2,7 +2,7 @@
 
 <h1 align="center">Boson Protocol V2</h1>
 
-### [Intro](../README.md) | Audits | [Setup](setup.md) | [Tasks](tasks.md) | [Architecture](architecture.md) | [Domain Model](domain.md) | [State Machines](state-machines.md) | [Happy Path Exchange](happy-path-exchange.md)
+### [Intro](../README.md) | Audits | [Setup](setup.md) | [Tasks](tasks.md) | [Architecture](architecture.md) | [Domain Model](domain.md) | [State Machines](state-machines.md) | [Sequences](sequences.md)
 
 ## Audits
 Version 2 of the Boson Protocol is an entirely new codebase and architecture from V1 and so we have once again had the  protocol thoroughly audited from top to bottom. Here are the results of those audits.

diff --git a/docs/domain.md b/docs/domain.md
@@ -2,7 +2,7 @@
 
 <h1 align="center">Boson Protocol V2</h1>
 
-### [Intro](../README.md) | [Audits](audits.md) | [Setup](setup.md) | [Tasks](tasks.md) | [Architecture](architecture.md) | Domain Model | [State Machines](state-machines.md) | [Happy Path Exchange](happy-path-exchange.md)
+### [Intro](../README.md) | [Audits](audits.md) | [Setup](setup.md) | [Tasks](tasks.md) | [Architecture](architecture.md) | Domain Model | [State Machines](state-machines.md) | [Sequences](sequences.md)
 
 ## Entity Relationship Diagram
 ![Entity Relationships](images/Boson_Protocol_V2_-_Domain_Model.png)

diff --git a/docs/images/Boson_Protocol_V2_-_Happy_Path_Exchange.png b/docs/images/Boson_Protocol_V2_-_Happy_Path_Exchange.png
diff --git a/docs/images/Boson_Protocol_V2_-_Raise_and_Resolve.png b/docs/images/Boson_Protocol_V2_-_Raise_and_Resolve.png
diff --git a/docs/limit-estimation.md b/docs/limit-estimation.md
@@ -2,7 +2,7 @@
 
 <h1 align="center">Boson Protocol V2</h1>
 
-### [Intro](../README.md) | [Audits](audits.md) | [Setup](setup.md) | [Tasks](tasks.md) | [Architecture](architecture.md) | [Domain Model](domain.md) | [State Machines](state-machines.md) | [Happy Path Exchange](happy-path-exchange.md)
+### [Intro](../README.md) | [Audits](audits.md) | [Setup](setup.md) | [Tasks](tasks.md) | [Architecture](architecture.md) | [Domain Model](domain.md) | [State Machines](state-machines.md) | [Sequences](sequences.md)
 
 # Protocol limit estimation
 

diff --git a/docs/local-development.md b/docs/local-development.md
@@ -2,7 +2,7 @@
 
 <h1 align="center">Boson Protocol V2</h1>
 
-### [Intro](../README.md) | [Audits](audits.md) | [Setup](setup.md) | [Tasks](tasks.md) | [Architecture](architecture.md) | [Domain Model](domain.md) | [State Machines](state-machines.md) | [Happy Path Exchange](happy-path-exchange.md)
+### [Intro](../README.md) | [Audits](audits.md) | [Setup](setup.md) | [Tasks](tasks.md) | [Architecture](architecture.md) | [Domain Model](domain.md) | [State Machines](state-machines.md) | [Sequences](sequences.md)
 
 ## Running against a Local Node
 If you want to develop against the Boson protocol smart contracts, you will need to deploy contracts to a local node that you can execute transactions against with scripts or a locally served instance of your dapp.

diff --git a/docs/happy-path-exchange.md → docs/sequences.md b/docs/happy-path-exchange.md → docs/sequences.md
@@ -2,15 +2,23 @@
 
 <h1 align="center">Boson Protocol V2</h1>
 
-### [Intro](../README.md) | [Audits](audits.md) | [Setup](setup.md) | [Tasks](tasks.md) | [Architecture](architecture.md) | [Domain Model](domain.md) | [State Machines](state-machines.md) | Happy Path Exchange
+### [Intro](../README.md) | [Audits](audits.md) | [Setup](setup.md) | [Tasks](tasks.md) | [Architecture](architecture.md) | [Domain Model](domain.md) | [State Machines](state-machines.md) | Sequences
 
 ## Happy Path Exchange
-![Entity Relationships](images/Boson_Protocol_V2_-_Happy_Path_Exchange.png)
+![Happy Path Exchange](images/Boson_Protocol_V2_-_Happy_Path_Exchange.png)
 
 ### About this diagram
-* This diagram shows an example timeline and sequence of protocol interactions for the simplest possible instance of the so-called "Happy Path Exchange".
-* In the happy path scenario, no dispute is raised, and the voucher is never canceled or revoked, but rather redeemed sometime within the redemption period.
+* This diagram shows an example timeline and sequence of protocol interactions for the simplest case of the so-called "Happy Path Exchange".
+* In the Happy Path scenario, no dispute is raised, and the voucher is never canceled or revoked, but rather redeemed sometime within the redemption period.
 * The diagram shows the buyer committing to the offer, but in fact anyone can commit to the offer on behalf of the buyer. In any case, it is the buyer's wallet that must complete exchange-related transactions for buyer actions after redemption.
 * "Lazy Buyer" describes the expected behavior of most buyers on the happy path. Once their order is fulfilled, no further interaction with the protocol is required on their part. In that case, the seller must wait until the dispute period has passed before they are able to complete the exchange and withdraw their funds.
 * A kind buyer could, of course, complete the exchange any time during the dispute period, releasing the funds for the seller early. They would incur a network transaction fee (gas), and so they are not expected to take this action.
 * It is also worth noting here that a seller does not have to withdraw their funds once an exchange is completed. They can leave it in the protocol to back their deposits for future exchanges, or only withdraw periodically.
+
+## Raise and Resolve a Dispute
+![Raise and Resolve a Dispute](images/Boson_Protocol_V2_-_Raise_and_Resolve.png)
+
+### About this diagram
+* This diagram shows an example timeline and sequence of protocol interactions for a dispute raised and mutually resolved by the buyer and seller.
+* In this scenario, the buyer has received damaged or otherwise unacceptable goods. Since the Dispute Period has not yet elapsed, the buyer raises a dispute. In an off-chain discussion the two parties arrive at a resolution, which essentially boils down to what percentage of the pot (all the committed funds from both parties for the current exchange) the buyer will receive. 
+* Also, as noted in the Happy Path sequence, neither party must necessarily withdraw their funds immediately nor in any particular order. Funds unencumbered at the end of an exchange accumulate for the buyer and seller, so they may withdraw all available funds from finalized exchanges at any time. The seller may leave it in the protocol to back their deposits for future exchanges. 
diff --git a/docs/setup.md b/docs/setup.md
@@ -2,7 +2,7 @@
 
 <h1 align="center">Boson Protocol V2</h1>
 
-### [Intro](../README.md) | [Audits](audits.md) | Setup | [Tasks](tasks.md) | [Architecture](architecture.md) | [Domain Model](domain.md) | [State Machines](state-machines.md) | [Happy Path Exchange](happy-path-exchange.md)
+### [Intro](../README.md) | [Audits](audits.md) | Setup | [Tasks](tasks.md) | [Architecture](architecture.md) | [Domain Model](domain.md) | [State Machines](state-machines.md) | [Sequences](sequences.md)
 
 ## Developer Setup
 The stack is a simple one:

diff --git a/docs/state-machines.md b/docs/state-machines.md
@@ -2,7 +2,7 @@
 
 <h1 align="center">Boson Protocol V2</h1>
 
-### [Intro](../README.md) | [Audits](audits.md) | [Setup](setup.md) | [Tasks](tasks.md) | [Architecture](architecture.md) | [Domain Model](domain.md) | State Machines | [Happy Path Exchange](happy-path-exchange.md)
+### [Intro](../README.md) | [Audits](audits.md) | [Setup](setup.md) | [Tasks](tasks.md) | [Architecture](architecture.md) | [Domain Model](domain.md) | State Machines | [Sequences](sequences.md)
 
 ## Core Exchange State Machines Diagram
 ![State Machines](images/Boson_Protocol_V2_-_State_Machines.png)
@@ -11,6 +11,4 @@
 * This date stamped diagram reflects the team's _current consensus_ about the state machines making up the protocol's core exchange mechanism.
 * The state of the code may be behind or at odds with this diagram; we are _working toward this_ now. 
 * Modifications to this diagram should be agreed upon by the team and this diagram updated before building if at possible.
-* If confused, _assume this diagram the source of truth_, not the code.
-
-[Source Lucidcharts Document](https://lucid.app/lucidchart/dc6bda67-0f44-4b02-889c-2f9372d437f2/edit?viewport_loc=-452%2C-129%2C2665%2C1392%2C0_0&invitationId=inv_e4012fa7-b379-4fa8-ba9e-30bc8aefa84c#)
+* If confused, _assume this diagram the source of truth_, not the code.
diff --git a/docs/tasks.md b/docs/tasks.md
@@ -2,7 +2,7 @@
 
 <h1 align="center">Boson Protocol V2</h1>
 
-### [Intro](../README.md) | [Audits](audits.md) | [Setup](setup.md) | Tasks | [Architecture](architecture.md) | [Domain Model](domain.md) | [State Machines](state-machines.md) | [Happy Path Exchange](happy-path-exchange.md)
+### [Intro](../README.md) | [Audits](audits.md) | [Setup](setup.md) | Tasks | [Architecture](architecture.md) | [Domain Model](domain.md) | [State Machines](state-machines.md) | [Sequences](sequences.md)
 
 ## Development Tasks
 Everything required to build, test, analyse, and deploy is available as an NPM script.