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

Consider the following accounts referenced throughout the below documentation:

• USD Settlement Acc. - USD asset settlement account (always zero or negative balance)
• USD (Asset) Liquidity Acc. - USD settlement account (always zero or positive balance)
• Peer Liquidity Acc. - USD asset counterparty liquidity account (always zero or positive balance)
• Wallet Address Liquidity Acc. - USD wallet address liquidity account (always zero or positive balance)
• Incoming Payment Liquidity Acc. - USD incoming payment liquidity account (always zero or positive balance)
• Outgoing Payment Liquidity Acc. - USD outgoing payment liquidity account (always zero or positive balance)

Deposits

Action of debiting the settlement account, and crediting the liquidity account.

Depositing Asset Liquidity

Debit Account	Credit Account
Settlement	Asset Liquidity

• Example: depositing 100 USD

USD Settlement Acc.	USD (Asset) Liquidity Acc.
Debit Credit 100	Debit Credit 100

Depositing Peer Liquidity

Debit Account	Credit Account
Settlement	Peer Liquidity

• Example: peering relationship in USD, depositing 100 USD

USD Settlement Acc.	Peer Liquidity Acc.
Debit Credit 100	Debit Credit 100

Depositing Outgoing Payment Liquidity

Debit Account	Credit Account
Settlement	Outgoing Payment

• Example: depositing 35 USD

USD Settlement Acc.	Outgoing Payment Liquidity Acc.
Debit Credit 35	Debit Credit 35

Withdrawals

Action of debiting the liquidity account, and crediting the settlement account.

Withdrawing Asset Liquidity

Debit Account	Credit Account
Asset Liquidity	Settlement

• Example: withdrawing 50 USD

USD (Asset) Liquidity Acc.	USD Settlement Acc.
Debit Credit 50	Debit Credit 50

Withdrawing Peer Liquidity

Debit Account	Credit Account
Peer Liquidity	Settlement

• Example: peering relationship in USD, withdrawing 50 USD

Peer Liquidity Acc.	USD Settlement Acc.
Debit Credit 50	Debit Credit 50

Withdrawing Wallet Address Liquidity (example: 2 USD)

Debit Account	Credit Account
Wallet Address	Settlement

• Example: withdrawing 2 USD

Wallet Address Liquidity Acc.	USD Settlement Acc.
Debit Credit 2	Debit Credit 2

Withdrawing Incoming Payment Liquidity

Debit Account	Credit Account
Incoming Payment	Settlement

• Example: withdrawing 25 USD

Incoming Payment Liquidity Acc.	USD Settlement Acc.
Debit Credit 25	Debit Credit 25

Withdrawing Outgoing Payment Liquidity

Debit Account	Credit Account
Outgoing Payment	Settlement

• Example: withdrawing 1 USD

Outgoing Payment Liquidity Acc.	USD Settlement Acc.
Debit Credit 1	Debit Credit 1

Payments (Same Asset)

Simple Payment Setup Protocol (SPSP) / Web Monetization

Debit Account	Credit Account
Outgoing Payment	Wallet Address

• Example: Send a Web Monetization 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.
Debit Credit 2	Debit Credit 2

Send Amount < Receive Amount

Debit Account	Credit Account
Outgoing Payment	Incoming Payment
Asset Liquidity	Incoming 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.
Debit Credit 14	Debit Credit 1	Debit Credit 15

Send Amount > Receive Amount

Debit Account	Credit Account
Outgoing Payment	Incoming Payment
Outgoing Payment	Asset 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.
Debit Credit 15	Debit Credit 1	Debit Credit 14

Payments (Cross Currency)

Debit Account	Credit Account	Asset
Outgoing Payment	Asset Liquidity	ABC
Asset Liquidity	Incoming Payment	XYZ

• Example: Outgoing payment for 10 USD, incoming payment receives 9 EUR.

Outgoing Payment Liquidity Acc.	USD (Asset) Liquidity Acc.
Debit Credit 10	Debit Credit 10
EUR (Asset) Liquidity Acc.	Incoming Payment Liquidity Acc.
Debit Credit 9	Debit Credit 9

SPSP / Web Monetization

Debit Account	Credit Account	Asset
Outgoing Payment	Asset Liquidity	ABC
Asset Liquidity	Wallet Address	XYZ

• Example: Outgoing payment for 2 USD, wallet address receives 1 EUR.

Outgoing Payment Liquidity Acc.	USD (Asset) Liquidity Acc.
Debit Credit 2	Debit Credit 2
EUR (Asset) Liquidity Acc.	Wallet Address Liquidity Acc.
Debit Credit 1	Debit Credit 1

Interledger

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

Sending Connector

Same asset

Debit Account	Credit Account
Outgoing Payment	Peer 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.
Debit Credit 100	Debit Credit 100

Cross currency

Debit Account	Credit Account	Asset
Outgoing Payment	Asset Liquidity	ABC
Asset Liquidity	Peer Liquidity	XYZ

• 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.
Debit Credit 100	Debit Credit 100
EUR (Asset) Liquidity Acc.	Peer Liquidity Acc.
Debit Credit 90	Debit Credit 90

Receiving Connector

Same asset

Debit Account	Credit Account
Peer Liquidity	Incoming 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.
Debit Credit 100	Debit Credit 100

SPSP / Web Monetization

Debit Account	Credit Account
Peer Liquidity	Wallet Address

• Example: A wallet address receives 2 USD from an ILP payment at a peer’s Rafiki instance.

Peer Liquidity Acc.	Wallet Address Liquidity Acc.
Debit Credit 2	Debit Credit 2

Cross currency

Debit Account	Credit Account	Asset
Peer Liquidity	Asset Liquidity	ABC
Asset Liquidity	Incoming Payment	XYZ

• 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.
Debit Credit 10	Debit Credit 10
EUR (Asset) Liquidity Acc.	Incoming Payment Liquidity Acc.
Debit Credit 9	Debit Credit 9

SPSP / Web Monetization

Debit Account	Credit Account	Asset
Peer Liquidity	Asset Liquidity	ABC
Asset Liquidity	Wallet Address	XYZ

• 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.
Debit Credit 2	Debit Credit 2
EUR (Asset) Liquidity Acc.	Wallet Address Liquidity Acc.
Debit Credit 1	Debit Credit 1

Connector

Same asset

Debit Account	Credit Account
Peer Liquidity	Peer Liquidity

• Example: Rafiki forwards 10 USD from peer A to peer B.

Peer A Liquidity Acc.	Peer B Liquidity Acc.
Debit Credit 10	Debit Credit 10

Cross currency

Debit Account	Credit Account	Asset
Peer Liquidity	Asset Liquidity	ABC
Asset Liquidity	Peer Liquidity	XYZ

• Example: Rafiki receives 100 USD from peer A and forwards 90 EUR to peer B.

Peer A Liquidity Acc.	USD (Asset) Liquidity Acc.
Debit Credit 100	Debit Credit 100
EUR (Asset) Liquidity Acc.	Peer B Liquidity Acc.
Debit Credit 90	Debit Credit 90