Introduction

Looking for a quick way to bootsrap a development environment for building applications on bitcoin and liquid? Look no further! In this tutorial we will be looking at Nigiri, a command line interface that manages a selection of docker cointainers (batteries included) to bootstrap a ready-to-use bitcoin regtest development environment, with a bitcoin node, electrum explorer both backend and frontend user interfaces and block explorers.

Getting started the quick way

Prerequisites

You will need a docker enabled host. https://www.docker.com/

Installing nigiri

  1. Download and install the nigiri command line interface

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

    NOTE: This will create a directory called ~/.nigiri with files for {bitcoin|elements}.conf respectively which you can modify.

  2. Close and re-open your terminal

    This step is required to initialise a terminal with the nigiri cli in your environment.

  3. Start Bitcoin and Liquid using nigiri cli

    $ nigiri start --liquid

    After running this command, you should see the following output.

    Creating bitcoin ... done
Creating liquid  ... done
Creating electrs        ... done
Creating electrs-liquid ... done
Creating chopsticks        ... done
Creating chopsticks-liquid ... done
Creating esplora           ... done
Creating esplora-liquid    ... done
Bitcoin services:
   esplora:       localhost:5000
   electrs:       localhost:3002
   electrs_rpc:   localhost:51401
   chopsticks:    localhost:3000
   peer:          localhost:18432
   node:          localhost:18433
Liquid services:
   electrs_rpc:   localhost:60401
   chopsticks:    localhost:3001
   peer:          localhost:7040
   node:          localhost:7041
   esplora:       localhost:5001
   electrs:       localhost:3012

That's it!

You can now visit http://localhost:5000 to inspect the Bitcoin blockchain or http://localhost:5001 for Liquid.

You can also invoke the bitcoin-cli and elements-cli by setting up the following aliases.

$ alias bcli='docker exec -it bitcoin bitcoin-cli -datadir=config'
$ bcli getblockchaininfo

$ alias ecli='docker exec -it liquid elements-cli -datadir=config'
$ ecli getblockchaininfo

Building nigiri from scratch

Prerequisites

Ingredients

Directions

Preparation Time: 5 min Cooking Difficulty: Easy

  1. Clone the repo:

    $ git clone https://github.com/vulpemventures/nigiri.git

  2. Enter project directory and install dependencies:

    $ bash scripts/install

    NOTE: This will create a directory called ~/.nigiri with files for {bitcoin|elements}.conf respectivly which you can modify.

  3. Building the nigiri binary

    # MacOSX
$ bash scripts/build darwin amd64
# Linux 
$ bash scripts/build linux amd64

     Done! You should be able to find the binary in the local `./build` folder. You will need to change the permissions to execute "chmod 755 ./build/nigiri-darwin-amd64" or "./build/nigiri-linux-amd64" and move/rename it binary to your PATH (`mv ./build/* /usr/local/bin/` ).

  4. Clean
    Remember to always clean Nigiri before running install to upgrade to a new version.

    $ bash scripts/clean

Tasting

At the moment bitcoind, elements and electrs are started on regtest network.

  • Start nigiri:
$ nigiri start

Use the --liquid flag to let you do experiments with the Liquid sidechain. A liquid daemon and a block explorer are also started when passing this flag.

  • Stop nigiri:
$ nigiri stop

Use the --delete flag to not just stop Docker containers but also to remove them and delete the config file and any new data written in volumes.

  • Check the logs of Bitcoin services
# Bitcoind
$ nigiri logs node
# Electrs
$ nigiri logs electrs
# Chopsticks
$ nigiri logs chopsticks
  • Check the logs of Liquid services
# Elementsd
$ nigiri logs node --liquid
# Electrs Liquid
$ nigiri logs electrs --liquid
# Chopsticks Liquid
$ nigiri logs chopsticks --liquid
  • Use the Bitcoin CLI inside the box
$ alias bcli='docker exec -it bitcoin bitcoin-cli -datadir=config'
$ bcli getblockchaininfo
  • Use the Elements CLI inside the box
$ alias ecli='docker exec -it liquid elements-cli -datadir=config'
$ ecli getblockchaininfo

Nigiri uses the default directory ~/.nigiri to store configuration files and docker-compose files.
To set a custom directory use the --datadir flag.

Run the help command to see the full list of available flags.

nigiri --help
Nigiri lets you create your dockerized environment with a bitcoin and optionally a liquid node + block explorer powered by an electrum server for every network

Usage:
  nigiri [command]

Available Commands:
  help        Help about any command
  logs        Check service logs
  start       Build and start Nigiri
  stop        Stop and/or delete nigiri

Flags:
      --datadir string   Set nigiri default directory (default "/Users/gr0kchain/.nigiri")
  -h, --help             help for nigiri
      --version          version for nigiri

Use "nigiri [command] --help" for more information about a command.

Nutrition Facts

Nigiri offers a JSON HTTP proxy passtrough that adds to the explorer handy endpoints like /faucet and automatic block generation when calling the /tx pushing a transaction.

You can have Elements too with the --liquid flag.

Are you looking to spin-up Nigiri in Travis or Github Action? Look here

Chopsticks service exposes on port 3000 (and on 3001 if started with --liquid flag) all Esplora's available endpoints and extends them with the following:

Bitcoin & Liquid

  • POST /faucet which expects a body { "address": <receiving_address> }
  • POST /tx has been extended to automatically mine a block when is called.

Liquid only

  • POST /mint which expects a body {"address": "ert1q90dz89u8eudeswzynl3p2jke564ejc2cnfcwuq", "quantity": 1000, "name":"VULPEM", "ticker":"VLP"}
  • POST /registry to get extra info about one or more assets like name and ticker which expects a body with an array of assets {"assets": ["2dcf5a8834645654911964ec3602426fd3b9b4017554d3f9c19403e7fc1411d3"]}

Conclusion

In this tutorial we had a look at setting up a developer environment using nigiri cli.

Be sure to checkout the team behind this awesome initiative here.

https://vulpem.com/

They also have a hosted version of nigiri here.
https://nigiri.vulpem.com/

And of course the source code on github.

https://github.com/vulpemventures/nigiri