Manage liquidity

As an implementation of the Interledger Protocol, Rafiki provides accounting between transacting parties but doesn’t handle settlement. You and the account servicing entities you decide to peer with must agree on the means and how often you will settle your accounts. Consequently, Rafiki can manage the liquidity used to fund payments made through the Interledger network.

As Rafiki supports several types of liquidity, we’ll cover the typical scenarios you’ll need to manage.

Note

You must provide the idempotencyKey when calling mutations related to liquidity. This key allows the safe retrying of requests without multiple operations. It should be a unique key, typically a V4 UUID. For more information, refer to Rafiki’s idempotency.

Asset Liquidity

Asset liquidity specifies the amount of value denominated in an asset you have previously added to your Rafiki instance, which Rafiki has at its disposal to send or forward Interledger packets. Asset liquidity increases if packets denominated in the asset are received and decreases if your Rafiki instance sends packets denominated in the asset. The amount is always non-negative.

You should define and adjust the asset liquidity based on your risk tolerance.

Deposit asset liquidity using the DepositAssetLiquidity mutation

DepositAssetLiquidity mutation

mutation DepositAssetLiquidity($input: DepositAssetLiquidityInput!) {
  depositAssetLiquidity(input: $input) {
    code
    success
    message
    error
  }
}

Example

Example input

{
  "input": {
    "id": "b97fd85a-126e-42ef-b40d-1a50a70ffa6f",
    "assetId": "7b8b0f65-896d-4403-b7ba-2e24bf20eb35",
    "amount": "100",
    "idempotencyKey": "b97fd85a-126e-42ef-b40d-1a50a70ffa6f"
  }
}

Variable	Description
assetID	The id of the asset to deposit liquidity into
amount	Amount of liquidity to deposit
id	The id of the transfer (deposit)
idempotencyKey	Unique key to ensure duplicate or retried requests are processed only once

If the asset liquidity deposit was successful, DepositAssetLiquidity returns true.

Withdraw asset liquidity using the CreateAssetLiquidityWithdrawal mutation

CreateAssetLiquidityWithdrawal mutation

mutation CreateAssetLiquidityWithdrawal(
  $input: CreateAssetLiquidityWithdrawalInput!
) {
  createAssetLiquidityWithdrawal(input: $input) {
    code
    success
    message
    error
  }
}

Example

Example input

{
  "input": {
    "id": "b97fd85a-126e-42ef-b40d-1a50a70ffa6f",
    "assetId": "7b8b0f65-896d-4403-b7ba-2e24bf20eb35",
    "amount": "100",
    "idempotencyKey": "b97fd85a-126e-42ef-b40d-1a50a70ffa6f",
    "timeoutSeconds": 0
  }
}

Variable	Description
id	The id of the transfer (withdrawal)
assetId	The id of the asset to withdraw liquidity from
amount	Amount of liquidity to withdraw
idempotencyKey	Unique key to ensure duplicate or retried requests are processed only once
timeoutSeconds	Interval, in seconds, after a pending transfer is initiated at which it can be posted or voided (zero denotes a no timeout, single-phase posted transfer)

If the asset liquidity withdrawal was successful, CreateAssetLiquidityWithdrawal returns true.

Deposit and withdraw asset liquidity using Rafiki Admin

Asset liquidity can also be added through the Rafiki Admin application. Navigate to the liquidity information section on the main Assets page and then select deposit or withdraw liquidity.

Peer Liquidity

Peer liquidity is the line of credit denominated in the asset of the peering relationship in Rafiki that you extend to your respective peer. You must determine how much credit you will extend in your peering agreement, which depends on how much you trust the peer. If peer liquidity is insufficient, Rafiki cannot initiate payments to that peer. Once peer liquidity is used up, you should settle with your peer and reset their peer liquidity.

Note

You must decide whether to secure liquidity with your peers by extending credit or requiring them to pre-fund your accounts. Those agreements must be made before setting up peering relationships in Rafiki and are not managed through Interledger or Rafiki.

Deposit peer liquidity using the DepositPeerLiquidity mutation

DepositPeerLiquidity mutation

