Balanced by asset
Every Transfer must balance its source and destination totals independently for each asset before execution begins.
Back to documentation
Correctness and recovery
Test the ledger invariants, not just the happy path
A balance system must still reconcile after concurrency, an uncertain response, reversal, expiry, and deliberately interrupted work. XferAPI exercises those boundaries and verifies the persisted result.
Verification scope reviewed July 2026. This page describes correctness evidence for the current service design; it does not turn a test environment into a production service commitment.
Implementation properties
What every recovery path must preserve
Account and Record move together
Each account mutation and its durable Record are committed in the same short database transaction.
Intermediate work is explicit
Persisted Processing, Completing, and Reversing states identify the only valid continuation after interrupted work.
Retries keep one identity
Exact retries converge on the caller-owned transfer ID and scene, while a different payload for that pair is rejected.
Automated verification
Exercise the public boundary and the durable state machine
Two complementary suites check the HTTP contract customers call and the persisted accounting behavior that must survive interrupted work.
Public HTTP contract
- The production /v1 router, middleware, Bearer service keys, key scopes, and ledger isolation
- Request parsing, unknown fields, payload limits, pagination, response envelopes, and request IDs
- Transfer creation, exact retries, idempotency conflicts, insufficient balances, and whole-transfer reversal
- Account, batch-balance, Transfer, Record, metadata, quota, rate, and plan-boundary behavior
State-machine fault injection
- Deliberately persisted source, destination, completion, and reversal interruption points
- Concurrent retries, reversal-first tombstones, inspection takeover, and cleanup recovery
- Active, future, expired, and permanent balances at one captured Unix-second boundary
- Overflow, overdraft, expiration recycling, quota metering, and month-boundary transitions
Production lineage
3.5 years of operational reconciliation
XferAPI evolved from a predecessor ledger system that operated in production for 3.5 years. Across the production reconciliation records retained for that system, no reconciliation discrepancy was identified during that period. Its persisted transfer and account records provided a practical trail for routine reconciliation and audit review. This historical operating record describes the predecessor system; it is not a measure of current Hosted-service uptime, an availability commitment, an SLA, independent audit assurance, or proof of a specific recovery objective.
Post-run reconciliation
Inspect the persisted result row by row
A test run is not accepted because aggregate totals look plausible. After concurrent work and recovery settle, the verifier reads the stored State, Record, and Account rows and checks their relationships.
- Every persisted Transfer State reaches an allowed terminal state after recovery settles.
- Each persisted State leg has the expected unique Record, direction, amount, status, asset, action, and account.
- Account balances reconcile with successful and reversed Records, including time-aware batches.
- No conflicting payload becomes a torn winner, and every ledger remains zero-sum independently for each asset.
- A newly completed Transfer is metered once; an exact idempotent retry does not consume another monthly unit.
What this evidence does not claim
These suites provide evidence about ledger invariants and recovery behavior in isolated test environments. They are not a Hosted uptime or latency commitment, a production throughput benchmark, proof of multi-host network partition or database failover, an RPO/RTO statement, or a substitute for terms expressly documented in a service agreement.
Use the integration guide for the caller-side retry contract, or discuss a deployment boundary and service commitments directly.