This is a monorepo for Bitcoin Oracle project, which aims to provide a tamper-proof, censorship-resistant, on-chain oracle for meta-protocols on Bitcoin.
For the backgound on the project, you may want to read our efforts to build an "Indexer of Indexers" for BRC20, the leading meta-protocol on Bitcoin.
The repo contains following apps:
- api-server
api-server
is a nodejs server that provides REST API for the project. It uses NestJS framework.
- bitcoin-sync
bitcoin-sync
is a worker that syncs bitcoin header info for quick access forvalidators
andrelayers
.
- relayer
relayer
is a used for submitting the proofs fromvalidator
to stacks-node.
- validator
validator
is a worker that validates meta-protocol events, bitcoin headers and submits the proofs toapi-server
.
- [TODO: add instructions for running validator in docker]
direnv
This project uses direnv to manage environment variables. It also modified the PATH variable in project.
Following description assuming that you have installed direnv and have it configured in your shell. Noting that ./node_modules/.bin
is added into $PATH.
asdf
.tool-versions
file contains list of tools and their versions used in project. Use asdf to install them with asdf install
.
nx
This project uses Nx to manage monorepo. nx is installed as devDependency in project.
With direnv, you can use nx
command directly without npx nx
.
/tools/bin directory
./tools/bin folder contains the custom development scripts, such as:
dev-database
:- starts local database
- it will create the database and run the migrations
dev-stacks
:- starts local stacks-node and stacks-node-api
- it will deploy the contracts and run setup transactions
direnv allow
pnpm install
Create .envrc.override
file in project root directory and add set necessary environment variables, such as:
export OK_ACCESS_KEY=""
export BIS_ACCESS_KEY=""
export STACKS_VALIDATOR_ACCOUNT_ADDRESS=""
export STACKS_VALIDATOR_ACCOUNT_SECRET=""
dev-database
dev-stacks
nx serve api-server
nx serve bitcoin-sync
nx serve validator
nx serve relayer
Validator
under packages/apps/validator folder is a worker that validates meta-protocol events, bitcoin headers and submits the proofs to api-server
.
It dynamically loads the module which implements the ValidatorProcessInterface
interface.
An off-chain indexer who wants to participate as a validator
must implement the follwing interface, which is then loaded by a validator
worker.
export abstract class ValidatorProcessInterface {
abstract processBlock$(block: number): Observable<unknown>;
}
Examples
Watcher API returns the debug information. The endpoint is ${HOST}/debug/query
. The query parameter is defined in RequestQuery as follow:
tx_id: Buffer;
tx_hash: Buffer;
output: bigint;
satpoint: bigint;
from_address: string;
to_address: string;
from: Buffer;
to: Buffer;
tick: string;
amt: bigint;
order_hash: Buffer;
signature: Buffer;
signer: string;
height: bigint;
stacks_tx_id: Buffer;
block_hash: Buffer;
block_header: Buffer;