Neutrino Elements

Neutrino + Elements

Overview

Neutrino-elements is a set of useful packages and binaries that can be used to "watch" Liquid side-chain events.
It uses Compact Block Filter (BIP0158) to implement a light client for elements based networks.

Two packages, that works independently, are provided if you want to build your own light client:

• NodeService is a full node maintaining an up-to-date state of the block headers + compact filters. The NodeService writes down headers and filters in repositories.
  
• ScannerService uses filters and headers repositories to handle ScanRequest which aims to know if an outpoint (identified by its script) is spent or not.
  

Two binaries are provided if you want to use ready light client:

• neutrinod is a daemon that accepts websocket connections on which clients can send requests to watch for events related to wallet-descriptor
  neutrinod also exposes HTTP endpoint that supports adding webhooks to receive notifications when an event occurs.
  
• neutrino is a simple command line tool that can be used to watch Liquid side-chain events.
  

Local Development

Requirements

• Go (^1.17.*)
• Nigiri (^0.4.*)

Build neutrinod & neutrino CLI

make build-nd
make build-n

Run test

make test

Run neutrinod and postgres db inside Docker container

make dev

Run neutrinod and postgres db separately

• Run make pgcreatedb to create database inside postgres container
• Run(or use binaries) go run ./cmd/neutrinod/main.go to start neutrinod
• Run make wpkh to fund address with two transactions and get wpkh wallet descriptor
• Run go run ./cmd/neutrino/* subscribe --descriptor="{WPKH_DESCRIPTOR}" --block_height=0 --events=unspentUtxo to watch for events

Usage

Run neutrinod

./neutrinod

Config CLI

./neutrino config

Watch for events related to wallet-descriptor(websocket-{HOST:PORT}/neutrino/subscribe/ws)

./neutrino subscribe --descriptor="{WALLET_DESCRIPTOR}" --block_height={BLOCK_HEIGHT} --events=unspentUtxo

Add webhook(http)

curl -X POST http://localhost:8000/neutrino/subscribe/http \
   -H 'Content-Type: application/json' \
   -d '{"actionType":"register", "eventTypes":["unspentUtxo"], "descriptorWallet":"wpkh(037470e26cc774eca62ca19e1a182461a5f3d3680acbc593ce3f38cd142c26c03d)", "startBlockHeight":0, "endpointUrl":"http://127.0.0.1:62900"}'

API

Neutrinod can be used to subscribe to events related to wallet-descriptor using web-socket or by registrating webhook using HTTP.

Web-socket

To subscribe to events related to wallet-descriptor using web-socket connection, send below json :

{
    "actionType":"register", 
    "eventTypes":["unspentUtxo"], 
    "descriptorWallet":"{WALLET_DESCRIPTOR}", 
    "startBlockHeight":"{START_BLOCK_HEIGHT}", 
}

to the following endpoint:

/neutrino/subscribe/ws

HTTP

To register webhook, send bellow json :

{
  "actionType": "register",
  "eventTypes": ["unspentUtxo"],
  "descriptorWallet": "{WALLET_DESCRIPTOR}",
  "startBlockHeight": "{START_BLOCK_HEIGHT}",
  "endpointUrl": "{ENDPOINT_URL}"
}

to the following endpoint:

/neutrino/subscribe/http

Valid actionTypes: "register", "unregister"
Valid eventTypes: "unspentUtxo", "spentUtxo"

License

MIT - see the LICENSE.md file for details

Acknowledgments

• Neutrino - Light bitcoin client
• Compact Block Filters for Light Clients - BIP158
• tinybit