Skip to content
GitHub

Accounts and Transfers

Accounts

Rafiki uses a combination of liquidity and settlement accounts to perform double-entry accounting.

Liquidity account

A liquidity account may only hold a positive balance. Rafiki enforces that its total debits MUST NOT exceed its total credits amount.

There is one liquidity account for each of the following resource:

  • Asset
  • Peer
  • Wallet Address (for SPSP / Web Monetization receiving)
  • Incoming Payment
  • Outgoing Payment

Asset and Peer liquidity accounts are created when calling createAsset and createPeer GraphQL Admin API mutations respectively, while liquidity accounts for wallet addresses, incoming and outgoing payments are created on-the-fly during payment processing or web monetization events.

Any liquidity management is done by the Account Servicing Entity through the GraphQL Admin API. See webhook events and liquidity documentation for more information.

Settlement account

A settlement account may only hold a negative balance. Rafiki enforces that its total credits MUST NOT exceed its total debits amount. A settlement account represents those total amount of funds an Account Servicing Entity has deposited into Rafiki.

There is one settlement account for each asset.

Transfers

Rafiki transfers perform double-entry accounting. Every transfer increases both the total debits of one account and the total credits of a second account by the same amount.

Intra-Rafiki

Deposits

Depositing Asset Liquidity
Debit AccountCredit Account
SettlementAsset Liquidity
  • Example: depositing 100 USD
USD Settlement Acc. USD (Asset) Liquidity Acc.
DebitCredit
100
DebitCredit
100
Depositing Peer Liquidity
Debit AccountCredit Account
SettlementPeer Liquidity
  • Example: peering relationship in USD, depositing 100 USD
USD Settlement Acc. Peer Liquidity Acc.
DebitCredit
100
DebitCredit
100
Depositing Outgoing Payment Liquidity
Debit AccountCredit Account
SettlementOutgoing Payment
  • Example: depositing 35 USD
USD Settlement Acc. Outgoing Payment Liquidity Acc.
DebitCredit
35
DebitCredit
35

Withdrawals

Withdrawing Asset Liquidity
Debit AccountCredit Account
Asset LiquiditySettlement
  • Example: withdrawing 50 USD
USD Settlement Acc. USD (Asset) Liquidity Acc.
DebitCredit
50
DebitCredit
50
Withdrawing Peer Liquidity
Debit AccountCredit Account
Peer LiquiditySettlement
  • Example: peering relationship in USD, withdrawing 50 USD
USD Settlement Acc. Peer Liquidity Acc.
DebitCredit
50
DebitCredit
50
Withdrawing Wallet Address Liquidity (example: 2 USD)
Debit AccountCredit Account
Wallet AddressSettlement
  • Example: withdrawing 2 USD
USD Settlement Acc. Wallet Address Liquidity Acc.
DebitCredit
2
DebitCredit
2
Withdrawing Incoming Payment Liquidity
Debit AccountCredit Account
Incoming PaymentSettlement
  • Example: withdrawing 25 USD
USD Settlement Acc. Incoming Payment Liquidity Acc.
DebitCredit
25
DebitCredit
25
Withdrawing Outgoing Payment Liquidity
Debit AccountCredit Account
Outgoing PaymentSettlement
  • Example: withdrawing 1 USD
USD Settlement Acc. Outgoing Payment Liquidity Acc.
DebitCredit
1
DebitCredit
1

Payments (Same Asset)

SPSP / Web Monetization
Debit AccountCredit Account
Outgoing PaymentWallet Address
  • Example: Send a WM Payment of 2 USD over SPSP to a wallet address. Sender and receiver have wallet addresses at the same Rafiki.
Outgoing Payment Liquidity Acc. Wallet Address Liquidity Acc.
DebitCredit
2
DebitCredit
2
Send Amount < Receive Amount
Debit AccountCredit Account
Outgoing PaymentIncoming Payment
Asset LiquidityIncoming Payment
  • Example: Sender consented to a payment of 14 USD but quote promised to deliver 15 USD.
Outgoing Payment Liquidity Acc. USD (Asset) Liquidity Acc. Incoming Payment Liquidity Acc.
DebitCredit
14
DebitCredit
1
DebitCredit
15
Send Amount > Receive Amount
Debit AccountCredit Account
Outgoing PaymentIncoming Payment
Outgoing PaymentAsset Liquidity
  • Example: Sender consented to a payment of 15 USD but quote promised to deliver 14 USD.
Outgoing Payment Liquidity Acc. USD (Asset) Liquidity Acc. Incoming Payment Liquidity Acc.
DebitCredit
15
DebitCredit
1
DebitCredit
14

Payments (Cross Currency)