mutation DepositPeerLiquidity($input: DepositPeerLiquidityInput!) {
  depositPeerLiquidity(input: $input) {
    code
    success
    message
    error
  }
}

Example

Example input

{
  "input": {
    "id": "a09b730d-8610-4fda-98fa-ec7acb19c775",
    "peerId": "73158598-2e0c-4973-895e-aebd115af260",
    "amount": "1000000",
    "idempotencyKey": "a09b730d-8610-4fda-98fa-ec7acb19c775"
  }
}

Variable	Description
id	The id of the transfer (deposit)
peerId	The id of the peer to deposit liquidity into
amount	Amount of liquidity to deposit
idempotencyKey	Unique key to ensure duplicate or retried requests are processed only once

If the peer liquidity deposit was successful, DepositPeerLiquidity returns true.

Withdraw peer liquidity using the CreatePeerLiquidityWithdrawal mutation

CreatePeerLiquidityWithdrawal mutation

mutation CreatePeerLiquidityWithdrawal(
  $input: CreatePeerLiquidityWithdrawalInput!
) {
  createPeerLiquidityWithdrawal(input: $input) {
    code
    success
    message
    error
  }
}

Example

Example input

{
  "input": {
    "id": "421fae87-9a59-4217-9ff8-faf55ffab9c6",
    "peerId": "73158598-2e0c-4973-895e-aebd115af260",
    "amount": "100",
    "idempotencyKey": "b97fd85a-126e-42ef-b40d-1a50a70ffa6f",
    "timeoutSeconds": 0
  }
}

Variable	Description
id	The id of the transfer (withdrawal)
peerId	The id of the peer to withdraw liquidity from
amount	Amount of liquidity to withdraw
idempotencyKey	Unique key to ensure duplicate or retried requests are processed only once
timeoutSeconds	Interval, in seconds, after a pending transfer is initiated at which it can be posted or voided (zero denotes a no timeout, single-phase posted transfer)

If the peer liquidity withdrawal was successful, CreatePeerLiquidityWithdrawal returns true.

Deposit and withdraw peer liquidity using Rafiki Admin

Peer liquidity can also be added through the Rafiki Admin application. Navigate to the liquidity information section on the main Peers page and then select deposit or withdraw liquidity.

Payment Liquidity

When Open Payments incoming or outgoing payments are created, your Rafiki instance creates a liquidity account within the accounting database. Liquidity must be deposited into an outgoing payment before the payment can be processed. Rafiki will notify you to deposit liquidity via the outgoing_payment.created webhook event. Similarly, packets received for an incoming payment increase its liquidity account. Rafiki will notify you to withdraw that liquidity via the incoming_payment.completed webhook event.

Withdraw incoming payment liquidity using the CreateIncomingPaymentWithdrawal mutation

CreateIncomingPaymentWithdrawal mutation

mutation CreateIncomingPaymentWithdrawal(
  $input: CreateIncomingPaymentWithdrawalInput!
) {
  createIncomingPaymentWithdrawal(input: $input) {
    code
    error
    message
    success
  }
}

Example

Example input

{
  "input": {
    "incomingPaymentId": "b4f85d5c-652d-472d-873c-4ba2a5e39052",
    "idempotencyKey": "a09b730d-8610-4fda-98fa-ec7acb19c775",
    "timeoutSeconds": 0
  }
}

Variable	Description
incomingPaymentId	The id of the incoming payment to withdraw from
idempotencyKey	Unique key to ensure duplicate or retried requests are processed only once
timeoutSeconds	Interval, in seconds, after a pending transfer is initiated at which it can be posted or voided (zero denotes a no timeout, single-phase posted transfer)

If the incoming payment liquidity withdrawal was successful, CreateIncomingPaymentWithdrawal returns true.

Deposit outgoing payment liquidity using the DepositOutgoingPaymentLiquidity mutation

DepositOutgoingPaymentLiquidity mutation

mutation DepositOutgoingPaymentLiquidity(
  $input: DepositOutgoingPaymentLiquidityInput!
) {
  depositOutgoingPaymentLiquidity(input: $input) {
    code
    error
    message
    success
  }
}

Example

Example input

