Nigiri

To build Nigiri from the repository, ensure you have Docker (compose) and Go installed. Use make to manage the build process.

git clone https://github.com/vulpemventures/nigiri.git
make clean
make install
make build

Use nigiri start to launch the Bitcoin regtest environment. You can include various features using flags:

• --ark: Adds Ark (Bitcoin layer two).
• --liquid: Adds Elements/Liquid sidechain and a block explorer.
• --ln: Adds Lightning Network nodes (Core Lightning, LND, and Taproot Assets).
• --remember: Saves the currently used flags so they are automatically applied to future nigiri start calls.

To stop the environment, use nigiri stop. Use the --delete flag to also remove Docker containers and delete configuration files and volume data.

nigiri start --ark --liquid --ln
nigiri stop
nigiri stop --delete

You can install the nigiri command line interface using the following curl command. On Windows, it is highly recommended to use WSL and ensure Docker is configured to integrate with WSL.

curl https://getnigiri.vulpem.com | bash

The --remember flag allows you to persist your preferred Nigiri configuration. When used, Nigiri writes the active configuration to flags.json inside your datadir.

On future runs, Nigiri will attempt to load these saved flags. If you provide new flags in a subsequent command, they will override the saved ones. This is useful for maintaining complex setups (e.g., always running with --liquid --ln --ark) without typing them every time.

Nigiri uses a default directory to store configuration files (like bitcoin.conf and elements.conf) and docker-compose files. You can override this using the --datadir flag or the NIGIRI_DATADIR environment variable. If both are provided, the --datadir flag takes precedence.

Default Directories:

• POSIX (Linux/BSD): ~/.nigiri
• macOS: $HOME/Library/Application Support/Nigiri
• Windows (WSL): ~/.nigiri
• Windows: %LOCALAPPDATA%\Nigiri
• Plan 9: $home/nigiri

Nigiri provides a complete local development environment for Bitcoin and Lightning development, including Bitcoin Core, Liquid (Elements), various Lightning implementations (LND, CLN, Taproot Assets), block explorers (Electrs, Esplora, NBXplorer), and the Arkade stack.

To use this environment, you can use the provided docker-compose.yml file. The services are configured to run in a regtest network by default, making it ideal for local testing without real Bitcoin assets.

# Use the provided docker-compose.yml to spin up the Nigiri stack
docker-compose up

Nigiri provides a faucet command to quickly distribute funds to addresses in the regtest environment.

• Bitcoin: nigiri faucet <bitcoin_address>
• Core Lightning (CLN): nigiri faucet cln <amount>
• LND: nigiri faucet lnd <amount>
• Elements/Liquid: nigiri faucet --liquid <liquid_address>
• Liquid Assets: nigiri faucet --liquid <liquid_address> <amt> <liquid_asset>

nigiri faucet <bitcoin_address>
nigiri faucet cln 0.01
nigiri faucet lnd 0.01
nigiri faucet --liquid <liquid_address>
nigiri faucet --liquid <liquid_address> <amt> <liquid_asset>

To facilitate testing between Core Lightning (CLN) and LND, you can use the following workflow to connect them and open a channel.

# Connect CLN to LND
nigiri cln connect `nigiri lnd getinfo | jq -r .identity_pubkey`@lnd:9735

# Open channel
nigiri lnd openchannel --node_key=`nigiri cln getinfo | jq -r .id` --local_amt=100000
nigiri cln fundchannel `nigiri lnd getinfo | jq -r .identity_pubkey` 100000

Use the push command to broadcast a raw transaction. For Elements/Liquid, include the --liquid flag. This command also automatically triggers block generation.

nigiri push <hex>
nigiri push --liquid <hex>

You can execute commands directly inside the running services using nigiri rpc (for Bitcoin/Elements) or by calling the service CLI directly (for Lightning/Ark).

# Bitcoin RPC
nigiri rpc getnewaddress "" "bech32"

# Elements RPC
nigiri rpc --liquid getnewaddress "" "bech32"

# Lightning CLIs
nigiri cln listpeers
nigiri lnd listpeers
nigiri tap assets list

# Ark CLI
nigiri ark balance

In a Liquid-enabled environment, you can mint assets using the nigiri mint command.

nigiri mint <liquid_address> 1000 VulpemToken VLP