Document payment verification and trezor safekeeping

2026-05-24 11:12:17 +04:00
parent 1a2b9f1f5d
commit b824ca0435
7 changed files with 569 additions and 54 deletions
--- a/Reference/Trezor
+++ b/Reference/Trezor
@@ -0,0 +1,187 @@
+---
+title: Trezor API
+tags: [api, payments, trezor, safekeeping]
+---
+
+# Trezor API
+
+The Trezor API is mounted at `/api/trezor`. It is optional support for hardware-backed safekeeping and does not replace SHKeeper or Request Network.
+
+Enforcement is controlled by:
+
+```env
+TREZOR_SAFEKEEPING_REQUIRED=false
+```
+
+Only the literal value `true` makes Trezor proof mandatory during release/refund confirmation. When unset or `false`, release/refund flows continue without Trezor proof.
+
+## GET /api/trezor/registration-message
+
+Builds the exact message the user must sign to register a Trezor xpub.
+
+Auth: bearer JWT
+
+Query:
+
+```text
+xpub=<extended public key>
+registrationAddress=<first derived address>
+```
+
+Response:
+
+```json
+{
+  "success": true,
+  "data": {
+    "message": "Amanat escrow Trezor registration\n..."
+  }
+}
+```
+
+## POST /api/trezor/register
+
+Registers a Trezor xpub after the first derived address signs the registration challenge.
+
+Auth: bearer JWT
+
+Body:
+
+```json
+{
+  "xpub": "xpub...",
+  "registrationAddress": "0x...",
+  "proofMessage": "Amanat escrow Trezor registration\n...",
+  "proofSignature": "0x...",
+  "basePath": "m/44'/60'/0'",
+  "deviceLabel": "Office Trezor"
+}
+```
+
+Validation:
+
+- Rejects private extended keys (`xprv`, `tprv`).
+- Requires `registrationAddress` to equal xpub-derived `m/44'/60'/0'/0/0`.
+- Requires `proofSignature` to recover `registrationAddress`.
+
+Response:
+
+```json
+{
+  "success": true,
+  "data": {
+    "xpubFingerprint": "0x...",
+    "registrationAddress": "0x...",
+    "basePath": "m/44'/60'/0'",
+    "nextAddressIndex": 1
+  }
+}
+```
+
+## GET /api/trezor/account
+
+Returns the caller's active Trezor registration summary.
+
+Auth: bearer JWT
+
+Response when absent:
+
+```json
+{
+  "success": true,
+  "data": {
+    "registered": false
+  }
+}
+```
+
+## POST /api/trezor/addresses/next
+
+Allocates or returns a deterministic receive address from the registered xpub.
+
+Auth: bearer JWT
+
+Body:
+
+```json
+{
+  "purpose": "deposit",
+  "paymentId": "..."
+}
+```
+
+If `paymentId` already has an assigned address, the same address is returned. Otherwise the backend derives:
+
+```text
+m/44'/60'/0'/0/{nextAddressIndex}
+```
+
+## POST /api/trezor/operation-message
+
+Builds the exact transaction-intent message an admin must sign when Trezor safekeeping is enabled.
+
+Auth: bearer JWT, admin
+
+Body:
+
+```json
+{
+  "operation": "release",
+  "paymentId": "...",
+  "transactionHash": "0x...",
+  "amount": 100,
+  "currency": "USDT",
+  "provider": "request.network"
+}
+```
+
+Response:
+
+```json
+{
+  "success": true,
+  "data": {
+    "message": "Amanat escrow Trezor transaction approval\n..."
+  }
+}
+```
+
+## POST /api/trezor/verify-operation
+
+Verifies a signed operation intent against the admin's registered Trezor safekeeping address.
+
+Auth: bearer JWT, admin
+
+Body:
+
+```json
+{
+  "payload": {
+    "operation": "release",
+    "paymentId": "...",
+    "transactionHash": "0x...",
+    "amount": 100,
+    "currency": "USDT",
+    "provider": "request.network"
+  },
+  "message": "Amanat escrow Trezor transaction approval\n...",
+  "signature": "0x..."
+}
+```
+
+## Release / Refund Integration
+
+When `TREZOR_SAFEKEEPING_REQUIRED=true`, release/refund confirmation bodies must include the Trezor proof:
+
+```json
+{
+  "txHash": "0x...",
+  "amount": 100,
+  "trezor": {
+    "message": "Amanat escrow Trezor transaction approval\n...",
+    "signature": "0x..."
+  }
+}
+```
+
+This proof is optional when enforcement is disabled.