account-lookup-service 15.6.0-snapshot.4 → 16.1.0-iso.0

package/docs/Proxy/P2P.md

@@ -0,0 +1,11 @@
+# P2P flow across network using Proxy
+This design make the following assumptions
+1. No two connected participant have the same identifier
+1. No limit checks are done against proxy participants
+1. Get /transactionRequests are resolved at the payee scheme
+1. Timeouts in non-payee schemes are  disabled (maybe enlarged)
+
+## Sequence Diagram
+Here is a sequence diagram show the Agreement and Transfer stages of a transaction, and how the Get Transfer is resolved.
+
+![P2P flow](./Proxy%20pattern%20-%20P2P.png)

package/docs/Proxy/Proxy pattern - Happy path.plantuml

@@ -0,0 +1,98 @@
+@startuml
+
+title Proxy Patterns - Happy Path 
+
+participant "Payer DFSP" as payerDFSP
+box "Scheme A"
+    participant "Handler\nScheme A" as schemeA
+    participant "Proxy Cache\nScheme A" as pc_A
+end box
+participant "Proxy AB" as xnp
+box "Scheme B"
+    participant "Handler\nScheme B" as schemeB
+    participant "Proxy Cache\nScheme B" as pc_B
+end box
+participant "Payee DFS" as payeeDFSP
+
+autonumber 1 "<b>[0]"
+
+== POST ==
+payerDFSP ->> schemeA: POST /xxx
+note left
+header
+  source: payerDFSP
+  destination: payeeDFSP
+body
+ {ID: 1234}
+end note
+schemeA -> pc_A: Destination not in scheme:\n payeeDFSP has a proxy mapped\n need to send to 'Proxy AB'
+schemeA ->> xnp: POST /xxx
+xnp->xnp: Add header
+    note left
+    fxpiop-proxy = "Proxy AB"
+    end note
+xnp ->> schemeB: POST /xxx
+note left
+Message if forwarded to schemeB unmodified
+end note
+    
+schemeB -->> xnp: 202 OK
+xnp -->> schemeA: 202 OK
+
+schemeB ->> payeeDFSP: POST /xxx
+
+== GET ==
+payerDFSP -> schemeA: GET /xxx/{ID} \nwithout destination
+note left
+  source: payerDFSP
+end note
+
+schemeA->schemeA: lookup if ID result and triggers put
+
+payerDFSP -> schemeA: GET /xxx/{ID} \nwith destination
+note left
+  source: payerDFSP
+  destination: payeeDFSP
+end note
+
+schemeA -> pc_A: Destination not in scheme:\n payeeDFSP has a proxy mapped\n need to send to 'Proxy AB'
+schemeA ->> xnp: GET /xxx
+xnp->xnp: Add header
+    note left
+    fxpiop-proxy = "Proxy AB"
+    end note
+xnp ->> schemeB: GET /xxx
+note left
+Message if forwarded to schemeB unmodified
+end note
+schemeB -->> xnp: 202 OK
+xnp -->> schemeA: 202 OK
+
+schemeB ->> payeeDFSP: GET /xxx
+
+
+
+== PUT ==
+
+
+payeeDFSP -> schemeB: PUT /xxx
+note right
+    source: payeeDFSP
+    destination: payerDFSP
+end note
+schemeB -> pc_B: Destination not in scheme:\n payerDFSP has a proxy mapped\n need to send to 'Proxy AB'
+schemeB -> xnp: PUT /xxx
+xnp->xnp: Add header
+    note left
+    fxpiop-proxy = "Proxy AB"
+    end note
+xnp -> schemeA: PUT /xxx
+note right
+Message if forwarded to schemeA unmodified
+end note
+schemeA -->> xnp: 200 OK
+xnp -->> schemeB: 200 OK
+
+schemeA -> payerDFSP: PUT /xxx
+
+@enduml

package/docs/Proxy/Proxy pattern - Lazy Discovery - No Oracles.plantuml

