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.
Peer endpoint safetyPublic peer hints are treated as untrusted. PBE pins resolved public DNS addresses for outbound P2P requests, refuses redirects, caps responses at 64 MiB, and does not accept private peer hints unless the node operator explicitly enables network.allowPrivatePeers.