Entity & Account Relationships in Rafiki Accounting
Rafiki operates on a strict separation between external customer-servicing ledgers (bank cores, digital wallets, fintech backends) and internal liquidity tracking ledgers (powered by TigerBeetle or PostgreSQL). Explore the relationship topology and operational walkthroughs below.
Instance Isolation & Double-Entry Ledger Structure
Account Servicing Entities (Sender & Recipient): Each entity (wallet provider, bank, or fintech) hosts its own independent Rafiki deployment.
Core Ledger vs. Rafiki Ledger: Customer accounts (end-user balances) reside on the entity's core banking/wallet ledger. Rafiki never manages customer bank accounts directly; it only tracks internal liquidity to clear and forward Interledger (ILP) packets.
Every deposit into a liquidity account is automatically offset by an equal credit to the Settlement Account. This ensures that across the Rafiki accounting instance, the sum of all debits strictly equals the sum of all credits at all times.
Account Categories & Invariable Rules
| Account Type | Main Purpose | Scope / Count | Balance Constraint |
|---|---|---|---|
| Asset Liquidity | Supports FX / cross-currency packet forwarding. | 1 per transacted asset | ≥ 0 (Zero or Positive) |
| Peer Liquidity | Tracks available credit line extended to an agreed peer. | 1 per peer relationship | ≥ 0 (Zero or Positive) |
| Outgoing Payment Liquidity | Funds reserved to dispatch an Open Payments transaction. | 1 per outgoing payment | ≥ 0 (Zero or Positive) |
| Incoming Payment Liquidity | Holds value received from completed Open Payments. | 1 per incoming payment | ≥ 0 (Zero or Positive) |
| Wallet Address Liquidity | Holds value received via SPSP payments. | 1 per wallet address (reused) | ≥ 0 (Zero or Positive) |
| Settlement Account | Tracks net funds deposited into Rafiki vs. withdrawn. | 1 per transacted asset | ≤ 0 (Zero or Negative) |
3. Allowed Operations Matrix
- Asset Liquidity: Pre-funded to absorb cross-currency fluctuations and conversion requirements.
- Peer Liquidity: Injected to establish or reset a peer's credit line after an external settlement.
- Outgoing Payment Liquidity: Explicitly deposited from the core sender balance before dispatching an outgoing payment.
- Asset & Peer Liquidity: Withdrawn for rebalancing or reducing extended credit/capital.
- Incoming Payment Liquidity: Withdrawn upon payment completion to credit the recipient core balance.
- Wallet Address Liquidity: Withdrawn upon SPSP payment completion to credit the recipient.
- Outgoing Payment Liquidity: Refunded if a payment fails or partially completes.
- Inter-Instance Routing: Interledger packets route value across instances between Peer Liquidity Accounts according to established bilateral credit limits.
- Intra-Instance Transfers: Multi-phase double-entry transfers move value between Payment Liquidity and Asset Liquidity Accounts when FX applies.
