# Getting started
### Prerequisites
To run this node, you must have the follow software installed on your local machine:
* Docker (including docker-compose)
* Python 3
* Virtualenv (`sudo apt install python3-venv`)
* Openssl
* Git
### Cloning this repository
```bash
# Clone repository
git clone https://github.com/ActorForth/bch-devsuite.git
cd ./bch-devsuite
# Setup virtualenv
python3 -m venv venv
source ./venv/bin/activate
# Install script dependencies
pip install -r requirements.txt
```
### Configuration
bch-devsuite initialize the infrastructure from configuration file, see configuration for more details.
### Setup infrastructure
#### 1. Generate configuration
You can run this command and follow the command-line wizard
```bash
./bch-devsuite build-config /tmp/bch-devsuite.toml
```
or create a config file by hand, note that you can remove the part if you don't want that component. See [Configuration Examples](/configuration-examples) for more examples.
```toml
# Example TOML config file
network = "mainnet" # mainnet | testnet | regtest
rest_service = "bchrest" # bchrest or bchapi
exposed_ports = true
docker_network = "bch-devsuite-network" # docker-network name
[local_node] # Local node configuration
node = "bu" # bu (bitcoin unlimited) or bchn (bitcoin cash node)
wait_time = 6 # a delay before running initializes command. Need to be high if you run on a slow system.
[slp] # SLPDB
username = "actorforth" # MongoDB username
password = "123ldsfoijqwerj" # MongoDB password
[smartbch] # SmartBCH
enabled = true
test_keys = [ "0b7cdf43329298b26d34d311b25d39f19c60fff25ba45b121284f91e12f17658", "b4d85a7a944b08bab74d0e9e9d612ee409649b382e4de500ee3bd7b7e9c6954f", "216fe772968f326d1b992da744db79fcf06cf6f1142d18086fb4b5a7005cdb8f", "adb378c6b0b9b9cb6190c88cbcaa992388f8e37f1d9c7fc791d08201d04047dc", "09b13dbd311823699802bad7240315021f9e79fe029cc0c0a7a15ab614f303d3", "7c5f4f8eb1f8a82dc9f243350082a1542b2d77d09832023b5cf8f158196a717e", "2917909f71ca82665e6f9ab50b05ecc869f49b9157d0b17976ccd000b3987e29", "989a02864785024b8488d4b22bbdea98048389c18879c18a95e72fbca11c0048", "e473abfa2982915d2cadb204dd41e41afce1b4e8851783a6b1356f5e6784774b", "e3bab3da3a55ac52b241f5d4c2066125b47e197316339540536f66ff92f38585"] # test accounts, only needed for regtest
[bch_rpc_conf]
host = "http://bch-node" # BCH RPC host, leave it to be "http://bch-node" if you also run BCH local node with bch-devsuite
port = "8332" # BCH RPC port
username = "actorforth" # BCH RPC username
password = "BWrzap0bqMjezoeHtOzgOOcUgzkxaL6w" # BCH RPC password
```
#### 2. Init infrastructure
Run:
```bash
./bch-devsuite init -f /tmp/bch-devsuite.toml
```
This command will read configuration file, generate files, check necessary softwares is installed, and then it will download and prepare the docker containers. 
### Running infrastructure
Execute the *services* script to start the node, indexer, rest API, and/or SLPDB (depending which ones defined in configuration file).
```bash
./bch-devsuite start
```
### Testing
```bash
./bitcoin-cli getblockchaininfo
```
Expected result
```json
{
"chain": "regtest",
"blocks": 200,
"headers": 200,
"bestblockhash": "0714183b15ac3757e35152fadbc0fd2d73ec97c4d9e1ee486882b18da8b256ca",
"difficulty": 4.656542373906925e-10,
"mediantime": 1614598375,
"verificationprogress": 1,
"initialblockdownload": false,
"chainwork": "0000000000000000000000000000000000000000000000000000000000000192",
"size_on_disk": 48350,
"pruned": false,
"softforks": [
{
"id": "bip34",
"version": 2,
"reject": {
"status": false
}
},
{
"id": "bip66",
"version": 3,
"reject": {
"status": false
}
},
{
"id": "bip65",
"version": 4,
"reject": {
"status": false
}
}
],
"bip9_softforks": {},
"bip135_forks": {}
}
```
### Stop infrastructure
Once you decide to call it a day, you can shut down your local environment by executing:
```bash
./bch-devsuite stop
```
### Cleaning Up
If you experience any issues, or would like to completely erase the current wallet and node containers, run the following script:
```bash
sudo ./clean
```
**NOTE:** this command may need to be ran with sudo while on linux
**WARNING:** The 'clean' script is very destructive, so make sure you only use it when you want to *completely erase* the entire current instance of nodes and the wallet.
# Configuration Examples
Examples of configuration TOML files, you can start with one of this and modify to meet your needs.
## [rest.bitcoin.com tech stack](https://github.com/ActorForth/bch-devsuite/blob/develop/docs/architecture/README.md#1.-rest.bitcoin.com-tech-stack)
```toml
# Example rest.bitcoin.com tech stack TOML config file
network = "mainnet"
rest_service = "bchrest"
exposed_ports = true
docker_network = "bch-devsuite-network"
[local_node]
node = "bu"
wait_time = 6
[slp]
username = "actorforth"
password = "123ldsfoijqwerj"
[bch_rpc_conf]
host = "http://bch-node"
port = "8332"
username = "actorforth"
password = "BWrzap0bqMjezoeHtOzgOOcUgzkxaL6w"
```
***
## [Chris Troutner JS tech stack](https://github.com/ActorForth/bch-devsuite/blob/develop/docs/architecture/README.md#2.-chris-troutner-js-tech-stack)
```toml
# Example Chris Troutner JS Tech Stack TOML config file
network = "mainnet"
rest_service = "bchapi"
exposed_ports = true
docker_network = "bch-devsuite-network"
[local_node]
node = "bu"
wait_time = 6
[slp]
username = "actorforth"
password = "123ldsfoijqwerj"
[bch_rpc_conf]
host = "http://bch-node"
port = "8332"
username = "actorforth"
password = "BWrzap0bqMjezoeHtOzgOOcUgzkxaL6w"
```
***
## SmartBCH Single Node Private Testnet
```toml
network = "regtest"
exposed_ports = true
docker_network = "bch-devsuite-network"
[local_node]
node = "bu"
regtest_blocks = "200"
wait_time = 6
[smartbch]
enabled = true
test_keys = [ "5f532666cf906ae915be2a58e591150a0e4371c124fec75bf4f9aff1d6d70d64", "6ffed448bfd71171822517facb73064d8ec259a8ed26c247ce686c35605648df", "b4d021fe956cfbb257dd9a1b27d40f0b9518b3b55ea03d65051302a3968906ea", "b671447e4ed28da42ee472890ab1bff4f7311250da8df848eeacfaf89bc6abbc", "b9e396537dc6b5dbb8c7c07f372a1e1848ff8e922615f284cd62fcc194324a29", "167f173b8cefd2c94d6f711ab2638492634e5408e8c3a96b79b414806d1f739d", "3ea051bb9ced8fd20eb826493da41b9ab8aa509af26e446a412178ae01c45caa", "8fea7384caa4b3dcffb5aeb779f065ecaf7bc681ceeba6523c3080b864df581c", "56ed2ec8f0c75365156847a7896905f82096df2cd60f104a486d0ff36616652e", "f5a1d4d0db63a9c7775ba02403eda7e20250907742266dca7d9e8242bc4d4182",]
[bch_rpc_conf]
host = "http://bch-node"
port = "18443"
username = "actorforth"
password = "yW8poFq39PXeNC8lnQPAXE6wWuCsBVNw"
```
## SmartBCH Testnet
```toml
network = "testnet"
exposed_ports = true
docker_network = "bch-devsuite-network"
[smartbch]
enabled = true
[bch_rpc_conf]
host = "http://35.220.203.194"
port = "8545"
username = "test"
password = "test"
```
# Getting started with SDK
# Geting started with bch-js
# Getting started with BitCash
# Setup Option
### Network
* Regtest
* Testnet
* Mainnet
### Component
* Local node (Bitcoin Unlimited node or Bitcoin Cash Node)
* REST service (A rest.bitcoin.com-compatible or Bch-API)
* SLP services (SLPDB, slpserve)
* SmartBCH ()
### Local node
* Bitcoin Unlimited Node
* Bitcoin Cash Node
### REST Service
* bchrest (rest.bitcoin.com)
* bchapi ()
# Architecture
Two REST APIs can be run: [rest.bitcoin.com](https://github.com/ActorForth/rest.bitcoin.com) and [bch-api](https://api.fullstack.cash/docs/).
#### 1. rest.bitcoin.com tech stack
All these components work together in a stack, which means that if the lower part is missing then some of the API in [rest.bitcoin.com](https://github.com/ActorForth/rest.bitcoin.com) might not function properly.
The main reason why you should use all of our fork stacks is because we maintain and guarantee that all of the components will work well with the Regtest address format. Allowing you to test locally more easily.
The blue part is the node that you choose. The default node is Bitcoin unlimited and there is Bitcoin Cash node as an option as well.
The red part is an indexer. ElectrsCash is for indexing Bitcoin cash transactions and aggregate BCH balance per address. Without these, you won't be able to query the amount of BCH you own in a particular address. OpenSight is a shim micro service to make ElectrsCash compatible with [rest.bitcoin.com](https://github.com/ActorForth/rest.bitcoin.com) API interface. [SLPDB](https://github.com/ActorForth/bch-devsuite/blob/develop/docs/slp.dev/tooling/slpdb/README.md#what-is-slpdb) is an indexer for SLP token, color coin on top of Bitcoin Cash, this will be verified if the data relate to the color coin is valid and checks if the coin follows the SLP off-chain consensus.
The orange part is [rest.bitcoin.com](https://github.com/ActorForth/rest.bitcoin.com) API, a unified interface for anyone to interact with all of these complex services through REST API interface uniformly
The green part is the client SDK that will interact with [rest.bitcoin.com](https://github.com/ActorForth/rest.bitcoin.com) interface. [Bitcash](https://github.com/ActorForth/bitcash) is written in Python and [Bitbox](https://github.com/ActorForth/bitbox-sdk) is written in typescript.
#### 2. Chris Troutner JS tech stack
The main difference is the rest interface. bch-api has a different API from rest.bitcoin.com and can talk directly to Electrscash without requiring the shim.
# Advance Usage
* Automate test with Regtest node
* Generate your own test coin in Regtest
# Sponsorship
Please help support our effort
Please help support our effort\
# Known Issues
### smartbchd illegal instruction (SIGILL)
#### Symptoms
```bash
$ docker run ghcr.io/actorforth/smartbch-amber:v0.3.5 start --mainnet-genesis-height=602983
SIGILL: illegal instruction
PC=0xbfd520 m=0 sigcode=2
instruction bytes: 0xf 0x1 0xf9 0x48 0xc1 0xe2 0x20 0x48 0x1 0xd0 0x48 0x89 0x44 0x24 0x8 0xf
goroutine 1 [running, locked to thread]:
github.com/dterei/gotsc.BenchEnd(0x34fea9a7ce340)
/go/pkg/mod/github.com/dterei/gotsc@v0.0.0-20160722215413-e78f872945c6/tsc_amd64.s:18 fp=0xc0002c5838 sp=0xc0002c5830 pc=0xbfd520
github.com/dterei/gotsc.TSCOverhead(0xf)
/go/pkg/mod/github.com/dterei/gotsc@v0.0.0-20160722215413-e78f872945c6/tsc.go:36 +0x48 fp=0xc0002c5868 sp=0xc0002c5838 pc=0xbfd4a8
github.com/smartbch/moeingads/datatree.init.0()
/go/pkg/mod/github.com/smartbch/moeingads@v0.3.0/datatree/tree.go:76 +0x37 fp=0xc0002c5a48 sp=0xc0002c5868 pc=0xc0bbb7
runtime.doInit(0x1d6c960)
/usr/local/go/src/runtime/proc.go:6309 +0xec fp=0xc0002c5b98 sp=0xc0002c5a48 pc=0x45e42c
runtime.doInit(0x1d6be20)
/usr/local/go/src/runtime/proc.go:6286 +0x72 fp=0xc0002c5ce8 sp=0xc0002c5b98 pc=0x45e3b2
runtime.doInit(0x1d73900)
/usr/local/go/src/runtime/proc.go:6286 +0x72 fp=0xc0002c5e38 sp=0xc0002c5ce8 pc=0x45e3b2
runtime.doInit(0x1d76200)
/usr/local/go/src/runtime/proc.go:6286 +0x72 fp=0xc0002c5f88 sp=0xc0002c5e38 pc=0x45e3b2
runtime.main()
/usr/local/go/src/runtime/proc.go:208 +0x205 fp=0xc0002c5fe0 sp=0xc0002c5f88 pc=0x450785
runtime.goexit()
/usr/local/go/src/runtime/asm_amd64.s:1371 +0x1 fp=0xc0002c5fe8 sp=0xc0002c5fe0 pc=0x488241
rax 0x34fea9a7ce340
rbx 0x756e6547
rcx 0x6c65746e
rdx 0x34fea00000000
rdi 0x1d6c9f0
rsi 0xf
rbp 0xc0002c5858
rsp 0xc0002c5830
r8 0x0
r9 0xc000144090
r10 0x6f00af00
r11 0x2f0e1eb5
r12 0x7200b376
r13 0x6f
r14 0x200
r15 0xffffffffffffffff
rip 0xbfd520
rflags 0x10202
cs 0x33
fs 0x0
gs 0x0
```
* It seems the asm is trying to run a command not supported by your CPU architecture.
* Issue occured on machines running ProxMox VM default CPU ("kvm64"), fixed by change to "host" instead.
* Read more: [SIGILL: illegal instruction when running smartbchd init mynode --chain-id 0x2710](https://github.com/smartbch/smartbch/issues/28)
# Contribution Guide
# Archived
### About
This repo intends to be a toolkit for running a local version of a Bitcoin Unlimited for development and testing purposes. Currently it provides a self-hosted local node, indexer (Electrs), a drop-in Ninsight replacement (Opensight), a regtest version of the
### Known Issues
There are a few issues with this setup that could use improvement in the future.
* Currently, this setup relies on the built-in Electrscash indexing server included in the Bitcoin Unlimited node. This isn't an issue per se, but to test with other nodes (such as Bitcoin ABC, Bitcoin Cash Node, or bchd) it will be necessary to seperate the indexing server into a seperate container.
*
# Bitcoin Cash Upgrade 2022
On May 15th, 2022, Bitcoin Cash will undergo a technical upgrade to further expand its virtual machine (VM) contracting capabilities. bch-devsuite version < 1.3.0 have to perform the upgrade.
## Instructions
```bash
# Upgrade bch-devsuite to 1.3.0
git fetch origin
git checkout 1.3.0
# Activate python virtualenv
source ./venv/bin/activate
# Install new dependencies
pip install -r requirements.txt
# Stop the running system
./bch-devsuite stop
# Backup data directory (Optional)
sudo cp -r data databak
# Upgrade stacks
./bch-devsuite upgrade
# Restart the system
./bch-devsuite start
# [Smartbch] `./bch-devsuite start` may showing that your bch-node is not completely synced up
# and it cannot start smartbch, you have to wait until it synced up and manully start smartbch with command
./bch-devsuite start-smartbch
```