docs: split manage liquidity into multi pages

Also added wrap to a few code blocks that needed it
interledger · Jan 6, 2025 · ae0c9bd · ae0c9bd
1 parent 52ff03b
commit ae0c9bd
Show file tree

Hide file tree

Showing 10 changed files with 484 additions and 484 deletions.
diff --git 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
@@ -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
+
+<IdempotencyNote />
+
+### Deposit asset liquidity
+
+<Tabs>
+  <TabItem label="Operation">
+    ```graphql
+    mutation DepositAssetLiquidity($input: DepositAssetLiquidityInput!) {
+      depositAssetLiquidity(input: $input) {
+        assetId
+        amount
+        id
+        idempotencyKey
+        success
+      }
+    }
+  ```
+  </TabItem>
+  <TabItem label="Arguments">
+    ```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). 
+  </TabItem>
+  <TabItem label="Response">
+    When an asset liquidity deposit is successful, `DepositAssetLiquidity` returns `true`.
+
+    ```json
+    {
+      data: {
+        success: true
+      }
+    }
+
+````
+</TabItem>
+</Tabs>
+
+### Withdraw asset liquidity
+
+<Tabs>
+<TabItem label="Operation">
+```graphql wrap
+mutation CreateAssetLiquidityWithdrawal($input: CreateAssetLiquidityWithdrawalInput!) {
+  createAssetLiquidityWithdrawal(input: $input) {
+    success
+    error
+  }
+}
+````
+
+  </TabItem>
+  <TabItem label="Arguments">
+  ```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).
+  </TabItem>
+  <TabItem label="Response">
+  When an asset liquidity withdrawal is successful, `CreateAssetLiquidityWithdrawal` returns `true`.
+  ```json
+   {
+    data: {
+      success: true
+    }
+  }
+  ```
+  </TabItem>
+</Tabs>
diff --git a/packages/documentation/src/content/docs/admin/liquidity/payment-liquidity.mdx 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
+
+<IdempotencyNote />
+
+### Withdraw incoming payment liquidity
+
+<Tabs>
+  <TabItem label="Operation">
+  ```graphql wrap
+  mutation CreateIncomingPaymentWithdrawal($input: CreateIncomingPaymentWithdrawalInput!) {
+  createIncomingPaymentWithdrawal(input: $input) {
+    error
+    success
+    }
+  }
+  ```
+  </TabItem>
+  <TabItem label="Arguments">
+  ```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).
+  </TabItem>
+  <TabItem label="Response">
+  When an incoming payment liquidity withdrawal is successful, `CreateIncomingPaymentWithdrawal` returns `true`.
+  ```json
+  {
+  data: {
+    success: true
+    }
+  }
+  ```
+  </TabItem>
+</Tabs>
+
+### Deposit outgoing payment liquidity
+
+<Tabs>
+  <TabItem label="Operation">
+  ```graphql wrap
+  mutation DepositOutgoingPaymentLiquidity($input: DepositOutgoingPaymentLiquidityInput!) {
+  depositOutgoingPaymentLiquidity(input: $input) {
+    error
+    success
+    }
+  }
+  ```
+  </TabItem>
+  <TabItem label="Arguments">
+  ```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).
+  </TabItem>
+  <TabItem label="Response">
+  When an outgoing payment liquidity deposit is successful, `DepositOutgoingPaymentLiquidity` returns `true`.
+  ```json
+  {
+  data: {
+    success: true
+    }
+  }
+  ```
+  </TabItem>
+</Tabs>
+
+### Withdraw outgoing payment liquidity
+
+<Tabs>
+  <TabItem label="Operation">
+  ```graphql wrap
+  mutation CreateOutgoingPaymentWithdrawal($input: CreateOutgoingPaymentWithdrawalInput!) {
+  createOutgoingPaymentWithdrawal(input: $input) {
+    error
+    success
+    }
+  }
+  ```
+  </TabItem>
+  <TabItem label="Arguments">
+  ```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).
+  </TabItem>
+  <TabItem label="Response">
+  When an outgoing payment liquidity withdrawal is successful, `CreateOutgoingPaymentWithdrawal` returns `true`.
+  ```json
+  {
+  data: {
+    success: true
+    }
+  }
+  ```
+  </TabItem>
+</Tabs>
diff --git a/packages/documentation/src/content/docs/admin/liquidity/peer-liquidity.mdx 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
+
+<IdempotencyNote />
+
+### Deposit peer liquidity
+
+<Tabs>
+  <TabItem label="Operation">
+  ```graphql wrap
+  mutation DepositPeerLiquidity($input: DepositPeerLiquidityInput!) {
+    depositPeerLiquidity(input: $input) {
+     success
+     error
+   }
+  }
+  ```
+  </TabItem>
+  <TabItem label="Arguments">
+  ```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).
+
+  </TabItem>
+  <TabItem label="Response">
+  When a peer liquidity deposit is successful, `DepositPeerLiquidity` returns `true`.
+
+```json
+{
+  "data": {
+    "success": true
+  }
+}
+```
+
+  </TabItem>
+</Tabs>
+
+### Withdraw peer liquidity
+
+<Tabs>
+  <TabItem label="Operation">
+  ```graphql wrap
+  mutation CreatePeerLiquidityWithdrawal($input: CreatePeerLiquidityWithdrawalInput!) {
+    createPeerLiquidityWithdrawal(input: $input) {
+      success
+      error
+   }
+  }
+  ```
+  </TabItem>
+  <TabItem label="Arguments">
+  ```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).
+
+  </TabItem>
+  <TabItem label="Response">
+
+When a peer liquidity withdrawal is successful, `CreatePeerLiquidityWithdrawal` returns `true`.
+
+```json
+{
+  "data": {
+    "success": true
+  }
+}
+```
+
+  </TabItem>
+</Tabs>