{
  "input": {
    "outgoingPaymentId": "b4f85d5c-652d-472d-873c-4ba2a5e39052",
    "idempotencyKey": "a09b730d-8610-4fda-98fa-ec7acb19c775"
  }
}

Variable	Description
outgoingPaymentId	The id of the outgoing payment to deposit into
idempotencyKey	Unique key to ensure duplicate or retried requests are processed only once

If the outgoing payment liquidity deposit was successful, DepositOutgoingPaymentLiquidity returns true.

Withdraw outgoing payment liquidity using the CreateOutgoingPaymentWithdrawal mutation

CreateOutgoingPaymentWithdrawal mutation

mutation CreateOutgoingPaymentWithdrawal(
  $input: CreateOutgoingPaymentWithdrawalInput!
) {
  createOutgoingPaymentWithdrawal(input: $input) {
    code
    error
    message
    success
  }
}

Example

Example input

{
  "input": {
    "outgoingPaymentId": "b4f85d5c-652d-472d-873c-4ba2a5e39052",
    "idempotencyKey": "a09b730d-8610-4fda-98fa-ec7acb19c775",
    "timeoutSeconds": 0
  }
}

Variable	Description
outgoingPaymentId	The id of the outgoing payment to withdraw from
idempotencyKey	Unique key to ensure duplicate or retried requests are processed only once
timeoutSeconds	Interval, in seconds, after a pending transfer is initiated at which it can be posted or voided (zero denotes a no timeout, single-phase posted transfer)

If the outgoing payment liquidity withdrawal was successful, CreateOutgoingPaymentWithdrawal returns true.

Two-phase withdrawals

Rafiki supports two-phase withdrawals via the PostLiquidityWithdrawal and VoidLiquidityWithdrawal mutations. When a withdrawal liquidity transaction is requested with a non-zero timeout value (zero denotes absence of a timeout), the transfer will be created as a two-phase transfer. If the timeout interval passes before the transfer is either posted or voided, the transfer expires and the full amount is returned to the original account.

• PostLiquidityWithdrawal: Withdrawals with timeouts greater than 0 are processed as two-phase transfers and committed via this mutation.

• VoidLiquidityWithdrawal: Withdrawals with timeouts greater than 0 are processed as two-phase transfers and are rolled back via this mutation.

The following withdrawal transactions supports two-phase transfers:

• Asset liquidity withdrawal
• Wallet address withdrawal
• Peer liquidity withdrawal
• Incoming payment withdrawal
• Outgoing payment withdrawal

Post and commit a sucessful transfer using the PostLiquidityWithdrawal mutation

PostLiquidityWithdrawal mutation

mutation PostLiquidityWithdrawal($input: PostLiquidityWithdrawalInput!) {
  postLiquidityWithdrawal(input: $input) {
    code
    error
    message
    success
  }
}

Example

Example input

{
  "input": {
    "withdrawalId": "b4f85d5c-652d-472d-873c-4ba2a5e39052",
    "idempotencyKey": "a09b730d-8610-4fda-98fa-ec7acb19c775"
  }
}

Variable	Description
withdrawalId	The id of the liquidity withdrawal to post
idempotencyKey	Unique key to ensure duplicate or retried requests are processed only once

If the liquidity withdrawal was successfully posted, PostLiquidityWithdrawal returns true.

Void and rollback an unsuccessful transfer using the VoidLiquidityWithdrawal mutation

VoidLiquidityWithdrawal mutation

mutation VoidLiquidityWithdrawal($input: VoidLiquidityWithdrawalInput!) {
  voidLiquidityWithdrawal(input: $input) {
    code
    error
    message
    success
  }
}

Example

Example input

{
  "input": {
    "withdrawalId": "b4f85d5c-652d-472d-873c-4ba2a5e39052",
    "idempotencyKey": "a09b730d-8610-4fda-98fa-ec7acb19c775"
  }
}

Variable	Description
withdrawalId	The id of the liquidity withdrawal to void
idempotencyKey	Unique key to ensure duplicate or retried requests are processed only once

If the liquidity withdrawal was successfully voided and rolled back, VoidLiquidityWithdrawal returns true.