Localhost RPC Endpoints

Using localhost RPC Endpoints in Backpack

This is intended to be a non-technical explanation for why the usage of http://localhost:XXXX or http://127.0.0.1:XXXX as a custom RPC endpoint within Backpack (and some other wallets) does not work.

Background

When engineers want to test or develop against on-chain data or programs from within an isolated environment, running an RPC on localhost is often the choice.

This works until peripheral systems and applications that are not local, also need to connect or send requests to this localhost runtime.

Problem

Using the addresses localhost and 127.0.0.1 from a networking perspective are like referring to yourself (i.e. using the words me or I).

Backpack, along with some other mainstream wallets, read the asset holdings of your addresses/wallets from remote servers and APIs that do not live or execute in the client. When you log into Backpack, the mobile or web application makes a request to a remote server asking for information about your wallet: balances, transaction history, NFT holdings, etc.

When you set a custom RPC endpoint within the Backpack wallet application, it is used as a stand-in for the defaults that are pre-configured in a couple of different places:

  1. Transaction serialization and sending

  2. Health checks

  3. Blockchain/network metadata retrieval

  4. Telling the Backpack API to read data directly from on-chain instead of from other faster data sources

Setting a localhost RPC can affect the first three in different ways, but #4 is important. Since the Backpack API is a remote server, when its told to fetch on-chain data from an RPC endpoint at http://localhost:XXXX, what it thinks is:

"There is a blockchain RPC node that I am running and I should send it requests."

This is obviously not correct, because to the server, localhost isn't a user's laptop running the RPC node potentially in a different country. Instead, the custom RPC should always be set to a publicly accessible endpoint that doesn't reference any local or internal system networks or reserved names.

So how do I use my test RPC that is running on localhost?

Workaround

The key point is that the endpoint of the custom RPC needs to be publicly accessible.

There are lots of tools and applications out there that allow you to tunnel your applications running on localhost into the public space (a few examples):

...and lots of others.

These applications allow you to choose a port on your local internal network and expose it to the public internet via local tunneling with ephemeral public domain names that are reachable from external networks.

Using ngrok, all you need to do after creating and verifying an account is running the following command to setup a local tunnel for your RPC endpoint which you can these set the custom RPC endpoint in the wallet for:

$ ngrok http 8080 # whichever port number you want

Why do some dApps work without this?

These are some cases where, even without a localhost tunnel, setting the custom RPC endpoint to localhost may still work.

This is purely dependent on the implementation of dApps that you are connected to. If the website of dApp is programmed to run on-chain queries directly from the client code, then it will likely still work because the network requests to the RPC are actually being made from code that is executing in your browser, and thus within the same network space as your localhost RPC.

That is the one exception to need for local tunneling.

Last updated