Peers

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 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

Note

Peering is not required unless you want to participate in transactions with another ASE on the Interledger network. For foundational peering concepts, refer to the Peers section of Interledger Concepts.

Before adding a peer, you and the account servicing entity you intend to peer with must both:

• Run an implementation of an Interledger connector (ideally Rafiki).
• Agree on an asset 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.
• Exchange static Interledger (ILP) addresses with your peer. Your ILP address is self-assigned during Rafiki setup and stored locally as the ILP_ADDRESS environment variable for the backend service.
• 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.

Optional settings

• Deposit an initialLiquidity for your peer. Liquidity can also be deposited later using the depositPeerLiquidity mutation.
• Define a maxPacketAmount value, which specifies the maximum packet size you are willing to accept from the peer. Your peer’s maxPacketAmount value does not need to match, as this value is independently set by each ASE. If omitted, payments will not be broken into smaller packets.

Set up peering in Rafiki

The basic workflow of setting up a peering relationship starts with adding the agreed upon asset and then adding a peer.

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.

Add a peer

After adding an asset, add a peer using the createPeer GraphQL mutation.

createPeer

Example createPeer Mutation

mutation CreatePeer($input: CreatePeerInput!) {
  createPeer(input: $input) {
    code
    success
    message
    peer {
      id
      asset {
        code
        scale
      }
      staticIlpAddress
      name
    }
  }
}

Example

Example JSON request

{
  "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": <optionally, an intial amount of liquity to provision. Liquidity can also be deposited via the `DepositPeerLiquidity` mutation>
  }
}

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	An array of auth tokens accepted by your Rafiki instance for authenticating incoming packets from your peer.	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 auth token presented to your peer for authenticating outgoing packets from your Rafiki instance.	Y
initialLiquidity	Initial amount of liquidity to deposit for peer. Liquidity can also be deposited using the DepositPeerLiquidity mutation.	N

Example JSON response

{
  "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"
      }
    }
  }
}

Manage peers

Once a peer has been added to your Rafiki instance, there is minimal ongoing management required. Most peer interactions focus on monitoring liquidity and ensuring smooth payment flows. In rare cases, you may need to update a peer’s configuration due to changes in their technical details or remove a peer created in error, as long as no payments have been exchanged. These actions help ensure your Rafiki instance stays up to date with operational changes.

Edit a peer

How to edit a peer

Occasionally, you may need 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

Example updatePeer Mutation

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.

Example JSON request

{
  "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 size you are willing to accept from the peer.	N
liquidityThreshold	A webhook event will notify the Account Servicing Entity if peer liquidity falls below this new value.	N

Example JSON response

{
  "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

How to 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

Example deletePeer Mutation

mutation DeletePeer($input: DeletePeerInput!) {
  deletePeer(input: $input) {
    success
  }
}

Example

Example JSON request

{
  "input": {
    "id": "480ef339-7842-4501-a905-923fc1339cef"
  }
}

Variable	Description	Required
id	The ID of the peer you wish to delete.	Y

Example JSON response

{
  "data": {
    "deletePeer": {
      "success": true
    }
  }
}