Running a Provenance Local Node

This guide expands on the official Provenance documentation for running a local node. It is designed to be practical, copy/paste friendly, and focused on fast local setup for development, debugging, and analysis.

Official reference:

https://docs.provenance.io/build/tutorials/running-a-provenance-local-node

What you are setting up

A local provenanced node that:

Boots from a snapshot instead of syncing from genesis

Uses a known-good config bundle

Exposes RPC, gRPC, REST, and WebSocket endpoints locally

Can be used for:

CLI queries
block and event inspection
metadata / bank / custom module development
local indexers and backfills

Prerequisites

macOS or Linux

At least 300–500GB free disk space (SSD or NVMe strongly recommended)

curl, tar

provenanced binary matching the chain version

Recommended tools:

bash
brew install jq lz4 pv

1. Download a snapshot

Provenance snapshots are commonly hosted by High Stakes.

Snapshot index:

https://tools.highstakes.ch/snapshots/provenance

Download the most recent snapshot listed on that page.

Example:

bash
mkdir -p ~/provenance/localnode
cd ~/provenance/localnode

curl -L -o data.tar.gz <SNAPSHOT_URL>

Snapshots may be .tar.gz or .tar.lz4. Adjust extraction accordingly.

Optional sanity check:

bash
ls -lh data.tar.gz

2. Download the config bundle

The official tutorial provides a config.tar.gz that contains:

genesis.json

config.toml

app.toml

peer and seed configuration

Download it from the docs page and place it next to the snapshot:

bash
curl -L -o config.tar.gz <CONFIG_TAR_URL>

3. Install `provenanced`

Download the correct binary version from GitHub:

https://github.com/provenance-io/provenance/releases

Verify the version:

bash
provenanced version

⚠️ Binary version must match the snapshot/config version.
Mismatches often cause app-hash or migration errors.

4. Create the node home and extract data

The standard home directory layout:

plain text
provhome/
├── data/
├── wasm/
└── config/

Extract snapshot

bash
mkdir -p provhome/config
tar -xzf data.tar.gz -C provhome

Extract config

bash
tar -xzf config.tar.gz -C provhome/config

Verify structure:

bash
ls provhome
ls provhome/config

You should see:

data/

config.toml

app.toml

genesis.json

5. Start the node

bash
provenanced start --home provhome

Useful variants:

bash
# more readable logs
provenanced start --home provhome --log_level info

# capture logs
provenanced start --home provhome 2>&1 | tee provhome/provenanced.log

6. Verify node health

RPC status

bash
curl -s localhost:26657/status | jq '.result.sync_info'

Expected behavior:

catching_up: true initially

Eventually switches to false

Point CLI at local node

bash
provenanced config node tcp://localhost:26657

Test queries:

bash
provenanced q node-info
provenanced q bank total

7. Common configuration tuning

Pruning (disk vs history)

Edit provhome/config/app.toml:

default – balanced

nothing – full history (large disk)

everything – minimal disk

Changing pruning usually requires reloading from snapshot.

Event indexing

Edit provhome/config/config.toml:

transaction indexing on/off

indexed event attributes

For heavy querying, many teams rely on an external indexer instead of full local indexing.

8. Troubleshooting

App hash mismatch

Common causes:

wrong binary version

snapshot/config mismatch

corrupted download

Fix:

bash
rm -rf provhome/data
# re-extract snapshot and config

Ports already in use

Default ports:

RPC: 26657

P2P: 26656

Find conflicts:

bash
lsof -i :26657
lsof -i :26656

Slow catch-up

Snapshot is too old

Disk IOPS too low

Poor peer connectivity

Solutions:

newer snapshot

NVMe storage

verify peers in config.toml

9. One-shot setup script

bash
#!/usr/bin/env bash
set -euo pipefail

HOME_DIR="${1:-provhome}"
SNAPSHOT="${2:-data.tar.gz}"
CONFIG="${3:-config.tar.gz}"

mkdir -p "$HOME_DIR/config"
tar -xzf "$SNAPSHOT" -C "$HOME_DIR"
tar -xzf "$CONFIG" -C "$HOME_DIR/config"

provenanced start --home "$HOME_DIR"

Next steps

Query balances, metadata, and module state

Inspect blocks and events

Stream live blocks via WebSocket

Build local indexers and backfill jobs