Skip to content
GitHub

Peers

To join the Interledger network and be able to send and receive payments, you must add one or more peers 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 capabilities 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.

Perform prerequisites

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

Run an Interledger connector

While you and your peer may run any implementation of an Interledger connector such as the TypeScript implementation, it is recommended to use Rafiki.

Agree on an asset

Both you and your peer must 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

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

The connection endpoint will be a url that the other peer will send packets to.

Exchange auth tokens for the connection endpoint

Incoming authtokens allow you to authenticate that packets sent from your peer originated from your peer’s Interledger connector and were not tampered en route. The outgoing authtoken allows your peer to authenticate that received packets originated from your Interledger connector and were not tampered with en route. The use of auth tokens is not required when autopeering with the Test Network.

Agree on a settlement mechanism

The settlement mechanism you both agree to use is what facilitates the transfer of actual funds between you and your peer. Neither Interledger nor Rafiki provide a settlement mechanism.

Perform optional prerequisites

Deposit an initial liquidity for your peer

While you may deposit an initiaLiquidity for your peer, you can deposit liquidity later using the depositPeerLiquidity mutation.

Define a maxPacketAmout value

The maxPacketAmount 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, you must add an asset to your Rafiki instance before creating a peering relationship. To learn how to add an asset, refer to Assets.

Add a peer

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

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

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

mutation UpdatePeer($input: UpdatePeerInput!) {
  updatePeer(input: $input) {
    peer {
      id
      name
      http {
        outgoing {
          authToken
          endpoint
        }
      }
      maxPacketAmount
      liquidityThreshold
    }
  }
}

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 starting this irreversible operation.

You can only delete a peer if no payments were sent 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 throws 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.

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