diff --git a/README.md b/README.md index 5a7e2bec..2e98dda8 100644 --- a/README.md +++ b/README.md @@ -1,72 +1,22 @@ [![Coverage Status](https://coveralls.io/repos/github/bluzelle/curium/badge.svg?branch=devel)](https://coveralls.io/github/bluzelle/curium?branch=devel) -# Curium Application -https://github.com/cosmos/sdk-tutorials/tree/master/nameservice +The Bluzelle Curium Application +=============================== +**TODO: Marketing description of the product here** -This project will form the basis of the Bluzelle Swarm Application. +Bluzelle Curium Multi-Validator Zone Installation +------------------------------------------------- +These are steps involved in setting up the OS, Dev Environment, building and deploying a multi-node Curium Zone. -## Building and running the example +1. [OS Setup for Curium](./docs/setup/os.md) +2. [Development Environment Setup](./docs/setup/devenv.md) +3. [Build the Curium Project](./docs/setup/build.md) +4. [Deploy the Initial Node](./docs/setup/deploy.md) +5. [Deploy Additional Nodes](./docs/setup/deployaddl.md) -* Install Golang version 1.13.4 from https://golang.org -* Optionally install your favourite Golang IDE (JetBrains Goland is a good one). Vim or emacs is probably all you need, though. -* make sure your Environment paths are set in your profile or rc file, for example: -`export GOPATH=/Users/rnistuk/go` -`export GOBIN=${GOPATH}/bin` -`export PATH=$PATH:$GOBIN` -* cd to the project root folder -* build and install the project -`make` -`make install` -* This will create the command line interface `blzcli` and the daemon `blzd` applications in your $GOBIN -* Now you can spool up a node and try it out! -* Open a new terminal for the daemon -* In the daemon terminal use blzd init to initialize the config files and genesis file -`blzd init --chain-id namechain` -moniker will be the name of the node, e.g.) Bluzelle -* In another terminal we will use the cli `blzcli` to set up a user or two -`blzcli keys add rich` -"rich" is the name of the user to be added. Follow the crypto related instructions from the blzcli -* Use the daemon to give yourself some nametokens -`blzd add-genesis-account $(blzcli keys show rich -a) 1000nametoken,1000000000stake` -note the use of blzcli to get the identifier for rich, try running the keys function on it's own -* Do some configure magic (we're not sure what a couple of these do yet...) -`blzcli config chain-id namechain` -`blzcli config output json` -`blzcli config indent true` -`blzcli config trust-node true` -* generate and validate a genesis transaction to start up the blockchain. -`blzd gentx --name rich` -`blzd collect-gentxs` -`blzd validate-genesis` -* In the daemon terminal start the node -`blzd start` -* Query the node and make some transactions. - -#Here are some Example queries transactions: - -\# Initialize configuration files and genesis file -\# moniker is the name of your node - blzd init --chain-id namechain - - - \# Copy the `Address` output here and save it for later use - \# [optional] add "--ledger" at the end to use a Ledger Nano S - blzcli keys add jack - - \# Copy the `Address` output here and save it for later use - blzcli keys add alice - - \# Add both accounts, with coins to the genesis file - blzd add-genesis-account $(blzcli keys show jack -a) 1000nametoken,100000000stake - blzd add-genesis-account $(blzcli keys show alice -a) 1000nametoken,100000000stake - - \# Configure your CLI to eliminate need for chain-id flag - blzcli config chain-id namechain - blzcli config output json - blzcli config indent true - blzcli config trust-node true - - blzd gentx --name jack ` - \ No newline at end of file +Using the Bluzelle Curium Multi-Validator Zone +---------------------------------------------- +- [Queries and Transactions](./docs/commands/qAndTX.md) +- [Useful Operations](./docs/commands/useful.md) diff --git a/docs/commands/qAndTX.md b/docs/commands/qAndTX.md new file mode 100644 index 00000000..3c404a37 --- /dev/null +++ b/docs/commands/qAndTX.md @@ -0,0 +1,20 @@ +[prev](../setup/deployaddl.md) | [next](../commands/useful.md) +*** +Using the Bluzelle Curium Zone +============================== +# Queries +The querying subcommands provide access to the unsigned functinality of the the Curium cli. These commands do not use gas and results are returned directly. + +The CLI can provide usage help for the queries with the following command: + + $ blzcli q --help + +# Transactions +Transactional commands can be crytographically signed and require gas to perform. Where a command has a return value users must employ the "tx" query to retrieve the response. + +The CLI can provide usage help for the queries with the following command: + + $ blzcli tx --help + +*** +[prev](../setup/deployaddl.md) | [next](../commands/useful.md) \ No newline at end of file diff --git a/docs/commands/useful.md b/docs/commands/useful.md new file mode 100644 index 00000000..f183d9e6 --- /dev/null +++ b/docs/commands/useful.md @@ -0,0 +1,10 @@ +[prev](./qAndTX.md) +*** + +Useful Commands +=============== + +# TBD + +*** +[prev](./qAndTX.md) \ No newline at end of file diff --git a/docs/setup/build.md b/docs/setup/build.md new file mode 100644 index 00000000..9ed2a314 --- /dev/null +++ b/docs/setup/build.md @@ -0,0 +1,100 @@ +[prev](./devenv.md) | [next](./deploy.md) +*** + +Build the Curium Project +======================== + +1. cd to the project folder + + $ cd ~/go/src/github.com/bluzelle/curium + +2. Install blzd and blzcli + + $ make install + +3. Ensure blzcli and blzd work by executing the binaries, you should be able to execute the apps from your user folder: + + $ cd + $ blzcli + Bluzelle CRUD Client + + Usage: + blzcli [command] + + Available Commands: + status Query remote node for status + config Create or query an application CLI configuration file + query Querying subcommands + tx Transactions subcommands + + rest-server Start LCD (light-client daemon), a local REST server + + keys Add or view local private keys + + version Print the app version + help Help about any command + + Flags: + --chain-id string Chain ID of tendermint node + -e, --encoding string Binary encoding (hex|b64|btc) (default "hex") + -h, --help help for blzcli + --home string directory for config and data (default "/Users/rnistuk/.blzcli") + -o, --output string Output format (text|json) (default "text") + --trace print out full stack trace on errors + + Use "blzcli [command] --help" for more information about a command. + + the daemon: + + $ cd + $ blzd + Bluzelle CRUD Daemon (server) + + Usage: + blzd [command] + + Available Commands: + init Initialize private validator, p2p, genesis, and application configuration files + collect-gentxs Collect genesis txs and output a genesis.json file + gentx Generate a genesis tx carrying a self delegation + validate-genesis validates the genesis file at the default location or at the location passed as an arg + add-genesis-account Add genesis account to genesis.json + start Run the full node + unsafe-reset-all Resets the blockchain database, removes address book files, and resets priv_validator.json to the genesis state + + tendermint Tendermint subcommands + export Export state to JSON + + version Print the app version + help Help about any command + + Flags: + -h, --help help for blzd + --home string directory for config and data (default "/Users/rnistuk/.blzd") + --log_level string Log level (default "main:info,state:info,*:error") + --trace print out full stack trace on errors + + Use "blzd [command] --help" for more information about a command. + +4. You can also verify the build versions with the following commands. They should match the git commit hash of the tip (git rev-parse HEAD) you cloned above. + + $ blzcli version --long + name: BluzelleService + server_name: blzd + client_name: blzcli + version: 0.0.0-24-g3253c8b + commit: 3253c8b6b4e40b125c0ccdfd6a81a06a02a5e018 + build_tags: ledger,cosmos-sdk v0.37.4 + go: go version go1.13.4 darwin/amd64 + + $ blzd version --long + name: BluzelleService + server_name: blzd + client_name: blzcli + version: 0.0.0-24-g3253c8b + commit: 3253c8b6b4e40b125c0ccdfd6a81a06a02a5e018 + build_tags: ledger,cosmos-sdk v0.37.4 + go: go version go1.13.4 darwin/amd64 + + *** + [prev](./devenv.md) | [next](./deploy.md) \ No newline at end of file diff --git a/docs/setup/deploy.md b/docs/setup/deploy.md new file mode 100644 index 00000000..8f7a5e3f --- /dev/null +++ b/docs/setup/deploy.md @@ -0,0 +1,104 @@ +[prev](./build.md) | [next](./deployaddl.md) +*** + +Deploy the Initial Node +======================= + +1. Before initializing a node, remove the previous node config folders from your home folder, if they exist + + $ rm -rf .blz* + +2. Initialize the daemon + + $ blzd init [moniker] [flags] + + where moniker is a human readable name for the current node, an appropriate flag would be a string for --chain-id, for example + + $ blzd init curium00 --chain-id bluzelle 2>&1 | jq .node_id + + Use the jq command to parse the node_id from the json output. Note the “2>&1” argument, blzd init, in this case sends its output to stderr, so we need to redirect the output back to stdout. + + The JSON output will contain the node_id, note that value so that it can be used to identify this node to other nodes in the zone (in their respective “persistent_peers” value in config.toml). + +3. Edit “./blzd/config/config.toml” to add + + output = "json" + + after the line + + ##### advanced configuration options ##### + +4. Edit “.blzd/config/genesis.json” to change bond_denom from “stake” to “bnt”. This genesis.json file will be used to initialize the blockchain for this zone. This can be done from the command line with sed + + $ sed -i -e 's/"bond_denom": "stake"/"bond_denom": "bnt"/g' \ + ~/.blzd/config/genesis.json + +5. Edit .blzd/config/app.toml in a text editor and set the minimum-gas-prices to “0.01bnt”. Every node should have at least this minimum. This can also be done from the command line with sed: + + $ sed -i -e 's/minimum-gas-prices = ""/minimum-gas-prices = "0.01bnt"/g' \ + ~/.blzd/config/app.toml + +6. Set the client configuration settings: + $ blzcli config chain-id bluzelle + $ blzcli config output json + $ blzcli config indent true + $ blzcli config trust-node true + where “bluzelle” is the zone’s chain-id. + +7. Derive a new key that will label the validator account for this node, call it “validator”: + + $ blzcli keys add validator + Enter a passphrase to encrypt your key to disk: + Repeat the passphrase: + + - name: validator + type: local + address: bluzelle1akcrplttpq2qvp90g8l7ttgj25q00rvj0e9d6k + pubkey: bluzellepub1addwnpepqtzzdysc4mukmzzk7aexmfyjdq305ztgu2dkggytqazvvpxv3xma56r8c4n + mnemonic: "" + threshold: 0 + pubkeys: [] + + + **Important** write this mnemonic phrase in a safe place. + It is the only way to recover your account if you ever forget your password. + + amused silk skull latin symbol together resemble blind march achieve angle rib innocent reflect weapon critic quarter empty crime pride fluid hint finish switch + + Note the address, with the “bluzelle” prefix, and the mnemonic. The mnemonic will be used by the Bluzelle javascript client to send transactions to the node. + +8. Add the first account to the blockchain using the validator key as the account identifier + + $ blzd add-genesis-account $(blzcli keys show validator -a) 10000000000bnt + + this command is an alias for “tx staking create-validator”. The amount given for the bnt tokens here will be the total amount of tokens available to the zone. + +9. As this is the first node in the zone, it needs a transaction that will be the first transaction in the blockchain. + + $ blzd gentx --name vuser --amount 100000000bnt + Password to sign with 'validator': + Genesis transaction written to "/home/rich/.blzd/config/gentx/gentx-6ccdb7764f4b6762bca9ce254ee9db49a687cc9c.json" + + remember to specify the amount of coins to bond using the --amount parameter so that bnt is used as stake, if this is neglected the bonding denomination will be stake. Open the genesis transaction JSON file and note the value for the validator_address, it will have the prefix “bluzellevaloper”, this id will be used to get account info later. + +10. Create the genesis file from the first transaction: + + $ blzd collect-gentxs + the output of this command will also contain the validator_address, prefixed with bluzellevaloper. If you have not done so in the previous step, note the validator_address. + + This command creates the signed genesis.json (.blzd/config/genesis.json) that will be copied to the rest of the nodes in the zone. + +11. The node can be started with the Bluzelle daemon: + + $ blzd start + +12. On a second terminal the http server can be started with the Bluzelle client + + $ blzcli rest-server + + If external access to the rest server is required add the _--laddr_ argument + + $ blzcli rest-server --laddr tcp://0.0.0.0:1317 + +*** +[prev](./build.md) | [next](./deployaddl.md) diff --git a/docs/setup/deployaddl.md b/docs/setup/deployaddl.md new file mode 100644 index 00000000..dc115bb0 --- /dev/null +++ b/docs/setup/deployaddl.md @@ -0,0 +1,129 @@ +[prev](./deploy.md) | [next](../commands/qAndTX.md) +*** +Deploy Additional Nodes +======================== + +1. Refer to previous documents for initializing the server, dev environments, and building the Bluzelle Curium applications. Open incoming TCP ports 26656 and 1317. + +2. Initialize the daemon config as before + + $ blzd init --chain-id 2>&1 | jq .node_id + + Use a new moniker string, but use the same chain-id as used in the initial node + + $ blzd init curium01 --chain-id bluzelle 2>&1 | jq .node_id + + The JSON output will contain the node_id, note that value so that it can be used to identify this node to other nodes in the zone (in their respective “persistent_peers” value in config.toml). Keep in mind that for this document’s purposes, we are only really ever pointing all second and subsequent nodes to the first node’s id. We could point them to any other running node, in theory. + + There is no need to edit the genesis file, .blzd/config/genesis.json, as it will be replaced with the genesis file created for the initial node in this zone. + +3. Set the client configuration + + $ blzcli config chain-id bluzelle + $ blzcli config output json + $ blzcli config indent true + $ blzcli config trust-node true + +4. Edit .blzd/config/config/config.toml to add the first node’s address to the comma separated list of persistent_peers: + + # Comma separated list of nodes to keep persistent connections to + persistent_peers = "6ccdb7764f4b6762bca9ce254ee9db49a687cc9c@18.220.65.143:26656" + + The node list item is created from the node id of the first node and its server’s ip address and Cosmos port number. In theory, you could point to any of the nodes already standing, here, or even all or some of them. We just choose to point to the first one here, for the purposes of the documentation. + +5. Edit .blzd/config/app.toml to set the minimum-gas-prices to “0.01bnt” + + # The minimum gas prices a validator is willing to accept for processing a + # transaction. A transaction's fees must meet the minimum of any denomination + # specified in this config (e.g. 0.25token1;0.0001token2). + minimum-gas-prices = "0.01bnt" + + Remember that every node should have at least this minimum. Feel free to set it higher if you wish. + +6. Create the key that will be used to label the validator on this node + + $ blzcli keys add vuser + Enter a passphrase to encrypt your key to disk: + Repeat the passphrase: + + - name: vuser + type: local + address: bluzelle1zgu6f3ezy0ay9eq82nla2mmlnedzypn9q86usr + pubkey: bluzellepub1addwnpepqvz4h9kgd7xx4k04epr7z2msy82uh8ugdsdykmplzcu2sx80gttrz8x8fpr + mnemonic: "" + threshold: 0 + pubkeys: [] + + **Important** write this mnemonic phrase in a safe place. + It is the only way to recover your account if you ever forget your password. + + poem reason library tenant enhance uncover welcome sponsor govern math young muffin series onion coral metal uncover topple conduct pact recall moral tornado palace + + note the address and mnemonic phrase values. + +7. Return to the first node server and distribute tokens from the genesis validator to the address of the validator on the new node + + $ blzcli tx send 1000000000bnt / + --gas-prices 0.01bnt / + --from validator + note that the the validator keys are the id’s that are prefixed with “bluzelle”, and can be obtained by running + + $ blzcli keys show validator -a + + on each server. + + The “tx send” command will place the transaction that sends 1B bnt tokens from the validator on the first node the the validator on the second node on the blockchain. + +8. Before the node can be started it must copy the genesis.json file from the first node. Return to the new node server and use the secure copy command scp, to copy the genesis file from the first node. + + $ scp ubuntu@:~/.blzd/config/genesis.json ~/.blzd/config/ + +9. Start the Bluzelle daemon as a background task on the new node + + $ blzd start + + the node will start and catch up to the rest of the zone. Occasionally, this command will fail, in that case run the following command first + + $ blzd unsafe-reset-all + + and then retry the start command. + +10. When the new node catches up to the rest of the zone, the account that we have named validator will have 1B bnt tokens, and it can be turned into a validator node, allowed to participate in validating additions to the blockchain. + + $ blzcli tx staking create-validator \ + --amount=100000000bnt \ + --pubkey=$(blzd tendermint show-validator) \ + --moniker=curium01 \ + --commission-rate=0.1 \ + --commission-max-rate=0.2 \ + --commission-max-change-rate=0.01 \ + --min-self-delegation=1 \ + --gas=auto --gas-adjustment=1.2 \ + --gas-prices=0.01bnt \ + --from validator + + This will stake this node’s validator with the minimum amount of bnt tokens to become a validator with 100 voting power. The validator will participate in validating new operations sent to block chain and earn rewards and commision for doing so. Be sure to note the validator address in the output. + +11. You can get the current validator set with the command + + $ blzcli q tendermint-validator-set + { + "block_height": "758", + "validators": [ + { + "address": "bluzellevalcons1djmvgcx9l8kn7m0zye4dgjnwsa4twypuyd9gqy", + "pub_key": "bluzellevalconspub1zcjduepq4cdy7m8fv60d5fr9zwx5j8h00qckhthzusrk8t6sz6szaa89x3hs6zufce", + "proposer_priority": "-87", + "voting_power": "100" + }, + { + "address": "bluzellevalcons1cg0pcwwefhflctqvsr3fejc6gnt30whc8jzzzd", + "pub_key": "bluzellevalconspub1zcjduepqnlt34pc0lqwt0rekxfxzz8k4mvf0a6z9nfasjmtvrx7xfej0ehaqxp6aqd", + "proposer_priority": "88", + "voting_power": "100" + } + ] + } +*** +[prev](./deploy.md) | [next](../commands/qAndTX.md) + diff --git a/docs/setup/devenv.md b/docs/setup/devenv.md new file mode 100644 index 00000000..c8c33f62 --- /dev/null +++ b/docs/setup/devenv.md @@ -0,0 +1,37 @@ +[prev](./os.md) | [next](./build.md) +*** + +Development Environment Setup +============================= +1. Curium uses Golang, on Linux: + + $ wget https://dl.google.com/go/go1.13.5.linux-amd64.tar.gz + + $ sudo tar -C /usr/local -xzf go1.13.5.linux-amd64.tar.gz + + on macOS install the latest package from here: https://golang.org/doc/install + +2. Make sure your Environment paths are set in your .profile file, for example, add the following to the end: + + export GOPATH=$HOME/go + export GOBIN=${GOPATH}/bin + export PATH=$PATH:$GOBIN:/usr/local/go/bin` + + GOPATH is where the golang project source files, packages and binaries are kept. Make sure that the Golang compiler is in the PATH + +3. Make the Golang working folders, if they have not already been created by the Golang compiler + + $ mkdir -p ~/go/src/github.com/bluzelle + $ mkdir ~/go/bin + $ mkdir ~/go/pkg + +4. Go to the bluzelle folder + + $ cd ~/go/src/github.com/bluzelle + +5. Clone the curium project + + $ git clone https://github.com/bluzelle/curium.git + +*** +[prev](./os.md) | [next](./build.md) \ No newline at end of file diff --git a/docs/setup/os.md b/docs/setup/os.md new file mode 100644 index 00000000..57719cf3 --- /dev/null +++ b/docs/setup/os.md @@ -0,0 +1,28 @@ +[prev](../../README.md) | [next](./devenv.md) +*** + +OS Setup for Curium +=================== + +Linux: +----- +Install Ubuntu, open incoming tcp ports 26656 and 1317, these are the ports that the daemon and http servers will use. + +Install the build-essential tools and jq for easy JSON parsing + +`$ sudo apt-get install build-essential jq` + + +macOS: +------ +We use homebrew (https://brew.sh/) to install dependancies, ensure that brew is installed and updated. + + +Install jq (https://stedolan.github.io/jq/) to help process the json output of the Curium client, use brew to install + +`$ brew install jq` + +we’ll use jq to parse blzd and blzcli output on the command line + +*** +[prev](../../README.md) | [next](./devenv.md) \ No newline at end of file