chore: Sign API diagrams

docs/specs/clients/sign/session-proposal.md

@@ -37,3 +37,126 @@ Proposal protocol will be established as follows:
 8. Dapp settles session with topic B using derived key
 9. Dapp receives settlement on topic B
 10. Dapp sends acknowledgment on topic B
+
+Note: numbers below are different from above
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant D AS dApp
+  participant DS AS dApp Sign client
+  participant R as Relay
+  participant WS AS Wallet Sign client
+  participant W as Wallet
+
+  activate D
+  D->>+DS: User clicks connect
+  DS->>+R: SDK connects to relay<br>Time: TLS connection
+  R-->>-DS: connected
+  DS->>+R: WebSocket upgrade<br>Time: network latency
+  R-->>-DS: complete
+  Note over DS: engine.connect()
+  Note over DS: pairing.create()
+  Note over DS: generate pairing symkey and topic
+  Note over DS: generate pairing URI<br>(symkey, topic, etc.)
+  DS->>+R: subscribe to pairing topic<br>Time: network latency
+  Note over R: optimistic subscribe<br>Time: 0ms
+  R-->>-DS: ACK subscribe<br>Time: network latency
+  Note over R: IRN: poll mailbox
+  Note over R: IRN: check subscriber count
+  Note over R: IRN: add subscription
+  Note over DS: ret pairing.create()
+  Note over DS: generate key pair X
+  Note over DS: prepare session proposal<br>(public key X, required + optional namespaces)
+  DS->>+R: publish session proposal request to pairing topic<br>Time: network latency
+  Note over R: IRN: get subscribers (0)
+  Note over R: IRN: get mailbox size
+  Note over R: IRN: store in mailbox
+  Note over R: Time: 3 IRN ops
+  R-->>-DS: ACK publish<br>Time: network latency
+  DS-->>-D: pairing URI
+  Note over D: display pairing URI to user
+  D->>+W: pairing URI
+
+  Note over W: user scans pairing URI
+  W->>+WS: engine.pair()
+  WS->>+R: SDK connects to relay<br>Time: TLS connection
+  R-->>-WS: connected
+  WS->>+R: WebSocket upgrade<br>Time: network latency
+  R-->>-WS: complete
+  WS->>+R: subscribe to pairing topic<br>Time: network latency
+  Note over R: optimistic subscribe<br>Time: 0ms
+  R-->>-WS: ACK subscribe<br>Time: not critical path
+  Note over R: IRN: poll mailbox
+  Note over R: Time: 1 IRN ops
+  R->>WS: receive session proposal request<br>Time: network latency
+  Note over R: IRN: check subscriber count
+  Note over R: IRN: add subscription
+  WS->>W: emit session_proposal
+
+  W->>WS: approve()
+  Note over WS: generate key pair Y
+  Note over WS: derive session symkey (pubX, privY) and topic
+  WS->>+R: subscribe to session topic<br>Time: network latency
+  Note over R: optimistic subscribe<br>Time: 0ms
+  R-->>-WS: ACK subscribe<br>Time: network latency
+  Note over R: IRN: poll mailbox
+  Note over R: IRN: check subscriber count
+  Note over R: IRN: add subscription
+  Note over WS: generate session settlement (public key Y)
+  Note over WS: generate session proposal response (public key Y)
+  WS->>+R: publish session settlement request to session topic<br>Time: network latency
+  Note over R: IRN: get subscribers (0)
+  Note over R: IRN: get mailbox size
+  Note over R: IRN: store in mailbox
+  Note over R: Time: 2 IRN op
+  R-->>-WS: ACK publish<br>Time: network latency
+  WS->>+R: publish session proposal response to pairing topic<br>Time: network latency
+  Note over R: IRN: get subscribers (1)
+  Note over R: Realtime delivery
+  Note over R: IRN: get mailbox size
+  Note over R: IRN: store in mailbox
+  Note over R: Time: min (1 IRN op +<br>2x dapp network latency, 2 IRN op)
+  R-->>-WS: ACK publish<br>Time: network latency
+  WS-->>W: session_connect
+
+  DS->>+R: SDK connects to relay<br>Time: TLS connection
+  R-->>-DS: connected
+  DS->>+R: WebSocket upgrade<br>Time: network latency
+  R-->>-DS: complete
+  R->>+DS: receive session proposal<br>Time: network latency
+  Note over DS: derive session symkey (privX, pubY) and topic
+  DS->>+R: subscribe to session topic<br>Time: network latency
+  Note over R: optimistic subscribe<br>Time: 0ms
+  R-->>-DS: ACK subscribe<br>Time: not critical path
+  Note over R: IRN: poll mailbox
+  Note over R: Time: 1 IRN op
+  R->>DS: receive session settlement request<br>Time: network latency
+  Note over R: IRN: check subscriber count
+  Note over R: IRN: add subscription
+  Note over DS: TODO what is exact behavior & timing here?
+  DS->>+R: publish session settlement response<br>Time: network latency
+  R-->>-DS: ACK publish<br>Time: network latency
+  DS-->>-D: connected
+  deactivate D
+
+  R->>WS: receive session settlement response
+  WS->>W: session_approve
+  deactivate WS
+  deactivate W
+
+  activate D
+  D->>+DS: user requests signature
+  Note over DS: TODO
+```
+
+```mermaid
+stateDiagram-v2
+  SP: Session proposed
+  PR: Proposal received
+  S: Settled
+  [*] --> SP
+  SP --> PR: scans QR code
+  PR --> S
+  S --> [*]
+```