https://github.com/vulpemventures/neutrino-elements
https://github.com/vulpemventures/neutrino-elements
Last synced: 12 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/vulpemventures/neutrino-elements
- Owner: vulpemventures
- License: mit
- Created: 2021-11-30T13:51:11.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2022-09-19T08:19:59.000Z (over 3 years ago)
- Last Synced: 2025-06-30T15:57:02.368Z (12 months ago)
- Language: Go
- Size: 4.47 MB
- Stars: 3
- Watchers: 4
- Forks: 4
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Neutrino Elements
[](https://github.com/vulpemventures/neutrino-elements/actions/workflows/ci.yml)
[](https://pkg.go.dev/github.com/vulpemventures/neutrino-elements)
[](https://github.com/vulpemventures/neutrino-elements/releases/latest)
[](https://goreportcard.com/report/github.com/vulpemventures/neutrino-elements)
[](https://blockstream.info/address/3MdERN32qiMnQ68bSSee5CXQkrSGx1iStr)
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](https://elementsproject.org/) 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)
```sh
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 :
```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 :
```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](https://github.com/lightninglabs/neutrino)
* [Compact Block Filters for Light Clients - BIP158](https://github.com/bitcoin/bips/blob/master/bip-0158.mediawiki)
* [tinybit](https://github.com/Jeiwan/tinybit)