🍣 Nigiri Bitcoin
Nigiri provides a command line interface that manages a selection of docker-compose batteries included to have a ready-to-use Bitcoin regtest development environment. Out of the box, you get:
- Bitcoin Node: A Bitcoin Core node running in regtest mode
- Electrum: Backend and frontend explorer for quick blockchain inspection
- Chopsticks: A JSON HTTP proxy that adds handy endpoints like
/faucet and automatic block generation
You can extend your setup with:
- Ark: A Bitcoin layer two implementation for scalable off-chain transactions
- Elements/Liquid sidechain with
--liquid flag
- Lightning Network nodes with
--ln flag (Core Lightning, LND, and Taproot Assets)
No time to make a Nigiri yourself?
Pre-built binary
- Download and install
nigiri command line interface
curl https://getnigiri.vulpem.com | bash
On Windows, you are heavily encouraged to make use of WSL. Ensure that Docker is configured to integrate and use WSL. Prepending most commands in this document with wsl is sufficient.
This will also install several configurable files, such as bitcoin.conf and elements.conf, that can be edited. These can be found browsing the following directory:
POSIX (Linux/BSD): ~/.nigiri
macOS: $HOME/Library/Application\ Support/Nigiri
Windows (WSL): ~/.nigiri
Windows: %LOCALAPPDATA%\Nigiri
Plan 9: $home/nigiri
- Launch Docker daemon (Mac OSX)
open -a Docker
You may want to Manage Docker as a non-root user
- Close and reopen your terminal, then start Bitcoin and Ark
nigiri start --ark
That’s it.
Go to http://localhost:5000 to quickly inspect the Bitcoin blockchain
Want more? Add Elements/Liquid, Lightning nodes, or Ark:
nigiri start --ark --liquid # Add Elements/Liquid sidechain
nigiri start --ark --ln # Add Lightning Network nodes
nigiri start --liquid --ln # Add both Liquid and Lightning
nigiri start --ark --liquid --ln # Add all features
Note for users of macOS Monterey and onward
Show more...
When trying to start Nigiri, you might get an error similar to the following:
Error response from daemon: Ports are not available: listen tcp 0.0.0.0:5000: bind: address already in use
exit status 1
This is due to AirPlay Receiver using port 5000, conflicting with Esplora trying to run using the very same port.
There are two ways to deal with this issue:
- Uncheck AirPlay Receiver in
System Preferences → Sharing → AirPlay Receiver
- Change Esplora’s port to something other than 5000. This can be done by changing it in docker-compose.yml found in your data directory. If you previously tried starting Nigiri getting an error – you might have to run
nigiri stop --delete before restarting it.
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.
-
Use the --ln flag to start a Core Lightning node, a LND node and a Tap daemon.
-
Use the --remember flag to save the currently used flags (like --liquid, --ln, --ark) so they are automatically applied on subsequent nigiri start calls without needing to specify them again.
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.
Forget remembered flags
nigiri forget
This command removes any flags previously saved using nigiri start --remember, causing future nigiri start calls to use default flags unless specified.
Generate and send bitcoin to given address
# Bitcoin
nigiri faucet <bitcoin_address>
## Fund the Core Lightning node
nigiri faucet cln 0.01
## Fund the LND node
nigiri faucet lnd 0.01
# Elements
nigiri faucet --liquid <liquid_address>
Send Liquid asset to given address
nigiri faucet --liquid <liquid_address> <amt> <liquid_asset>
Liquid only Issue and send a given quantity of an asset
nigiri mint <liquid_address> 1000 VulpemToken VLP
Broadcast a raw transaction and automatically generate a block
# Bitcoin
nigiri push <hex>
# Elements
nigiri push --liquid <hex>
Check the logs of Bitcoin services
# Bitcoind
nigiri logs bitcoin
# Electrs
nigiri logs electrs
# Chopsticks
nigiri logs chopsticks
Check the logs of Liquid services
# Elementsd
nigiri logs liquid
# Electrs Liquid
nigiri logs electrs-liquid
# Chopsticks Liquid
nigiri logs chopsticks-liquid
Check the logs of Lightning services
# Core Lightning
nigiri logs cln
# LND
nigiri logs lnd
Use the Bitcoin CLI inside the box
nigiri rpc getnewaddress "" "bech32"
bcrt1qsl4j5je4gu3ecjle8lckl3u8yywh8rff6xxk2r
Use the Elements CLI inside the box
nigiri rpc --liquid getnewaddress "" "bech32"
el1qqwwx9gyrcrjrhgnrnjq9dq9t4hykmr6ela46ej63dnkdkcg8veadrvg5p0xg0zd6j3aug74cv9m4cf4jslwdqnha2w2nsg9x3
Use the Core Lightning & LND CLIs inside the box
# Core Lightning
nigiri cln listpeers
# LND
nigiri lnd listpeers
# Tap (Taro)
nigiri tap assets list
Connect Core Lightning to LND
nigiri cln connect `nigiri lnd getinfo | jq -r .identity_pubkey`@lnd:9735
Open a channel between cln and lnd
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
Pay invoices between cln and lnd
nigiri lnd payinvoice `nigiri cln invoice 21000 $(date +%s) "test" | jq -r .bolt11`
nigiri cln pay `nigiri lnd addinvoice 21 | jq -r .payment_request`
Use the Ark CLI inside the box
# Check versions
nigiri ark --version # or -v
nigiri arkd --version # or -v
# Use the Ark client
nigiri ark config # Show wallet configuration
nigiri ark receive # Show receiving addresses
nigiri ark balance # Show wallet balance
# Configure the Ark daemon client
nigiri arkd wallet status # Show wallet status
nigiri arkd wallet create --password secret # Create a new wallet
nigiri arkd wallet unlock --password secret # Unlock the wallet
nigiri arkd wallet status # Verify ark wallet is set up
# Initialize the Ark client (only needed once)
nigiri ark init --network regtest --password secret --server-url localhost:7070 --explorer http://chopsticks:3000
Update the docker images
nigiri update
Nigiri uses the default directory ~/.nigiri to store configuration files and docker-compose files.
To set a custom directory use the --datadir flag or NIGIRI_DATADIR environment variable.
If both are present, --datadir takes precedence.
Run the help command to see the full list of available flags.
Make from scratch
Utensils
Ingredients
Directions
| Preparation Time: 5 min |
Cooking Difficulty: Easy |
git clone https://github.com/vulpemventures/nigiri.git
- Enter project directory and install dependencies:
make install
make build
Done! You should be able to find the binary in the local ./build folder. Give it permission to execute and move/rename into your PATH.
Remember to always clean Nigiri before running install to upgrade to a new version.
make clean
Nutrition Facts
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 it 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"]}
If you really do love Satoshi’s favourite dish like us at Vulpem Ventures, check the real recipe out and enjoy your own, delicious, hand made nigiri sushi.
![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)
评论