From a02e32aac7db9335e6b05bf6bec21cba92d9e5d0 Mon Sep 17 00:00:00 2001 From: brad-dow <162852233+brad-dow@users.noreply.github.com> Date: Fri, 6 Dec 2024 15:42:16 -0600 Subject: [PATCH] docs: peering integration guide Initial draft (repurposed the manging peering relationships admin page into a technical integration guide) Completed a few tasks from https://github.com/interledger/rafiki/issues/3139 as well, including the following: - Place the peering integration doc within the Integration > Requirements section. - Create a new section in Integration, called Deployment, and move the "Docker Compose" and "Helm and Kubernetes" pages into the section. - Move Integration > Services so that it's a subsection of Deployment (e.g., Integration > Deployment > Services > auth service). - The content in the "Manage peering relationships" page should become part of Brad's peering integration page. The "Manage" page should go away. - Update sidenav's TOCs as needed --- packages/documentation/astro.config.mjs | 74 ++--- .../{prod => deployment}/docker-compose.mdx | 0 .../{prod => deployment}/helm-k8s.mdx | 0 .../services/auth-service.mdx | 0 .../services/backend-service.mdx | 4 +- .../services/frontend-service.mdx | 0 .../services/token-introspection.mdx | 0 .../docs/integration/requirements/peers.mdx | 287 ++++++++++++++++++ .../docs/overview/concepts/interledger.mdx | 2 +- 9 files changed, 330 insertions(+), 37 deletions(-) rename packages/documentation/src/content/docs/integration/{prod => deployment}/docker-compose.mdx (100%) rename packages/documentation/src/content/docs/integration/{prod => deployment}/helm-k8s.mdx (100%) rename packages/documentation/src/content/docs/integration/{ => deployment}/services/auth-service.mdx (100%) rename packages/documentation/src/content/docs/integration/{ => deployment}/services/backend-service.mdx (95%) rename packages/documentation/src/content/docs/integration/{ => deployment}/services/frontend-service.mdx (100%) rename packages/documentation/src/content/docs/integration/{ => deployment}/services/token-introspection.mdx (100%) create mode 100644 packages/documentation/src/content/docs/integration/requirements/peers.mdx diff --git a/packages/documentation/astro.config.mjs b/packages/documentation/astro.config.mjs index 6fcebb9397..f1615952b6 100644 --- a/packages/documentation/astro.config.mjs +++ b/packages/documentation/astro.config.mjs @@ -112,6 +112,10 @@ export default defineConfig({ label: 'Assets', link: '/integration/requirements/assets' }, + { + label: 'Peers', + link: '/integration/requirements/peers' + }, { label: 'Wallet addresses', link: '/integration/requirements/wallet-addresses' @@ -134,36 +138,6 @@ export default defineConfig({ } ] }, - { - label: 'Docker Compose', - link: '/integration/prod/docker-compose' - }, - { - label: 'Helm and Kubernetes', - link: '/integration/prod/helm-k8s' - }, - { - label: 'Services', - collapsed: true, - items: [ - { - label: 'Auth service', - link: '/integration/services/auth-service' - }, - { - label: 'Backend service', - link: '/integration/services/backend-service' - }, - { - label: 'Frontend service', - link: '/integration/services/frontend-service' - }, - { - label: 'Token introspection', - link: '/integration/services/token-introspection' - } - ] - }, { label: 'Test locally', collapsed: true, @@ -181,6 +155,42 @@ export default defineConfig({ link: '/integration/playground/testnet' } ] + }, + { + label: 'Deployment', + collapsed: true, + items: [ + { + label: 'Services', + collapsed: true, + items: [ + { + label: 'Auth service', + link: '/integration/deployment/services/auth-service' + }, + { + label: 'Backend service', + link: '/integration/deployment/services/backend-service' + }, + { + label: 'Frontend service', + link: '/integration/deployment/services/frontend-service' + }, + { + label: 'Token introspection', + link: '/integration/deployment/services/token-introspection' + } + ] + }, + { + label: 'Docker Compose', + link: '/integration/deployment/docker-compose' + }, + { + label: 'Helm and Kubernetes', + link: '/integration/deployment/helm-k8s' + }, + ] } ] }, @@ -192,10 +202,6 @@ export default defineConfig({ label: 'Rafiki Admin', link: '/admin/admin-user-guide' }, - { - label: 'Manage peering relationships', - link: '/admin/manage-peering' - }, { label: 'Manage liquidity', link: '/admin/manage-liquidity' diff --git a/packages/documentation/src/content/docs/integration/prod/docker-compose.mdx b/packages/documentation/src/content/docs/integration/deployment/docker-compose.mdx similarity index 100% rename from packages/documentation/src/content/docs/integration/prod/docker-compose.mdx rename to packages/documentation/src/content/docs/integration/deployment/docker-compose.mdx diff --git a/packages/documentation/src/content/docs/integration/prod/helm-k8s.mdx b/packages/documentation/src/content/docs/integration/deployment/helm-k8s.mdx similarity index 100% rename from packages/documentation/src/content/docs/integration/prod/helm-k8s.mdx rename to packages/documentation/src/content/docs/integration/deployment/helm-k8s.mdx diff --git a/packages/documentation/src/content/docs/integration/services/auth-service.mdx b/packages/documentation/src/content/docs/integration/deployment/services/auth-service.mdx similarity index 100% rename from packages/documentation/src/content/docs/integration/services/auth-service.mdx rename to packages/documentation/src/content/docs/integration/deployment/services/auth-service.mdx diff --git a/packages/documentation/src/content/docs/integration/services/backend-service.mdx b/packages/documentation/src/content/docs/integration/deployment/services/backend-service.mdx similarity index 95% rename from packages/documentation/src/content/docs/integration/services/backend-service.mdx rename to packages/documentation/src/content/docs/integration/deployment/services/backend-service.mdx index b9115744c8..bd792915f3 100644 --- a/packages/documentation/src/content/docs/integration/services/backend-service.mdx +++ b/packages/documentation/src/content/docs/integration/deployment/services/backend-service.mdx @@ -39,7 +39,7 @@ Some of the responsibilities of a connector include: - Authenticating packets against ILP account credentials. - Forwarding packets to a sender or receiver. -- Rejecting a packet for any number of reasons, including expiration, insufficient liquidity, rate limit exceeded, or if the amount exceeds the `maxPacketAmount` [agreed to](/admin/manage-peering) by the connector and its peer. +- Rejecting a packet for any number of reasons, including expiration, insufficient liquidity, rate limit exceeded, or if the amount exceeds the `maxPacketAmount` [agreed to](/integration/requirements/peers#prerequisites) by the connector and its peer. - Converting currencies. - Fulfilling packets with an internal STREAM server. @@ -48,7 +48,7 @@ The `backend` service includes an HTTP server listening on the configured `CONNE Similarly, if a packet's destination address corresponds to a peer, your connector will forward the packet to your peer over HTTP, along with your peer's outgoing HTTP `authToken`. :::note[Auth tokens] -You and your peer should have exchanged incoming and outgoing auth tokens as part of establishing your [peering relationship](/admin/manage-peering). +You and your peer should have exchanged incoming and outgoing auth tokens as part of establishing your [peering relationship](/integration/requirements/peers#prerequisites). ::: A packet can either continue on to your peer via HTTP or terminate at your Rafiki instance's STREAM server. If the packet terminates at your STREAM server, your connector will attempt to extract and decode the payment tag from the packet's destination address. When your connector successfully matches the tag with a locally managed wallet address or incoming payment, the connector will not forward the packet. Instead, it will credit the corresponding balance and track the total amount received in Redis to support STREAM receipts. Packets addressed to a wallet address happen via SPSP. diff --git a/packages/documentation/src/content/docs/integration/services/frontend-service.mdx b/packages/documentation/src/content/docs/integration/deployment/services/frontend-service.mdx similarity index 100% rename from packages/documentation/src/content/docs/integration/services/frontend-service.mdx rename to packages/documentation/src/content/docs/integration/deployment/services/frontend-service.mdx diff --git a/packages/documentation/src/content/docs/integration/services/token-introspection.mdx b/packages/documentation/src/content/docs/integration/deployment/services/token-introspection.mdx similarity index 100% rename from packages/documentation/src/content/docs/integration/services/token-introspection.mdx rename to packages/documentation/src/content/docs/integration/deployment/services/token-introspection.mdx diff --git a/packages/documentation/src/content/docs/integration/requirements/peers.mdx b/packages/documentation/src/content/docs/integration/requirements/peers.mdx new file mode 100644 index 0000000000..1293d8875d --- /dev/null +++ b/packages/documentation/src/content/docs/integration/requirements/peers.mdx @@ -0,0 +1,287 @@ +--- +title: Peering integration guide +--- + +import { CodeBlock, LinkOut } from '@interledger/docs-design-system' + +To join the Interledger network and be able to send and receive payments, you must add one or more peer(s) to your Rafiki instance. Peering establishes the connections needed for your Rafiki instance to interact with another account servicing entity (ASE). The purpose of this guide is to help you set up and manage peers. + +While this guide focuses on the conceptual and technical steps of adding and managing peers via the Backend Admin API, the Rafiki Admin application offers the same functionality in a user-friendly interface. + +Refer to the [Rafiki Admin user guide](/admin/admin-user-guide#peers) for detailed instructions and examples of creating and managing peers through the application. + +:::tip +Whether you are using the Backend Admin API or the Rafiki Admin application, the underlying configurations and requirements remain the same. Choose the interface that best suits your individual workflow. +::: + +## Prerequisites + +Before adding a peer, you and the account servicing entity you intend to peer with must both: + +- Run an implementation of an [Interledger connector](/integration/services/backend-service#interledger-connector) (ideally Rafiki). +- Agree on an [asset](/overview/concepts/accounting#assets) for the peering relationship. You can set up multiple peering relationships with the same peer based on different assets. At least one asset shared by you and your peer must be added to your Rafiki instance prior to setting up the peering relationship. For more information, refer to [Assets](/integration/requirements/assets/). +- Agree on a `maxPacketAmount` value, which specifies how many packets a payment is split into. +- Communicate your respective static Interledger (ILP) addresses. +- Communicate a connection endpoint for the other peer to send packets to. +- Exchange `auth` tokens for the connection endpoint. +- Agree on a settlement mechanism (a means of paying one another for the successful forwarding and delivery of packets), which is outside the scope of Interledger and Rafiki. + +Optionally, you may also deposit an initial liquidity for your peer. + +:::note +Peering is not required unless you want to participate in transactions with another ASE running Rafiki. For foundational peering concepts, refer to [Peers](/overview/concepts/interledger/#peers). +::: + +## Setting up peering in Rafiki + +The basic workflow of setting up a peering relationship starts with adding the agreed upon asset, then adding a peer, and then creating a wallet address from where you can send and receive payments. + +### Add an asset + +As mentioned in the prerequisites, an asset must be added to your Rafiki instance before creating a peering relationship. To learn how to add an asset, refer to [Assets](/integration/requirements/assets/). + +### Add a peer + +After adding an asset, add a peer using the `createPeer` GraphQL mutation. + +#### `createPeer` + + + +```graphql +mutation CreatePeer($input: CreatePeerInput!) { + createPeer(input: $input) { + code + success + message + peer { + id + asset { + code + scale + } + staticIlpAddress + name + } + } +} +``` + + + +##### Example + + + +```json +{ + "input": { + "staticIlpAddress": "g.othergreatwallet", + "name": "The Other Great Wallet" + "http": { + "incoming": {"authTokens": ["mytoken"]}, + "outgoing": {"endpoint": "ilp.othergreatwallet.com", "authToken": "theirtoken"} + }, + "assetId": "INSERT_ASSET_ID", + "initialLiquidity": + } +} +``` + + + +
+ +| Variable | Description | Required | +| -------------------------- | --------------------------------------------------------------------------------------------------------------------------- | -------- | +| `assetID` | The ID of the asset that you and your peer will use to ultimately settle your net obligations outside of Interledger. | Y | +| `staticILPaddress` | Your peer’s static ILP address (the example uses `g.othergreatwallet`) | Y | +| `name` | Your peer’s name (the example uses “The Other Great Wallet”) | Y | +| `http.incoming.authTokens` | The token your peer will use to present and connect to and send packets to your Rafiki instance. | Y | +| `http.outgoing.endpoint` | Your peer’s connector endpoint. By default it is on local port 0.0.0.0:3002 | Y | +| `http.outgoing.authtoken` | The token that you will use to present to your peer and connect to and send packets to their Rafiki instance. | Y | +| `initialLiquidity` | Initial amount of liquidity to deposit for peer. Liquidity can also be deposited using the `DepositPeerLiquidity` mutation. | N | + +
+ + + +```json +{ + "data": { + "createPeer": { + "code": "200", + "success": true, + "message": "Created ILP Peer", + "peer": { + "id": "480ef339-7842-4501-a905-923fc1339cef", + "asset": { + "code": "USD", + "scale": 2 + }, + "staticIlpAddress": "g.othergreatwallet", + "name": "The Other Great Wallet" + } + } + } +} +``` + + + +### Create wallet addresses + +After adding a peer, we need to create a wallet address. This wallet address is where payments are sent from and received. To learn how to create a new wallet address, refer to [Assets](/integration/requirements/wallet-addresses/). + +## Managing peers + +Once a peer has been added to your Rafiki instance, ongoing peer management ensures that your peering integration remains functional. This includes editing configurations to reflect changes in your peer's technical details or resolving setup errors. It also includes deleting a peer that was created in error, as long as no payments have been exchanged. Active peer management helps maintain seamless payment flows and keeps your Rafiki instance up to date with operational changes. + +### Edit a peer + +Editing a peer allows you to adjust peering configurations or address any changes communicated by the peer. Some examples include updating new endpoints or tokens, technical settings like the maximum packet amount, or peer liquidity thresholds. + +In this example we are going to update the peer we just created. Rather than change any of the peering details, we can add some optional details that we didn't include when we created the peer. We will define the `maxPacketAmount` and the `liquidityThreshold`. + +#### `updatePeer` + + + +```graphql +mutation UpdatePeer($input: UpdatePeerInput!) { + updatePeer(input: $input) { + peer { + id + name + http { + outgoing { + authToken + endpoint + } + } + maxPacketAmount + liquidityThreshold + } + } +} +``` + + + +##### Example + +The input object for the update operation only requires that the `id` is present. All other variables are optional. For this example we will include the required `id` variable, as well as the optional variables of the fields we wish to update. In this case, `maxPacketAmount` and `liquidityThreshold`. + + + +```json +{ + "input": { + "id": "480ef339-7842-4501-a905-923fc1339cef", + "maxPacketAmount": 1000, + "liquidityThreshold": 100 + } +} +``` + + + +
+ +| Variable | Description | Required | +| -------------------------- | ------------------------------------------------------------------------------------------------------------- | -------- | +| `id` | The ID of the peer you wish to update. | Y | +| `maxPacketAmount` | Maximum packet amount that the peer accepts. | N | +| `liquidityThreshold` | A webhook event will notify the Account Servicing Entity if peer liquidity falls below this new value. | N | + +
+ + + +```json +{ + "data": { + "updatePeer": { + "code": "200", + "success": true, + "message": "Updated ILP Peer", + "peer": { + "id": "480ef339-7842-4501-a905-923fc1339cef", + "name": "The Other Great Wallet", + "http": { + "outgoing": { + "authToken": "test", + "endpoint": "http://peering-test:3002" + } + }, + "maxPacketAmount": 1000, + "liquidityThreshold": 100 + } + } + } +} +``` + + + +### Delete a peer + +Deleting a peer is an action that removes a peer from your Rafiki instance. There are specific rules and considerations to keep in mind before initating this irreversible operation. + +A peer can only be deleted if no payments have been made to or received from that peer. This ensures that historical payment records are preserved. If you attempt to delete a peer with payment history, the backend will throw an error, preventing the deletion. + +Deleting a peer is useful in situations where there were configuration errors when the peer was first created like an incorrect auth token or ILP address. + +:::danger +Deleting a peer is permanent and cannot be reversed. If you delete a peer in error, you must create another new peer. +::: + +#### `deletePeer` + + + +```graphql +mutation DeletePeer($input: DeletePeerInput!) { + deletePeer(input: $input) { + success + } +} +``` + + + +##### Example + + + +```json +{ + "input": { + "id": "480ef339-7842-4501-a905-923fc1339cef", + } +} +``` + + + +
+ +| Variable | Description | Required | +| --------- | -------------------------------------- | -------- | +| `id` | The ID of the peer you wish to delete. | Y | + +
+ + + +```json +{ + "data": { + "deletePeer": { + "success": true, + } + } +} +``` + + diff --git a/packages/documentation/src/content/docs/overview/concepts/interledger.mdx b/packages/documentation/src/content/docs/overview/concepts/interledger.mdx index 580b32bd3d..37e2075eae 100644 --- a/packages/documentation/src/content/docs/overview/concepts/interledger.mdx +++ b/packages/documentation/src/content/docs/overview/concepts/interledger.mdx @@ -18,7 +18,7 @@ Each packet represents a conditional IOU which affects financial accounting bala Interledger itself is a network of computers that enables sending payment messages across payment networks. Each computer on the network is called a node. -For two nodes on the Interledger network to exchange ILP packets with one another, the two nodes must be peers. There are a number of [requirements](/admin/manage-peering) that both you and your potential peer must meet in order to form a peering relationship. +For two nodes on the Interledger network to exchange ILP packets with one another, the two nodes must be peers. There are a number of [requirements](/integration/requirements/peers#prerequisites) that both you and your potential peer must meet in order to form a peering relationship. Since the purpose of peering is to facilitate payments, which often involves extending lines of credit, your peer should be someone you trust. We strongly recommend you and your potential peer define your expectations and outline your agreements in a legally-binding document peering with one another.