SEP-31: add mermaid sequence diagram (#1145)

stellar · Mar 8, 2022 · 623a2d3 · 623a2d3
1 parent cc75223
commit 623a2d3
Showing 1 changed file with 74 additions and 3 deletions.
diff --git a/ecosystem/sep-0031.md b/ecosystem/sep-0031.md
@@ -7,8 +7,8 @@ Title: Cross-Border Payments API
 Author: SDF
 Status: Active
 Created: 2020-04-07
-Updated: 2021-10-22
-Version 1.5.0
+Updated: 2022-03-08
+Version 1.5.1
 ```
 
 ## Simple Summary
@@ -36,6 +36,76 @@ Typically, the Sending and Receiving Clients reside in different regulatory juri
 
 Alice in Nigeria wants to send money to Bob in Europe. Alice signs up with NigeriaPay to make this payment to send money directly into Bob’s bank account. Bob doesn’t need to do anything, or know anything about this payment, besides letting Alice know what his bank account information is. Alice only needs to deal with her anchor (NigeriaPay). Alice passes this information and her money to NigeriaPay, and NigeriaPay sends those funds to the EuroPay Anchor service, and Europay deposits those funds into Bob’s bank account.
 
+## Diagrams
+
+The diagrams provided offer a detailed view of various flows that are possible using this protocol. Note that these diagrams are opinionated. Variations of the these flows may also be sufficient.
+
+### Completing a Transaction with a Firm Quote
+
+This diagram demonstrates the interactions between the entities involved in a successful transaction. Specifically it uses the [Receiving Anchor Asset Conversion](#receiving-anchor-asset-conversion) strategy defined described later in the document.
+
+```mermaid
+sequenceDiagram
+    participant Sending Client
+    participant Sending Anchor
+    participant Stellar
+    participant Receiving Anchor
+    participant Receiving Client
+    Sending Client->>Sending Anchor: initiates send to <br> Receiving Client's country
+    Sending Anchor-->>Sending Anchor: maps country to Receiving Anchor
+
+    Sending Anchor->>+Receiving Anchor: GET /.well-known/stellar.toml
+    Receiving Anchor-->>-Sending Anchor: SEP-10, 12, 31, & 38 URLs
+    Sending Anchor->>+Receiving Anchor: GET [SEP-31]/info
+    Receiving Anchor-->>-Sending Anchor: Stellar assets, customer types, fees
+    Sending Anchor->>+Receiving Anchor: GET [SEP-38]/prices
+    Receiving Anchor-->>-Sending Anchor: pairs and est. rates for Stellar asset
+
+    Sending Anchor-->>Sending Anchor: calculates fiat-to-fiat est. rates
+    Sending Anchor->>+Sending Client: provides pair <br> est. rates & fees
+    Sending Client-->>-Sending Anchor: selects asset pair
+
+    Sending Anchor->>+Receiving Anchor: GET [SEP-10]
+    Receiving Anchor-->>-Sending Anchor: challenge transaction
+    Sending Anchor-->>Sending Anchor: signs challenge
+    Sending Anchor->>+Receiving Anchor: POST [SEP-10]
+    Receiving Anchor-->>Receiving Anchor: verifies challenge
+    Receiving Anchor-->>-Sending Anchor: authentication token
+
+    loop once for Sending Client, once of Receiving Client
+        note right of Sending Anchor: If Sending Client or Receiving Client <br >has already been <br> accepted, this section <br> is unnecessary.
+        Sending Anchor->>+Receiving Anchor: GET [SEP-12]/customer?type=
+        Receiving Anchor-->>-Sending Anchor: fields required
+        Sending Anchor->>+Sending Client: requests fields
+        Sending Client-->>-Sending Anchor: provides field values
+        Sending Anchor->>+Receiving Anchor: PUT [SEP-12]/customer?type=
+        Receiving Anchor-->>Receiving Anchor: validates KYC values
+        Receiving Anchor-->>-Sending Anchor: id, ACCEPTED
+    end
+
+    Sending Anchor->>+Receiving Anchor: GET [SEP-38]/price
+    Receiving Anchor-->>-Sending Anchor: exchange rate
+    Sending Anchor->>+Sending Client: provides estimated rate
+    Sending Client-->>-Sending Anchor: continues
+    Sending Anchor->>+Receiving Anchor: POST [SEP-38]/quote
+    Receiving Anchor-->>Sending Anchor: quote id, rate, expiration
+    
+    Sending Anchor->>+Receiving Anchor: POST [SEP-31]/transactions
+    Receiving Anchor-->>Receiving Anchor: checks customer statuses, <br> links quote, <br> creates transaction record
+    Receiving Anchor-->>-Sending Anchor: transaction id, receiving account & memo
+
+    Sending Anchor->>+Stellar: submit Stellar payment
+    Stellar->>+Receiving Anchor: receives payment, matches w/ transaction
+    Receiving Anchor-->>Receiving Anchor: updates transaction status
+    Stellar-->>-Sending Anchor: success response
+
+    Receiving Anchor->>Receiving Client: Sends off-chain payment to recipient
+    Receiving Anchor-->>Receiving Anchor: updates transaction to complete
+    Sending Anchor->>+Receiving Anchor: GET /transactions?id=
+    Receiving Anchor-->>-Sending Anchor: transaction complete
+    Sending Anchor->>Sending Client: notifies sender
+```
+
 ## Prerequisites
 
 * The Receiving Anchor must define `DIRECT_PAYMENT_SERVER` in their [`stellar.toml`](sep-0001.md).
@@ -631,4 +701,5 @@ If the information was malformed, or if the sender tried to update data that isn
 
 ## Changelog
 
-* `v1.5.0`: Deprecate refunded boolean. Add refund object to transaction records. ([#1128](https://github.com/stellar/stellar-protocol/pull/1128))
+* `v1.5.1`: Add a sequence diagram for successful transactions using firm quotes. ([#1145](https://github.com/stellar/stellar-protocol/pull/1145))
+* `v1.5.0`: Deprecate refunded boolean. Add refund object to transaction records. ([#1128](https://github.com/stellar/stellar-protocol/pull/1128))