From ae0c9bd9ed41997d33766c2ece4a850e01cdeb32 Mon Sep 17 00:00:00 2001
From: Melissa Henderson <57110301+melissahenderson@users.noreply.github.com>
Date: Mon, 6 Jan 2025 13:13:43 -0500
Subject: [PATCH] docs: split manage liquidity into multi pages
Also added wrap to a few code blocks that needed it
---
packages/documentation/astro.config.mjs | 20 +-
.../docs/admin/liquidity/asset-liquidity.mdx | 106 ++++
.../admin/liquidity/payment-liquidity.mdx | 138 +++++
.../docs/admin/liquidity/peer-liquidity.mdx | 111 ++++
.../admin/liquidity/two-phase-withdrawals.mdx | 100 ++++
.../content/docs/admin/manage-liquidity.mdx | 476 ------------------
.../integration/deployment/docker-compose.mdx | 4 +-
.../docs/integration/playground/overview.mdx | 6 +-
.../docs/overview/concepts/telemetry.mdx | 4 +-
.../src/partials/liquidity-idempotency.mdx | 3 +
10 files changed, 484 insertions(+), 484 deletions(-)
create mode 100644 packages/documentation/src/content/docs/admin/liquidity/asset-liquidity.mdx
create mode 100644 packages/documentation/src/content/docs/admin/liquidity/payment-liquidity.mdx
create mode 100644 packages/documentation/src/content/docs/admin/liquidity/peer-liquidity.mdx
create mode 100644 packages/documentation/src/content/docs/admin/liquidity/two-phase-withdrawals.mdx
delete mode 100644 packages/documentation/src/content/docs/admin/manage-liquidity.mdx
create mode 100644 packages/documentation/src/partials/liquidity-idempotency.mdx
diff --git a/packages/documentation/astro.config.mjs b/packages/documentation/astro.config.mjs
index 19c02459dd..235645f1a1 100644
--- a/packages/documentation/astro.config.mjs
+++ b/packages/documentation/astro.config.mjs
@@ -213,7 +213,25 @@ export default defineConfig({
},
{
label: 'Manage liquidity',
- link: '/admin/manage-liquidity'
+ collapsed: true,
+ items: [
+ {
+ label: 'Asset liquidity',
+ link: '/admin/liquidity/asset-liquidity'
+ },
+ {
+ label: 'Peer liquidity',
+ link: '/admin/liquidity/peer-liquidity'
+ },
+ {
+ label: 'Payment liquidity',
+ link: '/admin/liquidity/payment-liquidity'
+ },
+ {
+ label: 'Two-phase withdrawals',
+ link: '/admin/liquidity/two-phase-withdrawals'
+ }
+ ]
}
]
},
diff --git a/packages/documentation/src/content/docs/admin/liquidity/asset-liquidity.mdx b/packages/documentation/src/content/docs/admin/liquidity/asset-liquidity.mdx
new file mode 100644
index 0000000000..f30d5852f0
--- /dev/null
+++ b/packages/documentation/src/content/docs/admin/liquidity/asset-liquidity.mdx
@@ -0,0 +1,106 @@
+---
+title: Asset liquidity
+tableOfContents:
+ maxHeadingLevel: 4
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components'
+import { CodeBlock, LinkOut } from '@interledger/docs-design-system'
+import IdempotencyNote from '/src/partials/liquidity-idempotency.mdx'
+
+Asset liquidity is the amount of value, denominated in a given asset, that Rafiki has available to handle foreign exchange transactions between you and a peer. An asset's liquidity increases when Interledger packets are received and decreases when packets are sent/forwarded.
+
+You should deposit and withdraw liquidity as necessary, based on your risk tolerance. Rafiki will fail any transaction that would cause an asset's liquidity to fall below zero.
+
+For more information about how Rafiki handles asset liquidity, see the [Accounting](/overview/concepts/accounting) concepts page and the [low asset liquidity](/integration/requirements/webhook-events#low-asset-liquidity) section of the webhook events page.
+
+## Manage asset liquidity using Rafiki Admin
+
+You can deposit and withdraw asset liquidity through the Rafiki Admin application's [Assets](/admin/admin-user-guide/#edit-asset) screen.
+
+## Manage asset liquidity using the Backend Admin API
+
+
+
+### Deposit asset liquidity
+
+
+
+ ```graphql
+ mutation DepositAssetLiquidity($input: DepositAssetLiquidityInput!) {
+ depositAssetLiquidity(input: $input) {
+ assetId
+ amount
+ id
+ idempotencyKey
+ success
+ }
+ }
+ ```
+
+
+ ```json
+ {
+ "input": {
+ "assetId": "7b8b0f65-896d-4403-b7ba-2e24bf20eb35",
+ "amount": "100",
+ "id": "b97fd85a-126e-42ef-b40d-1a50a70ffa6f",
+ "idempotencyKey": "b97fd85a-126e-42ef-b40d-1a50a70ffa6f",
+ }
+ }
+ ```
+ For more information about this mutation's input object, see [`DepositAssetLiquidityInput`](https://rafiki.dev/apis/graphql/backend/inputobjects/#depositassetliquidityinput).
+
+
+ When an asset liquidity deposit is successful, `DepositAssetLiquidity` returns `true`.
+
+ ```json
+ {
+ data: {
+ success: true
+ }
+ }
+
+````
+
+
+
+### Withdraw asset liquidity
+
+
+
+```graphql wrap
+mutation CreateAssetLiquidityWithdrawal($input: CreateAssetLiquidityWithdrawalInput!) {
+ createAssetLiquidityWithdrawal(input: $input) {
+ success
+ error
+ }
+}
+````
+
+
+
+ ```json
+ {
+ "input": {
+ "id": "b97fd85a-126e-42ef-b40d-1a50a70ffa6f",
+ "assetId": "7b8b0f65-896d-4403-b7ba-2e24bf20eb35",
+ "amount": "100",
+ "idempotencyKey": "b97fd85a-126e-42ef-b40d-1a50a70ffa6f",
+ "timeoutSeconds": 0
+ }
+ }
+ ```
+ For more information about this mutation's input object, see [`CreateAssetLiquidityWithdrawalInput`](https://rafiki.dev/apis/graphql/backend/inputobjects/#createassetliquiditywithdrawalinput).
+
+
+ When an asset liquidity withdrawal is successful, `CreateAssetLiquidityWithdrawal` returns `true`.
+ ```json
+ {
+ data: {
+ success: true
+ }
+ }
+ ```
+
+
diff --git a/packages/documentation/src/content/docs/admin/liquidity/payment-liquidity.mdx b/packages/documentation/src/content/docs/admin/liquidity/payment-liquidity.mdx
new file mode 100644
index 0000000000..5bb0aec576
--- /dev/null
+++ b/packages/documentation/src/content/docs/admin/liquidity/payment-liquidity.mdx
@@ -0,0 +1,138 @@
+---
+title: Payment liquidity
+tableOfContents:
+ maxHeadingLevel: 4
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components'
+import { CodeBlock, LinkOut } from '@interledger/docs-design-system'
+import IdempotencyNote from '/src/partials/liquidity-idempotency.mdx'
+
+Payment liquidity represents:
+
+- The value received from a completed incoming payment
+- The value available to send in an outgoing payment
+
+Because Rafiki doesn't hold funds, anything you receive in an incoming payment must be withdrawn and then credited to the recipient's account on your ledger. Listen for the [incoming payments](/integration/requirements/webhook-events#incoming-payments) webhook events to know when you need to interact with Rafiki.
+
+Any excess liquidity that remains after an outgoing payment completes must be withdrawn. You may also find that you must deposit liquidity into Rafiki to fund an outgoing payment. Listen for Rafiki's [outgoing payments](/integration/requirements/webhook-events#outgoing-payments) webhook events to know when action is required on your part.
+
+:::note[Rafiki Admin]
+The Rafiki Admin does not allow you to manage payment liquidity; however, you can view details about incoming and outgoing payments through the application's [Payments](/admin/admin-user-guide#payments) screen.
+:::
+
+For more information about how Rafiki handles payment liquidity, see the [Accounting](/overview/concepts/accounting) concepts page.
+
+## Manage payment liquidity using the Backend Admin API
+
+
+
+### Withdraw incoming payment liquidity
+
+
+
+ ```graphql wrap
+ mutation CreateIncomingPaymentWithdrawal($input: CreateIncomingPaymentWithdrawalInput!) {
+ createIncomingPaymentWithdrawal(input: $input) {
+ error
+ success
+ }
+ }
+ ```
+
+
+ ```json
+ {
+ "input": {
+ "incomingPaymentId": "b4f85d5c-652d-472d-873c-4ba2a5e39052",
+ "idempotencyKey": "a09b730d-8610-4fda-98fa-ec7acb19c775",
+ "timeoutSeconds": 0
+ }
+ }
+ ```
+ For more information about this mutation's input object, see [`CreateIncomingPaymentWithdrawalInput`](https://rafiki.dev/apis/graphql/backend/inputobjects/#createincomingpaymentwithdrawalinput).
+
+
+ When an incoming payment liquidity withdrawal is successful, `CreateIncomingPaymentWithdrawal` returns `true`.
+ ```json
+ {
+ data: {
+ success: true
+ }
+ }
+ ```
+
+
+
+### Deposit outgoing payment liquidity
+
+
+
+ ```graphql wrap
+ mutation DepositOutgoingPaymentLiquidity($input: DepositOutgoingPaymentLiquidityInput!) {
+ depositOutgoingPaymentLiquidity(input: $input) {
+ error
+ success
+ }
+ }
+ ```
+
+
+ ```json
+ {
+ "input": {
+ "outgoingPaymentId": "b4f85d5c-652d-472d-873c-4ba2a5e39052",
+ "idempotencyKey": "a09b730d-8610-4fda-98fa-ec7acb19c775"
+ }
+ }
+ ```
+ For more information about this mutation's input object, see [`DepositOutgoingPaymentLiquidityInput`](https://rafiki.dev/apis/graphql/backend/inputobjects/#depositoutgoingpaymentliquidityinput).
+
+
+ When an outgoing payment liquidity deposit is successful, `DepositOutgoingPaymentLiquidity` returns `true`.
+ ```json
+ {
+ data: {
+ success: true
+ }
+ }
+ ```
+
+
+
+### Withdraw outgoing payment liquidity
+
+
+
+ ```graphql wrap
+ mutation CreateOutgoingPaymentWithdrawal($input: CreateOutgoingPaymentWithdrawalInput!) {
+ createOutgoingPaymentWithdrawal(input: $input) {
+ error
+ success
+ }
+ }
+ ```
+
+
+ ```json
+ {
+ "input": {
+ "outgoingPaymentId": "b4f85d5c-652d-472d-873c-4ba2a5e39052",
+ "idempotencyKey": "a09b730d-8610-4fda-98fa-ec7acb19c775",
+ "timeoutSeconds": 0
+ }
+ }
+ ```
+ For more information about this mutation's input object, see [`CreateOutgoingPaymentWithdrawalInput`](https://rafiki.dev/apis/graphql/backend/inputobjects/#createoutgoingpaymentwithdrawalinput).
+
+
+ When an outgoing payment liquidity withdrawal is successful, `CreateOutgoingPaymentWithdrawal` returns `true`.
+ ```json
+ {
+ data: {
+ success: true
+ }
+ }
+ ```
+
+
diff --git a/packages/documentation/src/content/docs/admin/liquidity/peer-liquidity.mdx b/packages/documentation/src/content/docs/admin/liquidity/peer-liquidity.mdx
new file mode 100644
index 0000000000..28651b9e07
--- /dev/null
+++ b/packages/documentation/src/content/docs/admin/liquidity/peer-liquidity.mdx
@@ -0,0 +1,111 @@
+---
+title: Peer liquidity
+tableOfContents:
+ maxHeadingLevel: 4
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components'
+import { CodeBlock, LinkOut } from '@interledger/docs-design-system'
+import IdempotencyNote from '/src/partials/liquidity-idempotency.mdx'
+
+Peer liquidity is the line of credit you extend to a peer, denominated in your agreed upon asset. A peer's liquidity account balance represents the amount of credit the peer still has available to them.
+
+A peer's liquidity increases when payments are made to the peer and decreases when payments are made from the peer. For example, if a customer of your peer sends your customer a payment of $20 USD, then your peer's liquidity account decreases by 20.
+
+If a peer’s liquidity is insufficient (e.g., they’ve used up their allotted credit line), transactions initiated from the peer will fail. Once a peer's liquidity is used up, you should settle with your peer and reset their liquidity. Deposit and withdraw peer liquidity as necessary, based on your risk profile.
+
+For more information about how Rafiki handles peer liquidity, see the [Accounting](/overview/concepts/accounting) concepts page and the [low peer liquidity](/integration/requirements/webhook-events#low-peer-liquidity) section of the webhook events page.
+
+## Manage peer liquidity using Rafiki Admin
+
+You can deposit and withdraw peer liquidity through the Rafiki Admin application's [Peers](/admin/admin-user-guide/#edit-peer) screen.
+
+## Manage peer liquidity using the Backend Admin API
+
+
+
+### Deposit peer liquidity
+
+
+
+ ```graphql wrap
+ mutation DepositPeerLiquidity($input: DepositPeerLiquidityInput!) {
+ depositPeerLiquidity(input: $input) {
+ success
+ error
+ }
+ }
+ ```
+
+
+ ```json
+ {
+ "input": {
+ "id": "a09b730d-8610-4fda-98fa-ec7acb19c775",
+ "peerId": "73158598-2e0c-4973-895e-aebd115af260",
+ "amount": "1000000",
+ "idempotencyKey": "a09b730d-8610-4fda-98fa-ec7acb19c775"
+ }
+ }
+ ```
+
+For more information about this mutation's input object, see [`DepositPeerLiquidityInput`](https://rafiki.dev/apis/graphql/backend/inputobjects/#depositpeerliquidityinput).
+
+
+
+ When a peer liquidity deposit is successful, `DepositPeerLiquidity` returns `true`.
+
+```json
+{
+ "data": {
+ "success": true
+ }
+}
+```
+
+
+
+
+### Withdraw peer liquidity
+
+
+
+ ```graphql wrap
+ mutation CreatePeerLiquidityWithdrawal($input: CreatePeerLiquidityWithdrawalInput!) {
+ createPeerLiquidityWithdrawal(input: $input) {
+ success
+ error
+ }
+ }
+ ```
+
+
+ ```json
+ {
+ "input": {
+ "id": "421fae87-9a59-4217-9ff8-faf55ffab9c6",
+ "peerId": "73158598-2e0c-4973-895e-aebd115af260",
+ "amount": "100",
+ "idempotencyKey": "b97fd85a-126e-42ef-b40d-1a50a70ffa6f",
+ "timeoutSeconds": 0
+ }
+ }
+ ```
+
+For more information about this mutation's input object, see [`CreatePeerLiquidityWithdrawalInput`](https://rafiki.dev/apis/graphql/backend/inputobjects/#createpeerliquiditywithdrawalinput).
+
+
+
+
+When a peer liquidity withdrawal is successful, `CreatePeerLiquidityWithdrawal` returns `true`.
+
+```json
+{
+ "data": {
+ "success": true
+ }
+}
+```
+
+
+
diff --git a/packages/documentation/src/content/docs/admin/liquidity/two-phase-withdrawals.mdx b/packages/documentation/src/content/docs/admin/liquidity/two-phase-withdrawals.mdx
new file mode 100644
index 0000000000..8731cae7be
--- /dev/null
+++ b/packages/documentation/src/content/docs/admin/liquidity/two-phase-withdrawals.mdx
@@ -0,0 +1,100 @@
+---
+title: Two-phase withdrawals
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components'
+import { CodeBlock, LinkOut } from '@interledger/docs-design-system'
+import IdempotencyNote from '/src/partials/liquidity-idempotency.mdx'
+
+Rafiki allows for two-phase withdrawals, which moves funds in two stages.
+
+1. Reserve funds (`pending`)
+2. Resolve funds (`post`, `void`, or `expire`)
+
+The following transactions support two-phase withdrawals:
+
+- Asset liquidity withdrawal
+- Peer liquidity withdrawal
+- Incoming payment withdrawal
+- Outgoing payment withdrawal
+- Wallet address withdrawal
+
+When a withdrawal liquidity transaction is requested with a timeout greater than `0`, the transaction is processed as a two-phase withdrawal. A `0` denotes the absence of a timeout.
+
+If the timeout interval passes before the transaction posts or is voided, the transaction expires and the full amount is returned to the original account.
+
+## Manage two-phase withdrawals using the Backend Admin API
+
+
+
+### Post and commit a successful transfer
+
+
+
+ ```graphql wrap
+ mutation PostLiquidityWithdrawal($input: PostLiquidityWithdrawalInput!) {
+ postLiquidityWithdrawal(input: $input) {
+ error
+ success
+ }
+ }
+ ```
+
+
+ ```json
+ {
+ "input": {
+ "withdrawalId": "b4f85d5c-652d-472d-873c-4ba2a5e39052",
+ "idempotencyKey": "a09b730d-8610-4fda-98fa-ec7acb19c775"
+ }
+ }
+ ```
+ For more information about this mutation's input object, see [`PostLiquidityWithdrawalInput`](https://rafiki.dev/apis/graphql/backend/inputobjects/#postliquiditywithdrawalinput).
+
+
+ When a liquidity withdrawal post is successful, `PostLiquidityWithdrawal` returns `true`.
+ ```json
+ {
+ data: {
+ success: true
+ }
+ }
+ ```
+
+
+
+### Void and roll-back an unsuccessful transfer
+
+
+
+ ```graphql wrap
+ mutation VoidLiquidityWithdrawal($input: VoidLiquidityWithdrawalInput!) {
+ voidLiquidityWithdrawal(input: $input) {
+ error
+ success
+ }
+ }
+ ```
+
+
+ ```json
+ {
+ "input": {
+ "withdrawalId": "b4f85d5c-652d-472d-873c-4ba2a5e39052",
+ "idempotencyKey": "a09b730d-8610-4fda-98fa-ec7acb19c775"
+ }
+ }
+ ```
+ For more information about this mutation's input object, see [`VoidLiquidityWithdrawalInput`](https://rafiki.dev/apis/graphql/backend/inputobjects/#voidliquiditywithdrawalinput).
+
+
+ When a liquidity withdrawal is successfully voided and rolled back, `VoidLiquidityWithdrawal` returns `true`.
+ ```json
+ {
+ data: {
+ success: true
+ }
+ }
+ ```
+
+
diff --git a/packages/documentation/src/content/docs/admin/manage-liquidity.mdx b/packages/documentation/src/content/docs/admin/manage-liquidity.mdx
deleted file mode 100644
index a5963dc761..0000000000
--- a/packages/documentation/src/content/docs/admin/manage-liquidity.mdx
+++ /dev/null
@@ -1,476 +0,0 @@
----
-title: Manage liquidity
----
-
-import { CodeBlock, LinkOut } from '@interledger/docs-design-system'
-
-As an implementation of the Interledger Protocol, Rafiki provides [accounting](/overview/concepts/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
-
-
-
-```graphql
-mutation DepositAssetLiquidity($input: DepositAssetLiquidityInput!) {
- depositAssetLiquidity(input: $input) {
- code
- success
- message
- error
- }
-}
-```
-
-
-
-#### Example
-
-
-
-```json
-{
- "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
-
-
-
-```graphql
-mutation CreateAssetLiquidityWithdrawal(
- $input: CreateAssetLiquidityWithdrawalInput!
-) {
- createAssetLiquidityWithdrawal(input: $input) {
- code
- success
- message
- error
- }
-}
-```
-
-
-
-#### Example
-
-
-
-```json
-{
- "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](/admin/admin-user-guide/#edit-asset) 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
-
-
-
-```graphql
-mutation DepositPeerLiquidity($input: DepositPeerLiquidityInput!) {
- depositPeerLiquidity(input: $input) {
- code
- success
- message
- error
- }
-}
-```
-
-
-
-#### Example
-
-
-
-```json
-{
- "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
-
-
-
-```graphql
-mutation CreatePeerLiquidityWithdrawal(
- $input: CreatePeerLiquidityWithdrawalInput!
-) {
- createPeerLiquidityWithdrawal(input: $input) {
- code
- success
- message
- error
- }
-}
-```
-
-
-
-#### Example
-
-
-
-```json
-{
- "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](/admin/admin-user-guide/#edit-peer) 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
-
-
-
-```graphql
-mutation CreateIncomingPaymentWithdrawal(
- $input: CreateIncomingPaymentWithdrawalInput!
-) {
- createIncomingPaymentWithdrawal(input: $input) {
- code
- error
- message
- success
- }
-}
-```
-
-
-
-#### Example
-
-
-
-```json
-{
- "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
-
-
-
-```graphql
-mutation DepositOutgoingPaymentLiquidity(
- $input: DepositOutgoingPaymentLiquidityInput!
-) {
- depositOutgoingPaymentLiquidity(input: $input) {
- code
- error
- message
- success
- }
-}
-```
-
-
-
-#### Example
-
-
-
-```json
-{
- "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
-
-
-
-```graphql
-mutation CreateOutgoingPaymentWithdrawal(
- $input: CreateOutgoingPaymentWithdrawalInput!
-) {
- createOutgoingPaymentWithdrawal(input: $input) {
- code
- error
- message
- success
- }
-}
-```
-
-
-
-#### Example
-
-
-
-```json
-{
- "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
-
-
-
-```graphql
-mutation PostLiquidityWithdrawal($input: PostLiquidityWithdrawalInput!) {
- postLiquidityWithdrawal(input: $input) {
- code
- error
- message
- success
- }
-}
-```
-
-
-
-#### Example
-
-
-
-```json
-{
- "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
-
-
-
-```graphql
-mutation VoidLiquidityWithdrawal($input: VoidLiquidityWithdrawalInput!) {
- voidLiquidityWithdrawal(input: $input) {
- code
- error
- message
- success
- }
-}
-```
-
-
-
-#### Example
-
-
-
-```json
-{
- "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`.
diff --git a/packages/documentation/src/content/docs/integration/deployment/docker-compose.mdx b/packages/documentation/src/content/docs/integration/deployment/docker-compose.mdx
index bf5ac262e6..f1753fd504 100644
--- a/packages/documentation/src/content/docs/integration/deployment/docker-compose.mdx
+++ b/packages/documentation/src/content/docs/integration/deployment/docker-compose.mdx
@@ -56,7 +56,7 @@ sudo apt update && sudo apt install nginx certbot python3-certbot-nginx
Generate the Let’s Encrypt certificates using Certbot:
-```sh
+```sh wrap
certbot certonly --manual --preferred-challenges=dns --email EMAIL --server https://acme-v02.api.letsencrypt.org/directory --agree-tos -d DOMAIN
```
@@ -455,7 +455,7 @@ server {
Once the Nginx configuration files have been created, set up symbolic links that will allow Nginx to read those files and redirect the local paths to the exposed domains and ports.
-```sh
+```sh wrap
sudo ln -s /etc/nginx/sites-available/admin.conf /etc/nginx/sites-enabled/admin.conf
sudo ln -s /etc/nginx/sites-available/open_payments_auth_server.conf /etc/nginx/sites-enabled/open_payments_auth_server.conf
diff --git a/packages/documentation/src/content/docs/integration/playground/overview.mdx b/packages/documentation/src/content/docs/integration/playground/overview.mdx
index 861247296a..f2dac20e06 100644
--- a/packages/documentation/src/content/docs/integration/playground/overview.mdx
+++ b/packages/documentation/src/content/docs/integration/playground/overview.mdx
@@ -52,7 +52,7 @@ To spin up the Local Playground install the following software on your machine:
Run the following commands from the root of the project.
-```sh
+```sh wrap
## If you have spun up the environment before, first tear down and remove volumes!
pnpm localenv:compose down --volumes
@@ -65,7 +65,7 @@ pnpm localenv:compose up
If you want to use Postgres as the accounting database instead of TigerBeetle, you must use the `psql` variant of the `localenv:compose` commands as follows:
-```sh
+```sh wrap
## If you have spun up the environment before, first tear down and remove volumes!
## Otherwise start the local environment
pnpm localenv:compose:psql down --volumes
@@ -269,7 +269,7 @@ In addition to using Rafiki Admin to interact with the Admin APIs, you can also
Every wallet address also serves as an SPSP endpoint. A `GET` request with an `Accept` header `application/spsp4+json` will return an SPSP response with STREAM connection details. The following example uses [http://localhost:3000/accounts/gfranklin](http://localhost:3000/accounts/gfranklin) as the SPSP endpoint.
-```sh
+```sh wrap
http GET http://localhost:3000/accounts/gfranklin Host:backend Accept:application/spsp4+json
diff --git a/packages/documentation/src/content/docs/overview/concepts/telemetry.mdx b/packages/documentation/src/content/docs/overview/concepts/telemetry.mdx
index 96bc7319cb..2a458e2824 100644
--- a/packages/documentation/src/content/docs/overview/concepts/telemetry.mdx
+++ b/packages/documentation/src/content/docs/overview/concepts/telemetry.mdx
@@ -196,7 +196,7 @@ The configuration can be tested in our [Local Playground](/integration/playgroun
#### Docker Compose config
```yaml
-#Serves as example for optional local collector configuration
+# Serves as example for optional local collector configuration
happy-life-otel-collector:
image: otel/opentelemetry-collector-contrib:latest
command: ['--config=/etc/otel-collector-config.yaml', '']
@@ -217,7 +217,7 @@ happy-life-otel-collector:
Supplemental documentation can be found in OTEL’s Collector Configuration documentation.
-```yaml
+```yaml wrap
# Serves as example for the configuration of a local OpenTelemetry Collector that sends metrics to an AWS Managed Prometheus Workspace
# Sigv4auth required for AWS Prometheus Remote Write access (USER with access keys needed)
diff --git a/packages/documentation/src/partials/liquidity-idempotency.mdx b/packages/documentation/src/partials/liquidity-idempotency.mdx
new file mode 100644
index 0000000000..e282f5a67a
--- /dev/null
+++ b/packages/documentation/src/partials/liquidity-idempotency.mdx
@@ -0,0 +1,3 @@
+:::note[Idempotency key]
+You must provide an `idempotencyKey` when calling any mutations related to liquidity. This unique key ensures duplicate or retried requests are processed only once. For more information, see the [Idempotency](/apis/graphql/admin-api-overview#idempotency) section in the GraphQL Admin APIs page.
+:::