SafeLedger
A reference design for keeping a synchronous payment path correct and available when the wallet it depends on is slow, down, or shared with legacy debiters.
A till calls Transaction Service, and Transaction Service needs Wallet Service to approve or decline. The design has two phases:
| Phase 1 (now, existing API) | Phase 2 (long term, proposed API) | |
|---|---|---|
| Decision | Funds-checked debit is the authorisation | Atomic hold is the authorisation |
| Settlement | Already settled | Asynchronous capture |
| Cancel | Compensating credit | Release |
| Wallet down | Fast retryable decline (stand-in available, off) | same |
| Switch | — | Account-cohort rollout with kill switch |
Start here:
- Problem statement: the race, the outage, and the constraints
- PRD: requirements, assumptions, and the questions log (no open questions)
- Architecture: sequences, state machine, resilience numbers
- ADRs: the decisions and their alternatives
- Roadmap: milestones, dependency graph, and links to the task issues
- API: Transaction v1 · Wallet v1 · Wallet v2 proposal