81625d35d2
- Add AML scope note to Handoff - RN Multichain Probe (sanctions-only vs full KYT) - Add human-blocked section with 3 precise next steps for owner - Create Task 11 Pre-flight Inventory: library choice, dev/prod flow, admin UI gaps, backend gaps, risks, acceptance criteria
188 lines
3.4 KiB
Markdown
188 lines
3.4 KiB
Markdown
---
|
|
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 Request Network checkout, the funds ledger, or the broader Safe/multisig custody roadmap.
|
|
|
|
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.
|