Debit AccountCredit AccountAsset
Outgoing PaymentAsset LiquidityABC
Asset LiquidityIncoming PaymentXYZ
  • Example: Outgoing payment for 10 USD, incoming payment receives 9 EUR.
Outgoing Payment Liquidity Acc. USD (Asset) Liquidity Acc.
DebitCredit
10
DebitCredit
10
EUR (Asset) Liquidity Acc. Incoming Payment Liquidity Acc.
DebitCredit
9
DebitCredit
9
SPSP / Web Monetization
Debit AccountCredit AccountAsset
Outgoing PaymentAsset LiquidityABC
Asset LiquidityWallet AddressXYZ
  • Example: Outgoing payment for 2 USD, wallet address receives 1 EUR.
Outgoing Payment Liquidity Acc. USD (Asset) Liquidity Acc.
DebitCredit
2
DebitCredit
2
EUR (Asset) Liquidity Acc. Wallet Address Liquidity Acc.
DebitCredit
1
DebitCredit
1

Interledger

Sender and receiver do not have wallet addresses at the same Rafiki instance.

Sending Connector

Same asset
Debit AccountCredit Account
Outgoing PaymentPeer Liquidity
  • Example: Sender creates an outgoing payment for 100 USD to an incoming payment at a peer’s Rafiki instance. The peering relationship is in USD.
Outgoing Payment Liquidity Acc. Peer Liquidity Acc.
DebitCredit
100
DebitCredit
100
Cross currency
Debit AccountCredit AccountAsset
Outgoing PaymentAsset LiquidityABC
Asset LiquidityPeer LiquidityXYZ
  • Example: Sender creates an outgoing payment for 100 USD to an incoming payment at a peer’s Rafiki instance. The peering relationship is in EUR, so payment is converted on the sending side.
Outgoing Payment Liquidity Acc. USD (Asset) Liquidity Acc.
DebitCredit
100
DebitCredit
100
EUR (Asset) Liquidity Acc. Peer Liquidity Acc.
DebitCredit
90
DebitCredit
90

Receiving Connector

Same asset
Debit AccountCredit Account
Peer LiquidityIncoming Payment
  • Example: An incoming payment receives 100 USD from an outgoing payment at a peer’s Rafiki instance.
Peer Liquidity Acc. Incoming Payment Liquidity Acc.
DebitCredit
100
DebitCredit
100
SPSP / Web Monetization
Debit AccountCredit Account
Peer LiquidityWallet Address
  • Example: A wallet address receives 2 USD from an outgoing payment at a peer’s Rafiki instance.
Peer Liquidity Acc. Wallet Address Liquidity Acc.
DebitCredit
2
DebitCredit
2
Cross currency
Debit AccountCredit AccountAsset
Peer LiquidityAsset LiquidityABC
Asset LiquidityIncoming PaymentXYZ
  • Example: A Rafiki instance receives 10 USD from a peer (peering relationship in USD) to be deposited in an incoming payment liquidity account denominated in EUR. The payment is converted to EUR and deposited.
Peer Liquidity Acc. USD (Asset) Liquidity Acc.
DebitCredit
10
DebitCredit
10
EUR (Asset) Liquidity Acc. Incoming Payment Liquidity Acc.
DebitCredit
9
DebitCredit
9
SPSP / Web Monetization
Debit AccountCredit AccountAsset
Peer LiquidityAsset LiquidityABC
Asset LiquidityWallet AddressXYZ
  • Example: A Rafiki instance receives 10 USD from a peer (peering relationship in USD) to be deposited in a wallet address liquidity account denominated in EUR. The payment is converted to EUR and deposited.
Peer Liquidity Acc. USD (Asset) Liquidity Acc.
DebitCredit
2
DebitCredit
2
EUR (Asset) Liquidity Acc. Wallet Address Liquidity Acc.
DebitCredit
1
DebitCredit
1

Connector

Same asset
Debit AccountCredit Account
Peer LiquidityPeer Liquidity
  • Example: Rafiki forwards 10 USD from peer A to peer B.
Peer A Liquidity Acc. Peer B Liquidity Acc.
DebitCredit
10
DebitCredit
10
Cross currency
Debit AccountCredit AccountAsset
Peer LiquidityAsset LiquidityABC
Asset LiquidityPeer LiquidityXYZ
  • Example: Rafiki receives 100 USD from peer A and forwards 90 EUR to peer B.
Peer A Liquidity Acc. USD (Asset) Liquidity Acc.
DebitCredit
100
DebitCredit
100
EUR (Asset) Liquidity Acc. Peer B Liquidity Acc.
DebitCredit
90
DebitCredit
90