kylefang/bitcoin-indexer
1
0
Fork 0
mirror of https://github.com/alexgo-io/bitcoin-indexer.git synced 2026-04-30 04:35:04 +08:00
Code Issues Packages Projects Releases Wiki Activity

Updated stacks commands and improved formatting for consistency

Browse Source
This commit is contained in:
Lavanya Kasturi
2023-04-18 17:18:11 -05:00
parent 38a915c73e
commit dac35e9136
6 changed files with 83 additions and 115 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/faq.md
View File

@@ -2,7 +2,7 @@
title: FAQ's
---
# Frequently Asked Questions
# FAQ's
#### **Can Chainhooks target both Bitcoin and stacks?**

4
docs/getting-started.md
View File

@@ -2,11 +2,11 @@
title: Getting Started
---
# Install Chainhook
# Getting Started
You can install chainhook from the source by following this guide.
## Install from source
## Install Chainhook from source
Chainhook can be installed from the source by following the steps below:

4
docs/how-to-guides/how-to-run-chainhook-as-a-service.md
View File

@@ -2,7 +2,7 @@
title: Run chainhook as a Service
---
## Run `chainhook` as a service for streaming new blocks
# Run `chainhook` as a service for streaming new blocks
`chainhook` can be run as a background service for streaming and processing new canonical blocks appended to the Bitcoin and Stacks blockchains.
@@ -22,4 +22,4 @@ $ chainhook service start --config-path=./path/to/config.toml
$ chainhook service start --predicate-path=./path/to/predicate-1.json --start-http-api --config-path=./path/to/config.toml
```
A comprehensive OpenAPI specification explaining how to interact with the Chainhook REST API can be found [here](./docs/chainhook-openapi.json).
A comprehensive OpenAPI specification explaining how to interact with the Chainhook REST API can be found [here](../chainhook-openapi.json).

18
docs/how-to-guides/how-to-use-chainhook-with-bitcoin.md
View File

@@ -2,7 +2,11 @@
title: Use Chainhook with Bitcoin
---
# Guide to `if_this` / `then_that` predicate design
# Use chainhook with Bitcoin
The following guide helps you define predicates to use chainhook with Bitcoin.
## Guide to `if_this` / `then_that` predicate design
To get started with Bitcoin predicates, we can use the `chainhook` to generate a template:
@@ -10,7 +14,7 @@ To get started with Bitcoin predicates, we can use the `chainhook` to generate a
$ chainhook predicates new hello-ordinals.json --bitcoin
```
The above command generates a JSON file that looks like this:
The above command generates a hello-ordinals.json file that looks like this:
```
{
@@ -223,7 +227,7 @@ Append events to a file through the filesystem. Convenient for local tests. The
}
```
### Additional configuration knobs available
## Additional configuration knobs available
```json
// Ignore any block before the given block:
@@ -249,7 +253,7 @@ Append events to a file through the filesystem. Convenient for local tests. The
```
### Putting all the above configurations together
## Putting all the above configurations together
Retrieve and HTTP Post to `http://localhost:3000/api/v1/wrapBtc` the five first transfers to the p2wpkh `bcrt1qnxk...yt6ed99jg` address of any amount, occurring after block height 10200.
@@ -280,7 +284,7 @@ Retrieve and HTTP Post to `http://localhost:3000/api/v1/wrapBtc` the five first
}
```
### Another example
## Another example
A specification file can also include different networks. In this case, the chainhook will select the predicate corresponding to the network it was launched against.
@@ -324,7 +328,7 @@ A specification file can also include different networks. In this case, the chai
```
### Guide to local Bitcoin testnet / mainnet predicate scanning
## Guide to local Bitcoin testnet / mainnet predicate scanning
To scan the Bitcoin chain with a given predicate, a `bitcoind` instance with access to the RPC methods `getblockhash` and `getblock` must be accessible. The RPC calls latency will directly impact the speed of the scans.
@@ -386,7 +390,7 @@ $ chainhook config new --testnet
$ chainhook predicates scan ./path/predicate.json --config=./Testnet.toml
```
### Tips and tricks
## Tips and tricks
To optimize your experience with scanning, the following are a few knobs you can play with:

168
docs/how-to-guides/how-to-use-chainhook-with-stacks.md
View File

@@ -2,17 +2,21 @@
title: Use chainhook with Stacks
---
# Guide to `if_this` / `then_that` predicate design
# Use chainhook with Stacks
To get started with Bitcoin predicates, we can use the `chainhook` to generate a template:
The following guide helps you define predicates to use chainhook with Stacks.
## Guide to `if_this` / `then_that` predicate design
To get started with Stacks predicates, we can use the `chainhook` to generate a template:
```bash
$ chainhook predicates new hello-ordinals.json --bitcoin
$ chainhook predicates new hello-arkadiko.json --stacks
```
## `if_this` and `then_that` specifications
The current `bitcoin` predicates support the following `if_this` constructs:
The current `stacks` predicates support the following `if_this` constructs:
Get any transaction matching a given txid `txid` mandatory argument admits:
- 32 bytes hex encoded type. Example:
@@ -202,7 +206,7 @@ Append events to a file through the filesystem. Convenient for local tests. The
}
```
### Additional configuration knobs available
## Additional configuration knobs available
```json
// Ignore any block before the given block:
@@ -228,144 +232,104 @@ Append events to a file through the filesystem. Convenient for local tests. The
```
:::tip
### Putting all the above configurations together
To optimize your experience with scanning, developers have a few knobs they can play with:
- Use of adequate values for `start_block` and `end_block` in predicates will drastically improve the speed.
Retrieve and HTTP Post to `http://localhost:3000/api/v1/wrapBtc` the five first transfers to the p2wpkh `bcrt1qnxk...yt6ed99jg` address of any amount, occurring after block height 10200.
:::
## Putting all the above configurations together
Retrieve and HTTP Post to `http://localhost:3000/api/v1/wrapBtc`. The five first transfers to the p2wpkh `bcrt1qnxk...yt6ed99jg` address of any amount occurring after block height 10200.
```json
{
"chain": "bitcoin",
"chain": "stacks",
"uuid": "1",
"name": "Wrap BTC",
"name": "Lorem ipsum",
"version": 1,
"networks": {
"testnet": {
"if_this": {
"scope": "outputs",
"p2wpkh": {
"equals": "bcrt1qnxknq3wqtphv7sfwy07m7e4sr6ut9yt6ed99jg"
}
},
"then_that": {
"http_post": {
"url": "http://localhost:3000/api/v1/transfers",
"authorization_header": "Bearer cn389ncoiwuencr"
}
},
"start_block": 10200,
"expire_after_occurrence": 5,
"if_this": {
"scope": "print_event",
"contract_identifier": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.monkey-sip09",
"contains": "vault"
},
"then_that": {
"http_post": {
"url": "http://localhost:3000/api/v1/vaults",
"authorization_header": "Bearer cn389ncoiwuencr"
}
},
"start_block": 10200,
"expire_after_occurrence": 5,
}
}
}
```
### Another example
## Another example
A specification file can also include different networks. In this case, the chainhook will select the predicate corresponding to the network it was launched against.
```json
{
"chain": "bitcoin",
"chain": "stacks",
"uuid": "1",
"name": "Wrap BTC",
"name": "Lorem ipsum",
"version": 1,
"networks": {
"testnet": {
"if_this": {
"scope": "ordinals_protocol",
"operation": "inscription_feed"
},
"then_that": {
"http_post": {
"url": "http://localhost:3000/api/v1/ordinals",
"authorization_header": "Bearer cn389ncoiwuencr"
}
},
"start_block": 10200,
"if_this": {
"scope": "print_event",
"contract_identifier": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.monkey-sip09",
"contains": "vault"
},
"then_that": {
"http_post": {
"url": "http://localhost:3000/api/v1/vaults",
"authorization_header": "Bearer cn389ncoiwuencr"
}
},
"start_block": 10200,
"expire_after_occurrence": 5,
},
"mainnet": {
"if_this": {
"scope": "ordinals_protocol",
"operation": "inscription_feed"
},
"if_this": {
"scope": "print_event",
"contract_identifier": "SP456HQKV0RJXZFY1DGX8MNSNYVE3VGZJSRT459863.monkey-sip09",
"contains": "vault"
},
"then_that": {
"http_post": {
"url": "http://my-protocol.xyz/api/v1/ordinals",
"authorization_header": "Bearer cn389ncoiwuencr"
}
"http_post": {
"url": "http://my-protocol.xyz/api/v1/vaults",
"authorization_header": "Bearer cn389ncoiwuencr"
}
},
"start_block": 90232,
"expire_after_occurrence": 5,
}
}
}
```
### Guide to local Bitcoin testnet / mainnet predicate scanning
## Guide to local Stacks testnet / mainnet predicate scanning
To scan the Bitcoin chain with a given predicate, a `bitcoind` instance with access to the RPC methods `getblockhash` and `getblock` must be accessible. The RPC calls latency will directly impact the speed of the scans.
Developers can test their Stacks predicates without spinning up a Stacks node.
To date, the Stacks blockchain has just over two years of activity, and the `chainhook` utility can work with both `testnet` and `mainnet` chainstates in memory.
:::note
To test a Stacks `if_this` / `then_that` predicate, the following command can be used:
Configuring a `bitcoind` instance is out of the scope of this guide.
:::
Assuming a `bitcoind` node is correctly configured, you can perform scans using the following command:
```bash
$ chainhook predicates scan ./path/to/predicate.json --testnet
```
When using the flag `--testnet`, the scan operation will generate a configuration file in memory using the following settings:
```toml
[storage]
driver = "memory"
[chainhooks]
max_stacks_registrations = 500
max_bitcoin_registrations = 500
The first time this command run, a chainstate archive will be downloaded, uncompressed, and written to disk (around 3GB required for the testnet and 10GB for the mainnet).
[network]
mode = "testnet"
bitcoind_rpc_url = "http://0.0.0.0:18332"
bitcoind_rpc_username = "testnet"
bitcoind_rpc_password = "testnet"
stacks_node_rpc_url = "http://0.0.0.0:20443"
```
When using the flag `--mainnet`, the scan operation will generate a configuration file in memory using the following settings:
```toml
[storage]
driver = "memory"
[chainhooks]
max_stacks_registrations = 500
max_bitcoin_registrations = 500
[network]
mode = "mainnet"
bitcoind_rpc_url = "http://0.0.0.0:8332"
bitcoind_rpc_username = "mainnet"
bitcoind_rpc_password = "mainnet"
stacks_node_rpc_url = "http://0.0.0.0:20443"
```
Developers can customize their Bitcoin node's credentials and network address by adding the flag `-config=/path/to/config.toml`.
```bash
$ chainhook config new --testnet
✔ Generated config file Chainhook.toml
$ chainhook predicates scan ./path/predicate.json --config-path=./Chainhook.toml
```
### Tips and tricks
To optimize their experience with scanning, developers have a few knobs they can play with:
- Use of adequate values for `start_block` and `end_block` in predicates will drastically improve the speed.
- Networking: reducing the number of network hops between the chainhook and the bitcoind processes can also help a lot.
The subsequent scans will use the cached chainstate if already present, speeding up iterations and the overall feedback loop.

2
docs/overview.md
View File

@@ -1,5 +1,5 @@
---
title: Chainhook Overview
title: Overview
---
# What is Chainhook?