Merge pull request #318 from radixdlt/develop

docs: document rcfm flow

docs/rcfm.md

@@ -0,0 +1,132 @@
+# Radix Connect for Mobile
+
+## Initial Discovery
+
+Initial discovery is triggered by a deep link containing data to establish a session.
+
+Requires the Radix Wallet app to be installed on the same device.
+
+## 1. dApp → Wallet
+
+The flow is triggered by a user action, e.g. user navigating to a dApp website and clicking connect in the Radix Connect Button.
+
+The first message contains data for establishing a session and wallet interaction request.
+
+### Identity
+
+- secret – used for deriving key pair
+- ed25519 keypair – used for signing
+- x25519 keypair – used for key exchange ([Diffe-Hellman](https://en.wikipedia.org/wiki/Elliptic-curve_Diffie%E2%80%93Hellman))
+
+### Signature scheme
+
+- Curve – ed25519
+- Hash algorithm – blake2b
+- Hash digest size – 32 Bytes
+
+**Bytes to sign:**
+
+| Size     | Description                       |
+| -------- | --------------------------------- |
+| 1 Byte   | Prefix C                          |
+| 36 Bytes | Wallet interaction id (uuid v4)   |
+| 2 Bytes  | Length of dApp definition address |
+| 69 Bytes | dApp definition address           |
+| >0 Bytes | dApp origin                       |
+
+### Session
+
+A session ID is created and stored.
+
+- sessionId – uuid v4
+
+### Polling RCR for wallet response
+
+- Before sending the deep link dApp starts polling for wallet response
+
+- RPC endpoint – `getResponses`
+
+  - Request body
+
+    - sessionId
+
+- Polling interval – 1500 ms
+
+- Timeout – No timeout. Polling continues until either a response is returned or the user cancels the request.
+
+### Deep link
+
+The deep link URL contains handshake and request data as query parameters.
+
+**URL:** `radixwallet://connect`
+
+**Query parameters:**
+
+| Key                   | Encoding    | Value                                        |
+| --------------------- | ----------- | -------------------------------------------- |
+| sessionId             | utf-8       | uuid v4                                      |
+| request               | base64url   | request payload (dApp <> wallet interaction) |
+| signature             | hexadecimal | signature                                    |
+| identity              | hexadecimal | ed25519 public key                           |
+| publicKey             | hexadecimal | x25519 public key                            |
+| origin                | utf-8       | dApp origin                                  |
+| dAppDefinitionAddress | utf-8       | radix account address                        |
+
+## 2. Wallet -> Radix Connect Relay
+
+### Derive symmetric encryption key
+
+**Shared secret derivation (Diffie-Hellman key exchange)**
+
+Derived from dApp public key and an x25519 keypair created in the wallet.
+
+A symmetric encryption key is derived from passing the shared secret (Diffie-Hellman) through a key derivation function.
+
+**Key derivation function ([HKDF](https://en.wikipedia.org/wiki/HKDF))**
+
+- input – shared secret
+- hashing algoritm – sha256
+- salt – dApp definition address (included in request)
+- context – RCfM
+- output size – 32 Bytes
+
+**Signature validation**
+
+Provided signature is verified
+
+- constructing message
+
+- dApp identity as public key
+
+**Encrypting response payload**
+
+- Wallet handles the request and produces a wallet interaction response.
+
+- Wallet interaction response is encrypted
+
+**Encryption/Decryption**
+
+- algorithm – [AES-GCM](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/encrypt#aes-gcm)
+- iv – nonce, random generated bytes
+- encryption key – symmetric encryption key
+
+### Send response to RCR
+
+- RPC endpoint – `sendResponse`
+
+| Key       | Encoding    | Value                                                   |
+| --------- | ----------- | ------------------------------------------------------- |
+| sessionId | utf-8       | uuid v4                                                 |
+| data      | hexadecimal | encrypted response payload (dApp <> wallet interaction) |
+| publicKey | hexadecimal | wallet x25519 public key                                |
+
+## 3) RCR → dApp
+
+- Get responses from RCR
+  - sessionId
+  - data
+  - publicKey – wallet x25519 public key
+- Derive symmetric encryption key
+- Decrypt response
+- Resolve wallet interaction request
+  - A request is considered resolved when a request is matched with a response