@@ -0,0 +1,105 @@
+@startuml
+
+title Lazy Discovery - No Oracles Registered
+
+participant "Payer DFSP" as payerDFSP
+box "Scheme A"
+    participant "ALS\nScheme A" as ALS_A
+    participant "Proxy Cache\nScheme A" as pc_A
+end box
+participant "XN Proxy" as xnp
+participant "other DFSPs" as dfspsA
+box "Scheme B"
+    participant "ALS\nScheme B" as ALS_B
+    participant "Proxy Cache\nScheme B" as pc_B
+end box
+participant "Payee DFS" as payeeDFSP
+participant "other DFSPs" as dfspsB
+
+autonumber 1 "<b>[0]"
+
+== First time Party Identifier is used ==
+payerDFSP ->> ALS_A: GET /parties/{Type}/{ID}
+
+note left
+ header source = payerDFSP
+end note
+ALS_A ->> ALS_A: Lookup if {Type} and {ID} is mapped to dfsp
+alt if not cached
+  loop for all DFSPs in Scheme A and not source    
+  alt if XN Proxy
+    ALS_A ->> xnp: GET /parties/{Type}/{ID}  
+    xnp ->> ALS_B: GET /parties/{Type}/{ID}  
+    ALS_B ->> pc_B: Source not in Scheme: \nAdd 'Payer DFSP' to 'XN Proxy' mapping
+    pc_B -> pc_B: New mapping
+    pc_B -> pc_B: Check JWS signature\n & Add to cache
+note left
+Payer DFSP : XN Proxy
+end note        
+    ALS_B -> ALS_B: Lookup if {Type} and {ID} is mapped to dfsp
+    loop for all DFSPs in Scheme B and not source    
+    alt if Payee DFSP
+        ALS_B ->> payeeDFSP: GET /parties/{Type}/{ID}  
+        payeeDFSP ->> ALS_B: PUT /parties/{ID}
+        note right
+        header desitination = payerDFSP
+        end note
+        ALS_B -> ALS_B: Update cache
+        note left
+        cache [{Type}][{ID}] = payeeDFSP
+        end note
+        ALS_B -> pc_B: Lookup payerDFSP proxy
+        ALS_B ->> xnp: PUT /parties/{ID}
+        xnp ->> ALS_A: PUT /parties/{ID}
+        ALS_A -> pc_A: Source not in Scheme: \nAdd 'Payee DFSP' to 'XN Proxy' mapping
+        pc_A -> pc_A: New mapping\nCheck JWS signature\n & Add to cache
+    note left
+    Payee DFSP : XN Proxy
+    end note        
+        ALS_A -> ALS_A: Update cache 
+        note left
+        cache [{Type}][{ID}] = XN Proxy
+        end note
+        ALS_A ->> payerDFSP: PUT /parties/{ID}
+     else if other DFSPs in Scheme B
+        ALS_B ->> dfspsB: GET /parties/{Type}/{ID}    
+        dfspsB ->> ALS_B: PUT /parties/{ID}/error
+        note right
+        header desitination = payerDFSP
+        end note
+        ALS_B ->> ALS_B: increment Scheme B Failure Count        
+        alt if Failure Count == TotalCalls
+            ALS_B -> pc_B: Lookup payerDFSP proxy
+            ALS_B ->> xnp: PUT /parties/{ID}/error
+            xnp ->> ALS_A: PUT /parties/{ID}/error
+        end
+    end
+    end loop
+  else if other DFSPs in Scheme A
+    ALS_A ->> dfspsA: GET /parties/{Type}/{ID}    
+    dfspsA ->> ALS_A: PUT /parties/{ID}/error
+    ALS_A ->> ALS_A: increment Scheme A Failure Count
+    alt if Failure Count == TotalCalls
+        ALS_A ->> payerDFSP: PUT /parties/{ID}/error
+    end
+  end  
+  end loop
+else
+  ALS_A->ALS_A: Yes, it is mapped to XN Proxy
+  ALS_A ->> xnp: GET /parties/{Type}/{ID}
+  xnp ->> ALS_B: GET /parties/{Type}/{ID}  
+  ALS_B ->> pc_B: Source not in Scheme: \nAdd 'Payer DFSP' to 'XN Proxy' mapping
+  pc_B -> pc_B: Got Mapping
+  ALS_B -> ALS_B: Lookup if {Type} and {ID} is mapped to proxy
+  ALS_B ->> payeeDFSP: GET /parties/{Type}/{ID}
+    payeeDFSP ->> ALS_B: PUT /parties/{ID}
+        note right
+        header desitination = payerDFSP
+        end note
+    ALS_B -> ALS_B: Lookup payerDFSP proxy
+    ALS_B->ALS_B: Got it; it is mapped to XN Proxy
+    ALS_B ->> xnp: PUT /parties/{ID}
+    xnp ->> ALS_A: PUT /parties/{ID}
+    ALS_A ->> payerDFSP: PUT /parties/{ID}
+end
+@enduml

