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.

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.

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

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 initial amount of liquidity 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 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.

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

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