Cuiloa

Cuiloa (opens in a new tab) is a block explorer for navigating and inspecting data on Penumbra (opens in a new tab). While Penumbra is a fully private proof-of-stake network, Cuiloa allows you to explore the public facets of the Penumbra chain. Beyond just blocks and transactions, Cuiloa lets you explore staking, governance, and DEX activity along with Penumbra's cross-chain interactions via the Inter-Blockchain Communication (IBC) interoperability protocol, including established IBC clients running on Penumbra and recent IBC packets.

Deployment

Assuming you have cloned and entered the repository...

Docker

For a dev instance of Cuiloa, a docker compose file is provided. Simply run:

docker compose up

Then navigate to http://localhost:3000 (opens in a new tab) to view a development instance of the app.

Cuiloa will soon have a production ready image that can be deploy in a standard docker (or podman) workflow. Until then, please checkout manual configuration below.

Manual Deployment

In addition to a local Penumbra Node and configured CometBFT indexer (more on that below), you will need to have recent version of node, npm, and postgresql installed on the machine you are building and running Cuiloa.

PostgreSQL

With a modern version of PostgreSQL, create a database and initialize it with the schema file provided by cometbft here (opens in a new tab). Assuming you've created a database $DB_NAME and you have user permissions for the database, You can load a schema file using psql with the following command:

psql -d $DB_NAME -f schema.sql

This will be our indexer that the block explorer uses for accessing information on blocks, events, and transactions that occur on the chain.

With the database initialized, create an .env file with the database's URI, i.e.:

DATABASE_URL="postgresql://DB_USER:DB_PASSWORD@localhost:DB_PORT/DB_NAME?sslmode=disable"

You will also need this information for the config.toml file that cometbft will be initialized with when creating your own full node. More on that below.

Penumbra

You need to have a full node setup with penumbra (including cometbft) as detailed here (opens in a new tab). Alternatively, you can configure a full node on a devnet as explained here (opens in a new tab). In either case, you need to modify the config.toml file that is created by pd after generating your configuration files.

config.toml should be found under $HOME/.penumbra/network_data/node0/cometbft/config/. In this file, there is a heading [tx_index] with the configuration variable of indexer = "kv". Using the URI of the database you created with PostgreSQL from the previous section, you need to update the section under [tx_index] to the following:

[tx_index]
indexer = "psql"
psql-conn = "$YOUR_DB_URI_HERE"

After you have updated this file, you should start the full node as instructed by the Penumbra guide. If everything was configured correctly, you should be able to open the database and inspect for Block and Transaction events. If there is no data, check the logs for cometbft for any errors with inserting data into the indexer.

Building Cuiloa

If you are only interested in running a development version of Cuiloa, you can simply run npm run dev at this point and head to localhost:3000 to view the application.

For a production build, ensure that the output option in next.config.js is either commented out or deleted unless you are building Cuiloa for an optimized image. If you are planning on running Cuiloa as an image, you need to follow NextJS's instructions (opens in a new tab) for correctly building and copying over its dependencies.

Assuming you are using a normal build on your machine, you can now run npm run build && npm run start. If everything has been configured correctly, you can visit localhost:3000 to view your local production release of Cuiloa.