package/docs/Proxy/Proxy pattern - Lazy Discovery - Oracles.plantuml

@@ -0,0 +1,130 @@
+@startuml
+
+title On Demand Discovery - Oracles
+
+participant "Payer DFSP" as payerDFSP
+box "Scheme A"
+    participant "ALS\nScheme A" as ALS_A
+    participant "Oracle\nScheme A" as Oracle_A
+    participant "Proxy Cache\nScheme A" as pc_A
+end box
+participant "other Proxies" as dfspsA
+participant "Proxy AB" as xnp
+box "Scheme B"
+    participant "ALS\nScheme B" as ALS_B
+    participant "Oracle\nScheme A" as Oracle_B
+    participant "Proxy Cache\nScheme B" as pc_B    
+end box
+participant "Payee DFS" as payeeDFSP
+
+autonumber 1 "<b>[0]"
+
+payerDFSP ->> ALS_A: GET /parties/{Type}/{ID}
+note left
+ header source = payerDFSP
+end note
+ALS_A-> Oracle_A: GET /participant/{ID}
+alt if not found in Oracle
+
+Oracle_A--> ALS_A: no dfsp found
+ALS_A ->> ALS_A: Are there any proxies in Scheme A?
+  ALS_A ->> ALS_A: Cache Proxy that will receive messages
+   note left
+     SentToProxies[{ID}] = {['Proxy AB', 'Proxy CD', 'Proxy EF']}
+   end note
+
+  loop for all Proxys in Scheme A and not source    
+  alt if Proxy AB
+    ALS_A ->> xnp: GET /parties/{Type}/{ID}      
+    xnp->xnp: Add header
+    note left
+    fxpiop-proxy = "Proxy AB"
+    end note
+
+    xnp ->> ALS_B: GET /parties/{Type}/{ID}
+    ALS_B -->> xnp: 202 OK
+    xnp -->> ALS_A: 202 OK
+    ALS_B ->> pc_B: Source not in Scheme: \nfxpiop-proxy = "Proxy AB"\nAdd 'Payer DFSP' to 'Proxy AB' mapping
+    alt not MVP
+      pc_B -> pc_B: Check JWS signature
+    end
+      pc_B -> pc_B: Add new mapping to cache
+note left
+Payer DFSP : Proxy AB
+end note        
+
+    ALS_B-> Oracle_B: GET /participant/{ID}
+    Oracle_B--> ALS_B: dfps = payeeDFSP
+    ALS_B ->> payeeDFSP: GET /parties/{Type}/{ID}  
+    payeeDFSP ->> ALS_B: PUT /parties/{ID}
+    note right
+    header desitination = payerDFSP
+    source = payeeDFSP
+    end note
+    ALS_B -> pc_B: Lookup payerDFSP proxy
+    ALS_B ->> xnp: PUT /parties/{ID}
+    xnp->xnp: Add header
+    note left
+    fxpiop-proxy = "Proxy AB"
+    end note
+    
+    xnp ->> ALS_A: PUT /parties/{ID}
+    ALS_A -->> xnp: 200 OK
+    xnp -->> ALS_B: 200 OK
+    ALS_A -> pc_A: Source not in Scheme: \nfxpiop-proxy = "Proxy AB"\nAdd 'Payee DFSP' to 'Proxy AB' mapping
+    pc_A -> pc_A: New mapping\nCheck JWS signature\n & Add to cache
+note left
+Payee DFSP : Proxy AB
+end note        
+    ALS_A -> Oracle_A: Update Oracle with mapping\nPOST /participants/{Type}/{ID} {{"fspId": "Payee DFSP"}}
+    Oracle_A--> ALS_A: 
+    ALS_A ->> payerDFSP: PUT /parties/{ID}
+  else if other Proxy in Scheme A
+    ALS_A ->> dfspsA: GET /parties/{Type}/{ID}    
+    dfspsA ->> ALS_A: PUT /parties/{ID}/error
+    ALS_A ->> ALS_A: increment Scheme A Failure Count in cache
+   note left
+     remove other Proxy from list SentToProxies[{ID}]
+   end note
+
+    alt if SentToProxies[{ID}] is empty
+        ALS_A ->> payerDFSP: PUT /parties/{ID}/error
+   note right
+     SentToProxies[{ID}] is empty
+   end note
+    end
+  end  
+end loop
+else if found in Oracle
+  Oracle_A--> ALS_A: dfsp = payeeDFSP
+
+  ALS_A->ALS_A: Payee DFSP is not in scheme A 
+  ALS_A-> pc_A: Lookup proxy for Payee DFSP
+  ALS_A->ALS_A: Add desitation to header 
+  note left 
+  destination dfsp: Payee DFSP
+  end note 
+
+  ALS_A ->> xnp: GET /parties/{Type}/{ID}
+  xnp ->> ALS_B: GET /parties/{Type}/{ID} 
+  ALS_B -->> xnp: 202 OK
+  xnp -->> ALS_A: 202 OK
+ ALS_B->ALS_B: Forward to desitination
+    ALS_B ->> payeeDFSP: GET /parties/{Type}/{ID}
+
+    payeeDFSP ->> ALS_B: PUT /parties/{ID}
+    note right
+    header desitination = payerDFSP
+    end note
+    ALS_B -> pc_B: Lookup payerDFSP proxy
+    ALS_B ->> xnp: PUT /parties/{ID}
+    xnp ->> ALS_A: PUT /parties/{ID}
+    ALS_A -->> xnp: 200 OK
+    xnp -->> ALS_B: 200 OK
+    ALS_A -> pc_A: Source not in Scheme: \nAdd 'Payee DFSP' to 'Proxy AB' mapping
+    pc_A -> pc_A: Got Mapping
+    ALS_A ->> payerDFSP: PUT /parties/{ID}
+end
+
+
+@enduml

