SECURITY
Integrate defensively.
PBE nodes return JSON errors and enforce protocol limits, but application security still belongs to the wallet, merchant backend and node operator.
Error shape
JSON
{"ok":false,"error":"Human-readable reason"}Do not make business decisions from the text of an error. Treat non-2xx HTTP responses or ok:false as failure and log the request context without secrets.
Important limits
| Item | Limit / rule |
|---|---|
| Transaction format | v2 only |
| Transaction type | Transfer (type 1) only |
| Transaction maximum | 65,536 bytes |
| Payment reference | 64 bytes; A-Z, a-z, 0-9, dot, underscore, colon, hyphen |
| PBE precision | 8 decimal places |
| Payment confirmation target | 1-1000; default 12 |
| Webhook callback URL | 1024 bytes; HTTPS by default |
| Webhook TTL | 60 seconds to configured maximum; hard maximum 7 days |
| Address history limit | 1-100 rows |
| P2P block batch | 1-16 blocks |
Wallet security
- Private keys and wallet passwords stay client-side.
- Use HTTPS and a strict Content Security Policy on wallet origins.
- Do not load untrusted third-party JavaScript into the wallet.
- Verify the recipient and amount shown by the wallet before signing.
- Back up encrypted browser wallets before clearing browser storage.
Node security
- Never ship node keys, producer keys, operator bindings, setup tokens, database credentials, webhook tokens or signing secrets in public packages.
- Expose only the interfaces you intend. Standalone port 8024 is localhost-only; public peer traffic uses 8025.
- Keep webhook management disabled unless the node is deliberately acting for a merchant.
- Rate-limit public write-heavy P2P endpoints at the reverse proxy or firewall. Candidate block validation includes memory-hard participation verification and should not be exposed to unlimited request floods.
- Rotate credentials if they have been copied into logs, support bundles or source archives.
Commerce security
- Store the expected reference, recipient and amount before asking the customer to pay.
- Verify all three values server-side before fulfilment.
- Make fulfilment idempotent; webhooks are delivered at least once.
- Verify webhook HMAC over the exact raw body and reject stale timestamps.
- Do not interpret confirmation depth as hard finality.
0.0.1 settlement modelhardFinality=false. PBE 0.0.1 uses deterministic fork choice and canonical confirmation depth. Deep alternate histories and long partitions remain protocol risks, particularly for a newly syncing node. Treat 0.0.1 as an experimental mainnet release and avoid high-value irreversible settlement until stronger finality/checkpoint policy has been designed and reviewed.