IPC Explorer

The goal of this project was to build a minimum viable product (MVP) of the IPC explorer. See what's next after the MVP.

InterPlanetary Consensus (IPC) is a revolutionary blockchain technology that powers planetary-scale web3 apps.

You can learn more about this technology at https://www.ipc.space.

Using IPC Explorer you can:

• Browse subnets.
• View subnet configuration.
• View the last committed bottom-up checkpoint of a subnet.
• View subnet genesis validators.
• View recent subnet deposits.
• View recent subnet withdrawals.
• View recent subnet transactions.

Check out IPC Explorer website or run the application locally.

How it's made

• To narrow the scope of the MVP the decision was made to not build an indexing backend at this stage.
• The application relies on public Filecoin RPC providers.
• IPC Explorer is a single page application (SPA) built using React.
• The application uses ethers.js to:
  • Call various methods of the IPC Subnet Actor (ISA) and the IPC Gateway Actor (IGA) smart contracts to collect various information about subnets.
  • Fetch blocks, transactions, and events from the root network and its child subnets.

Known issues and limitations

• Listing subnet withdrawals may not work. It relies on the NewBottomUpMsgBatch event of the IPC Gateway Actor smart contract. But for some reason, I do not observe such events via a local subnet RPC during manual testing.
• Connecting to a subnet RPC provider is subject to same-origin policy. Therefore, you can only connect to a local subnet RPC provider from a locally running application. Connecting to a public subnet RPC provider is possible if the provider explicitly allows it by setting corresponding CORS headers.
• Not displaying when the last bottom-up checkpoint of a subnet was committed to the parent. Finding in what parent block a subnet committed its last bottom-up checkpoint is inefficient without having an indexing backend. In the worst-case scenario, you'd have to scan the parent from its current block down to the subnet's genesis block to find the last checkpoint transaction.
• L3+ subnets are not supported. Nested subnets would require different application architecture and more sophisticated UX. It is simply out of scope of the MVP.

Why building from scratch?

Since the Filecoin Virtual Machine used by IPC is an EVM-compatible runtime, you may wonder, can't we just use some existing open-source blockchain explorer like Blockscout? And the short answer is yes, we can. But, the user experience will be poor out-of-the-box.

• Blockscout doesn't support simultaneously connecting to multiple RPC providers. This means you either look at a parent or a child IPC network at a time. Or have to deploy a separate Blockscout instance for every subnet. Which seems inefficient.
• Blockscout is a general-purpose blockchain explorer and knows nothing about IPC subnets. Even if you upload and verify IPC-specific smart contracts into it, this will improve visibility into subnets just a little. And the UX will remain poor. Because you still need to manually call a set of Gateway and Subnet Actor methods to gather info about subnets.

So for the best visibility into subnets and a good user experience you either fork and extend something like Blockscout or build your own IPC explorer from scratch. For this MVP I chose the latter.

What's next?

Before the IPC General Availability launch (planned for 2024 Q3) I want to build a production-ready IPC explorer. The key difference from the current MVP will be having an indexing backend. This backend will greatly improve the UX of the explorer and enable new features. To name a few:

• Full history of transactions, messages, events, etc. is available and searchable.
• Various charts and analytics based on real-time and historical data.
• Quicker application load times.

Another useful feature will be the ability to connect your Metamask wallet to a subnet.

Development

Running locally

First, clone the repository and cd into its directory:

git clone git@github.com:31z4/ipc-explorer.git
cd ipc-explorer

Now, simply run the following commands to install all required packages and run a development server:

npm install
npm run dev

The application is running at http://localhost:5173.

Connecting to a local subnet RPC

You can only connect to a local subnet RPC from a locally running application due to same-origin policy. You also need a workaround because Fendermint Ethereum API Facade doesn't set CORS headers that would allow such connection from your browser.

The suggested workaround is to run a reverse proxy that sets required CORS headers. In the following instruction, it's assumed that you're already running a subnet with Ethereum API Facade listening on http://localhost:8545. This should be the case if you followed the official instruction about deploying a subnet.

1. Install mitmproxy.
2. Run it with a custom cors.py module:

mitmdump --mode reverse:http://localhost:8545 --listen-host localhost --listen-port 9545 -s mitmproxy/cors.py

Now you should be able to connect to subnet RPC from the locally running application. Note the non-standard provider URL (which is our reverse proxy) that you must enter after you click on the "Connect" button in the application:

http://localhost:9545

Manual testing using ipc-cli

The following is a simplified and limited version of the official documentation about deploying a subnet. If you need a fully operational subnet follow the official instructions instead.

1. First, you need to build a Docker image for ipc-cli:

make build-ipc-cli-docker

2. Initialize your ipc-cli config:

mkdir .ipc

cat << EOF > .ipc/config.toml
keystore_path = "~/.ipc-keystore"

[[subnets]]
id = "/r314159"

[subnets.config]
network_type = "fevm"
provider_http = "https://api.calibration.node.glif.io/rpc/v1"
gateway_addr = "`curl -s https://raw.githubusercontent.com/consensus-shipyard/ipc/cd/contracts/deployments/r314159.json | jq -r '.gateway_addr'`"
registry_addr = "`curl -s https://raw.githubusercontent.com/consensus-shipyard/ipc/cd/contracts/deployments/r314159.json | jq -r '.registry_addr'`"
EOF

Note the non-default keystore_path. This is the path where a Docker volume will be mounted to persist wallet keys for the ipc-cli container.

3. Set up a new wallet.

make ipc-cli-new-wallet

Make note of the address of the wallet you created. And set it as your default wallet:

wallet=NEW_WALLET_ADDRESS make ipc-cli-set-default-wallet

4. Go to the Calibration faucet and get some funds sent to this new wallet.

Create a child subnet

make ipc-cli-create-subnet

Make a note of the address of the subnet you created.

Join the subnet from your validator (i.e., the wallet you created earlier)

First, get the public key of your wallet and note it down:

wallet=NEW_WALLET_ADDRESS make ipc-cli-wallet-pub-key

Now, join the subnet:

subnet=NEW_SUBNET_ID pubkey=NEW_WALLET_PUBKEY make ipc-cli-join-subnet

Deposit funds

subnet=NEW_SUBNET_ID amount=0.01 make ipc-cli-fund

Withdraw funds

Withdrawing funds requires a running subnet.