package/docs/Proxy/Proxy pattern - Lazy Discovery Identifier Cache Invalid.plantuml

@@ -0,0 +1,72 @@
+@startuml
+
+title Lazy Discovery - Party Identifier cache no-longer valid
+
+participant "Payer DFSP" as payerDFSP
+box "Scheme A"
+    participant "ALS\nScheme A" as ALS_A
+    participant "Oracle\nScheme A" as Oracle_A
+    participant "Proxy Cache\nScheme A" as pc_A    
+end box
+participant "Proxy AB" as xnp
+box "Scheme B"
+    participant "ALS\nScheme B" as ALS_B
+    participant "Oracle\nScheme A" as Oracle_B
+    participant "Proxy Cache\nScheme B" as pc_B    
+end box
+participant "Payee DFS" as payeeDFSP
+
+autonumber 1 "<b>[0]"
+
+payerDFSP ->> ALS_A: **GET** /parties/{Type}/{ID}
+note left
+ header source = payerDFSP
+end note
+
+  ALS_A-> Oracle_A: **GET** /participant/{ID}
+  Oracle_A--> ALS_A: found DFSP = payeeDFSP
+  ALS_A ->> ALS_A: DFSP not in scheme
+  ALS_A -> pc_A: Who is payee DFSP's proxy?
+  pc_A --> ALS_A: forward to Proxy AB
+  ALS_A ->> xnp: **GET** /parties/{Type}/{ID}
+    xnp->xnp: Add header
+    note left
+    fxpiop-proxy = "Proxy AB"
+    end note
+
+  xnp ->> ALS_B: **GET** /parties/{Type}/{ID}  
+  ALS_B ->> pc_B: Source not in Scheme: \nfxpiop-proxy = "Proxy AB"\nAdd 'Payer DFSP' to 'Proxy AB' mapping
+alt not MVP
+  pc_B -> pc_B: Check JWS signature
+end
+  pc_B -> pc_B: Add new mapping to cache
+note left
+Payer DFSP : Proxy AB
+end note        
+ALS_B-> Oracle_B: **GET** /participant/{ID}
+  Oracle_B--> ALS_B: dfps = payeeDFSP
+  ALS_B ->> payeeDFSP: **GET** /parties/{Type}/{ID}
+  payeeDFSP ->> ALS_B: **PUT** /parties/{ID}/error
+  note right
+   header desitination = payerDFSP
+  end note
+  ALS_B -> pc_B: Lookup payerDFSP proxy
+  ALS_B ->> xnp: **PUT** /parties/{ID}/error
+  xnp->xnp: Add header
+    note left
+    fxpiop-proxy = "Proxy AB"
+    end note
+  xnp ->> ALS_A: **PUT** /parties/{ID}/error
+  alt message from proxy & error & desitination in scheme
+  note left ALS_A
+  fxpiop-proxy = "Proxy AB"
+  Error Code = 5107
+  Destination = Payer DFSP in Scheme A
+  end note
+  ALS_A -> Oracle_A: Remove mapping in Oracle\n **DELETE** \participants\{Type}\{ID} 
+  ALS_A ->> ALS_A: Restart the ALS get parties process
+  else
+  ALS_A->>payerDFSP: **PUT** /parties/{ID}/error
+end
+
+@enduml

