debug_node: Create README.md
This commit is contained in:
theoreticalbts
parent
f049fce4e9
commit
0f7f8acc03
1 changed files with 104 additions and 0 deletions
104
programs/debug_node/README.md
Normal file
104
programs/debug_node/README.md
Normal file
|
|
@ -0,0 +1,104 @@
|
|||
|
||||
Introduction
|
||||
------------
|
||||
|
||||
The `debug_node` is a tool to allow developers to run many interesting sorts of "what-if" tests using state from a production blockchain.
|
||||
Like "what happens if I produce enough blocks for the next hardfork time to arrive?" or "what would happen if this account (which I don't have a private key for) did this transaction?"
|
||||
|
||||
Setup
|
||||
-----
|
||||
|
||||
Be sure you've built the right build targets:
|
||||
|
||||
$ make get_dev_key debug_node cli_wallet witness_node
|
||||
|
||||
Use the `get_dev_key` utility to generate a keypair:
|
||||
|
||||
$ programs/genesis_util/get_dev_key "" nathan
|
||||
[{"private_key":"5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3","public_key":"BTS6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV","address":"BTSFAbAx7yuxt725qSZvfwWqkdCwp9ZnUama"}]
|
||||
|
||||
Obtain a copy of the blockchain in `block_db` directory:
|
||||
$ programs/witness_node/witness_node --data-dir data/mydatadir
|
||||
# ... wait for chain to sync
|
||||
^C
|
||||
$ cp -Rp data/mydatadir/blockchain/database/block_num_to_block ./block_db
|
||||
|
||||
Set up a new datadir with the following `config.ini` settings:
|
||||
|
||||
# setup API endpoint
|
||||
rpc-endpoint = 127.0.0.1:8090
|
||||
# setting this to empty effectively disables the p2p network
|
||||
seed-nodes = []
|
||||
# set apiaccess.json so we can set up
|
||||
api-access = "data/debug_datadir/api-access.json"
|
||||
|
||||
Then set up `data/debug_datadir/api-access.json` to allow access to the debug API like this:
|
||||
|
||||
{
|
||||
"permission_map" :
|
||||
[
|
||||
[
|
||||
"bytemaster",
|
||||
{
|
||||
"password_hash_b64" : "9e9GF7ooXVb9k4BoSfNIPTelXeGOZ5DrgOYMj94elaY=",
|
||||
"password_salt_b64" : "INDdM6iCi/8=",
|
||||
"allowed_apis" : ["database_api", "network_broadcast_api", "history_api", "network_node_api", "debug_api"]
|
||||
}
|
||||
],
|
||||
[
|
||||
"*",
|
||||
{
|
||||
"password_hash_b64" : "*",
|
||||
"password_salt_b64" : "*",
|
||||
"allowed_apis" : ["database_api", "network_broadcast_api", "history_api"]
|
||||
}
|
||||
]
|
||||
]
|
||||
}
|
||||
|
||||
See [here](https://github.com/cryptonomex/graphene#accessing-restricted-apis) for more detail on the `api-access.json` format.
|
||||
|
||||
Once that is set up, run `debug_node` against your newly prepared datadir:
|
||||
|
||||
programs/debug_node/debug_node --data-dir data/debug_datadir
|
||||
|
||||
Run `cli_wallet` to connect to the `debug_node` port, using the username and password to access the new `debug_api` (and also a different wallet file):
|
||||
|
||||
programs/cli_wallet/cli_wallet -s 127.0.0.1:8090 -w debug.wallet -u bytemaster -p supersecret
|
||||
|
||||
Example usage
|
||||
-------------
|
||||
|
||||
Load some blocks from the datadir:
|
||||
|
||||
dbg_push_blocks block_db 20000
|
||||
|
||||
Note, when pushing a very large number of blocks sometimes `cli_wallet` hangs and you must Ctrl+C and restart it (leaving the `debug_node` running).
|
||||
|
||||
Generate (fake) blocks with our own private key:
|
||||
|
||||
dbg_generate_blocks 5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3 1000
|
||||
|
||||
Update `angel` account to be controlled by our own private key and generate a (fake) transfer:
|
||||
|
||||
dbg_update_object {"_action":"update", "id":"1.2.1090", "active":{"weight_threshold":1,"key_auths":[["BTS6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV",1]]}}
|
||||
import_key angel 5KQwrPbwdL6PhXujxW37FSSQZ1JiwsST4cqQzDeyXtP79zkvFD3
|
||||
transfer angel init0 999999 BTS "" true
|
||||
|
||||
How it works
|
||||
------------
|
||||
|
||||
The commands work by creating diff(s) from the main chain that are applied to the local chain at specified block height(s). It lets you easily check out "what-if"
|
||||
scenarios in a fantasy debug toy world forked from the real chain, e.g. "if we take all of the blocks until today, then generate a bunch more until a hardfork time
|
||||
in the future arrives, does the chain stay up? Can I do transactions X, Y, and Z in the wallet after the hardfork?" Anyone connecting to this node sees the same
|
||||
fantasy world, so you can e.g. make changes with the `cli_wallet` and see them exist in other `cli_wallet` instances (or GUI wallets or API scripts).
|
||||
|
||||
Limitations
|
||||
-----------
|
||||
|
||||
The main limitations are:
|
||||
|
||||
- No export format for the diffs, so you can't really [1] connect multiple `debug_node` to each other.
|
||||
- Once faked block(s) or tx(s) have been produced on your chain, you can't really [1] stream blocks or tx's from the main network to your chain.
|
||||
|
||||
[1] It should theoretically be possible, but it's non-trivial and totally untested.
|
||||
Loading…
Reference in a new issue