package/docs/Proxy/Proxy pattern - P2P.plantuml

@@ -0,0 +1,186 @@
+@startuml
+
+title Proxy Patterns - P2P 
+
+participant "Payer DFSP" as payerDFSP
+box Scheme A
+  participant "Mojaloop\nScheme A" as schemeA
+  participant "Proxy Cache\nScheme A" as pc_A
+end box
+participant "Proxy AB" as xnp
+box Scheme B
+  participant "Mojaloop\nScheme B" as schemeB
+  participant "Proxy Cache\nScheme B" as pc_B
+end box
+participant "Payee DFS" as payeeDFSP
+
+autonumber 1 "<b>[0]"
+
+== Agreement ==
+payerDFSP ->> schemeA: POST /quotes
+note left
+header 
+  source: payerDFSP
+  destination: payeeDFSP
+JWS signed by payerDFSP
+end note
+schemeA -> pc_A: Destination not in Scheme\n Lookup proxy for payeeDFSP = Proxy AB
+schemeA ->> xnp: POST /quotes
+xnp ->> schemeB: POST /quotes\nmessage unmodified
+note left
+header 
+  source: payerDFSP
+  destination: payeeDFSP
+  fxpiop-proxy: proxyAB
+JWS signed by payerDFSP
+end note
+schemeB -->> xnp: 202 OK
+xnp -->> schemeA: 202 OK
+schemeB->>payeeDFSP: POST /quotes
+note right
+Checks JWS signed by payerDFSP
+end note
+payeeDFSP->>schemeB: PUT /quotes
+note right
+header 
+  source: payeeDFSP
+  destination: payerDFSP
+JWS signed by payeeDFSP
+end note
+schemeB -> pc_B: Destination not in Scheme\n Lookup proxy for payerDFSP = Proxy AB
+schemeB->>xnp: PUT /quotes
+xnp->>schemeA: PUT /quotes\nmessage unmodified
+note right
+header 
+  source: payeeDFSP
+  destination: payerDFSP
+  fxpiop-proxy: proxyAB
+JWS signed by payeeDFSP
+end note
+schemeA-->>xnp: 202 OK
+xnp-->>schemeB: 202 OK
+schemeA->>payerDFSP: PUT /quotes
+note left
+Checks JWS signed by payeeDFSP
+end note
+
+== Transfer ==
+
+payerDFSP ->> schemeA: POST /transfers
+note left
+header 
+  source: payerDFSP
+  destination: payeeDFSP
+JWS signed by payerDFSP
+body 
+    transferId: 1234
+end note
+schemeA -> schemeA: Payer DFSP\n - Checks limits\n - Updates position
+schemeA -> pc_A: Destination not in Scheme\nLookup proxy for payeeDFSP = Proxy AB
+schemeA ->> xnp: POST /transfers
+xnp ->> schemeB: POST /transfers
+note left
+header 
+  source: payerDFSP
+  destination: payeeDFSP
+  fxpiop-proxy: proxyAB
+JWS signed by payerDFSP
+body 
+    transferId: 1234
+end note
+schemeB -->> xnp: 202 OK
+xnp -->> schemeA: 202 OK
+schemeA -> schemeA: Disable timeout
+
+schemeB -> schemeB: Proxy AB\n **- No limit check**\n - Updates position
+schemeB->>payeeDFSP: POST /transfers
+note right
+Checks JWS signed by payerDFSP
+end note
+payeeDFSP->>schemeB: PUT /transfers \n{fulfilment: "xyz", transferState: "RESERVED"}
+note right
+header 
+  source: payeeDFSP
+  destination: payerDFSP
+JWS signed by payeeDFSP  
+end note
+schemeB -> schemeB: Payer DFSP\n - Updates position
+schemeB -> pc_B: Lookup proxy for payerDFSP = Proxy AB
+schemeB->>xnp: PUT /transfers
+xnp->>schemeA: PUT /transfers
+note right
+header 
+  source: payeeDFSP
+  destination: payerDFSP
+  fxpiop-proxy: proxyAB
+JWS signed by payeeDFSP  
+end note
+schemeA-->>xnp: 200 OK
+xnp-->>schemeB: 200 OK
+schemeB->>payeeDFSP: PATCH /transfers \n{transferState: "COMMITTED"}
+schemeA -> schemeA: NX Proxy\n - Updates position
+schemeA->>payerDFSP: PUT /transfers
+note left
+Checks JWS signed by payeeDFSP
+end note
+
+== Get Transfers ==
+
+payerDFSP ->> schemeA: GET /transfers/1234
+note left
+header 
+  source: payerDFSP
+  destination: payeeDFSP
+JWS signed by payerDFSP
+end note
+schemeA -> schemeA: Load transfer informtaion\nand check if payeeDFSP is in scheme
+schemeA -> pc_A: Destination not in Scheme\nLookup proxy for payeeDFSP = Proxy AB
+schemeA ->> xnp: GET /transfers/1234
+xnp ->> schemeB: GET /transfers/1234
+note left
+header 
+  source: payerDFSP
+  destination: payeeDFSP
+  fxpiop-proxy: proxyAB
+JWS signed by payerDFSP
+end note
+schemeB -->> xnp: 202 OK
+xnp -->> schemeA: 202 OK
+schemeB->schemeB: lookup transfer information
+schemeB->>xnp: PUT /transfers/1234
+note right
+header 
+  source: schemeB
+  destination: payerDFSP
+JWS signed by schemeB
+end note
+xnp->>schemeA: PUT /transfers/1234
+note right
+header 
+  source: schemeB
+  destination: payerDFSP
+  fxpiop-proxy: proxyAB
+JWS signed by schemeB
+end note
+schemeA-->>xnp: 200 OK
+xnp-->>schemeB: 200 OK
+schemeA->>payerDFSP: PUT /transfers/1234
+
+payeeDFSP->>schemeB: GET /transfers/1234
+note right
+header 
+  source: payeeDFSP
+JWS signed by payeeDFSP
+end note
+schemeB -> schemeB: Load transfer informtaion\nand check if payeeDFSP is in scheme
+schemeB->>payeeDFSP: Yes; return information\nPUT /transfers/1234
+note left
+header 
+  source: schemeB
+  destination: payeeDFSP
+JWS signed by schemeB
+end note
+
+
+
+@enduml