From e521f3769ee95aad3ccb3706c844d2a15ea84edf Mon Sep 17 00:00:00 2001 From: rigel rozanski Date: Wed, 28 Jun 2017 05:16:33 -0400 Subject: [PATCH 1/8] tutorial auto-testing, basecoin basics --- Makefile | 11 ++- docs/guide/basecoin-basics.md | 122 +++++++++++++++++++++++----------- 2 files changed, 93 insertions(+), 40 deletions(-) diff --git a/Makefile b/Makefile index ea93496b7c..6eb79a96fd 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,7 @@ GOTOOLS = github.com/mitchellh/gox \ - github.com/Masterminds/glide + github.com/Masterminds/glide \ + github.com/rigelrozanski/shelldown/cmd/shelldown +TUTORIALS=$(shell find docs/guide -name "*md" -type f) all: get_vendor_deps install test @@ -27,6 +29,13 @@ test_cli: tests/cli/shunit2 @./tests/cli/restart.sh @./tests/cli/ibc.sh +test_tutorial: + shelldown ${TUTORIALS} + for script in ${TUTORIALS} ; do \ + echo "\n\n\nRunning test for script: $$script.sh" ; \ + bash $$script.sh ; \ + done + get_vendor_deps: tools glide install diff --git a/docs/guide/basecoin-basics.md b/docs/guide/basecoin-basics.md index 36491bb23c..4e3464dbcd 100644 --- a/docs/guide/basecoin-basics.md +++ b/docs/guide/basecoin-basics.md @@ -1,3 +1,43 @@ + + # Basecoin Basics Here we explain how to get started with a simple Basecoin blockchain, @@ -8,7 +48,7 @@ and what is happening under the hood. Installing Basecoin is simple: -``` +```shelldown[0] go get -u github.com/tendermint/basecoin/cmd/... ``` @@ -22,7 +62,7 @@ The former is the running node. The latter is a command-line light-client. Let's generate two keys, one to receive an initial allocation of coins, and one to send some coins to later: -``` +```shelldown[1] # WARNING: this will wipe out any existing info in the ~/.basecli dir # including private keys, don't run if you have lots of local state already basecli reset_all @@ -30,15 +70,16 @@ basecli keys new cool basecli keys new friend ``` -You'll need to enter passwords. You can view your key names and addresses with `basecli keys list`, -or see a particular key's address with `basecli keys get `. +You'll need to enter passwords. You can view your key names and addresses with +`basecli keys list`, or see a particular key's address with `basecli keys get +`. ## Initialize Basecoin To initialize a new Basecoin blockchain, run: -``` +```shelldown[2] # WARNING: this will wipe out any existing info in the ~/.basecoin dir # don't run if you have lots of local state already rm -rf ~/.basecoin @@ -47,21 +88,23 @@ basecoin init
If you prefer not to copy-paste, you can provide the address programatically: -``` +```shelldown[3] basecoin init $(basecli keys get cool | awk '{print $2}') ``` This will create the necessary files for a Basecoin blockchain with one -validator and one account (corresponding to your key) in `~/.basecoin`. For more options on setup, see the -[guide to using the Basecoin tool](/docs/guide/basecoin-tool.md). +validator and one account (corresponding to your key) in `~/.basecoin`. For +more options on setup, see the [guide to using the Basecoin +tool](/docs/guide/basecoin-tool.md). -If you like, you can manually add some more accounts to the blockchain by generating keys and editing the `~/.basecoin/genesis.json`. +If you like, you can manually add some more accounts to the blockchain by +generating keys and editing the `~/.basecoin/genesis.json`. ## Start Now we can start Basecoin: -``` +```shelldown[4] basecoin start ``` @@ -69,11 +112,11 @@ You should see blocks start streaming in! ## Initialize Light-Client -Now that Basecoin is running we can initialize `basecli`, the light-client utility. -Basecli is used for sending transactions and querying the state. +Now that Basecoin is running we can initialize `basecli`, the light-client +utility. Basecli is used for sending transactions and querying the state. Leave Basecoin running and open a new terminal window. Here run: -``` +```shelldown[5] basecli init --node=tcp://localhost:46657 --genesis=$HOME/.basecoin/genesis.json ``` @@ -91,7 +134,7 @@ set through some other method. Now we are ready to send some transactions. First Let's check the balance of the two accounts we setup earlier: -``` +```shelldown[6] ME=$(basecli keys get cool | awk '{print $2}') YOU=$(basecli keys get friend | awk '{print $2}') basecli query account $ME @@ -101,19 +144,19 @@ basecli query account $YOU The first account is flush with cash, while the second account doesn't exist. Let's send funds from the first account to the second: -``` +```shelldown[7] basecli tx send --name=cool --amount=1000mycoin --to=$YOU --sequence=1 ``` Now if we check the second account, it should have `1000` 'mycoin' coins! -``` +```shelldown[8] basecli query account $YOU ``` We can send some of these coins back like so: -``` +```shelldown[9] basecli tx send --name=friend --amount=500mycoin --to=$ME --sequence=1 ``` @@ -121,20 +164,20 @@ Note how we use the `--name` flag to select a different account to send from. If we try to send too much, we'll get an error: -``` +```shelldown[10] basecli tx send --name=friend --amount=500000mycoin --to=$ME --sequence=1 ``` Let's send another transaction: -``` +```shelldown[11] basecli tx send --name=cool --amount=2345mycoin --to=$YOU --sequence=2 ``` Note the `hash` value in the response - this is the hash of the transaction. We can query for the transaction by this hash: -``` +```shelldown[12] basecli query tx ``` @@ -142,23 +185,23 @@ See `basecli tx send --help` for additional details. ## Proof -Even if you don't see it in the UI, the result of every query comes with a proof. -This is a Merkle proof that the result of the query is actually contained in the state. -and the state's Merkle root is contained in a recent block header. -Behind the scenes, `countercli` will not only verify that this state matches the header, -but also that the header is properly signed by the known validator set. -It will even update the validator set as needed, so long -as there have not been major changes and it is secure to do so. So, if you wonder -why the query may take a second... there is a lot of work going on in the -background to make sure even a lying full node can't trick your client. +Even if you don't see it in the UI, the result of every query comes with a +proof. This is a Merkle proof that the result of the query is actually +contained in the state. and the state's Merkle root is contained in a recent +block header. Behind the scenes, `countercli` will not only verify that this +state matches the header, but also that the header is properly signed by the +known validator set. It will even update the validator set as needed, so long +as there have not been major changes and it is secure to do so. So, if you +wonder why the query may take a second... there is a lot of work going on in +the background to make sure even a lying full node can't trick your client. In a latter [guide on InterBlockchainCommunication](ibc.md), we'll use these proofs to post transactions to other chains. ## Accounts and Transactions -For a better understanding of how to further use the tools, it helps to understand the -underlying data structures. +For a better understanding of how to further use the tools, it helps to +understand the underlying data structures. ### Accounts @@ -184,8 +227,8 @@ type Coin struct { } ``` -If you want to add more coins to a blockchain, you can do so manually in the `~/.basecoin/genesis.json` before -you start the blockchain for the first time. +If you want to add more coins to a blockchain, you can do so manually in the +`~/.basecoin/genesis.json` before you start the blockchain for the first time. Accounts are serialized and stored in a Merkle tree under the key `base/a/
`, where `
` is the address of the account. @@ -254,9 +297,10 @@ transaction. ## Conclusion -In this guide, we introduced the `basecoin` and `basecli` tools, -demonstrated how to start a new basecoin blockchain and how to send tokens between accounts, -and discussed the underlying data types for accounts and transactions, specifically the `Account` and the `SendTx`. -In the [next guide](basecoin-plugins.md), we introduce the Basecoin plugin system, -which uses a new transaction type, the `AppTx`, to extend the functionality of -the Basecoin system with arbitrary logic. +In this guide, we introduced the `basecoin` and `basecli` tools, demonstrated +how to start a new basecoin blockchain and how to send tokens between accounts, +and discussed the underlying data types for accounts and transactions, +specifically the `Account` and the `SendTx`. In the [next +guide](basecoin-plugins.md), we introduce the Basecoin plugin system, which +uses a new transaction type, the `AppTx`, to extend the functionality of the +Basecoin system with arbitrary logic. From 985665fb8adfa006c16651bf223eb9e4f7c7a1b6 Mon Sep 17 00:00:00 2001 From: rigel rozanski Date: Wed, 28 Jun 2017 05:49:49 -0400 Subject: [PATCH 2/8] working --- docs/guide/basecoin-basics.md | 22 +++++++++------------- 1 file changed, 9 insertions(+), 13 deletions(-) diff --git a/docs/guide/basecoin-basics.md b/docs/guide/basecoin-basics.md index 4e3464dbcd..78e586e044 100644 --- a/docs/guide/basecoin-basics.md +++ b/docs/guide/basecoin-basics.md @@ -1,15 +1,11 @@ + # Basecoin Plugins In the [previous guide](basecoin-basics.md), we saw how to use the `basecoin` -tool to start a blockchain and the `basecli` tools to send transactions. We also learned about -`Account` and `SendTx`, the basic data types giving us a multi-asset -cryptocurrency. Here, we will demonstrate how to extend the tools to -use another transaction type, the `AppTx`, so we can send data to a custom plugin. In -this example we explore a simple plugin named `counter`. +tool to start a blockchain and the `basecli` tools to send transactions. We +also learned about `Account` and `SendTx`, the basic data types giving us a +multi-asset cryptocurrency. Here, we will demonstrate how to extend the tools +to use another transaction type, the `AppTx`, so we can send data to a custom +plugin. In this example we explore a simple plugin named `counter`. ## Example Plugin @@ -25,7 +86,7 @@ and a coin amount named `countfee`. The transaction is only accepted if both A new blockchain can be initialized and started just like in the [previous guide](basecoin-basics.md): -``` +```shelldown[0] # WARNING: this wipes out data - but counter is only for demos... rm -rf ~/.counter countercli reset_all @@ -41,7 +102,7 @@ counter start The default files are stored in `~/.counter`. In another window we can initialize the light-client and send a transaction: -``` +```shelldown[1] countercli init --node=tcp://localhost:46657 --genesis=$HOME/.counter/genesis.json YOU=$(countercli keys get friend | awk '{print $2}') @@ -51,7 +112,7 @@ countercli tx send --name=cool --amount=1000mycoin --to=$YOU --sequence=1 But the Counter has an additional command, `countercli tx counter`, which crafts an `AppTx` specifically for this plugin: -``` +```shelldown[2] countercli tx counter --name cool --amount=1mycoin --sequence=2 countercli tx counter --name cool --amount=1mycoin --sequence=3 --valid ``` @@ -61,7 +122,7 @@ valid, while the second transaction passes. We can build plugins that take many arguments of different types, and easily extend the tool to accomodate them. Of course, we can also expose queries on our plugin: -``` +```shelldown[3] countercli query counter ``` @@ -70,7 +131,7 @@ should see a Counter value of 1 representing the number of valid transactions. If we send another transaction, and then query again, we will see the value increment: -``` +```shelldown[4] countercli tx counter --name cool --amount=2mycoin --sequence=4 --valid --countfee=2mycoin countercli query counter ``` From a7c07ab3c01123008bf32d02260055a917f3c1a7 Mon Sep 17 00:00:00 2001 From: rigel rozanski Date: Thu, 29 Jun 2017 04:18:28 -0400 Subject: [PATCH 6/8] Auto-tutorial basecoin-tool --- docs/guide/basecoin-tool.md | 80 +++++++++++++++++++++++++++++++------ 1 file changed, 67 insertions(+), 13 deletions(-) diff --git a/docs/guide/basecoin-tool.md b/docs/guide/basecoin-tool.md index eb35ec9ea1..00ced1bbfb 100644 --- a/docs/guide/basecoin-tool.md +++ b/docs/guide/basecoin-tool.md @@ -1,3 +1,57 @@ + + # The Basecoin Tool In previous tutorials we learned the [basics of the Basecoin @@ -9,7 +63,7 @@ details on using the Basecoin tool. Generate a key using the `basecli` tool: -``` +```shelldown[0] basecli keys new mykey ME=$(basecli keys get mykey | awk '{print $2}') ``` @@ -19,7 +73,7 @@ ME=$(basecli keys get mykey | awk '{print $2}') By default, `basecoin` works out of `~/.basecoin`. To change this, set the `BCHOME` environment variable: -``` +```shelldown[1] export BCHOME=~/.my_basecoin_data basecoin init $ME basecoin start @@ -27,7 +81,7 @@ basecoin start or -``` +```shelldown[2] BCHOME=~/.my_basecoin_data basecoin init $ME BCHOME=~/.my_basecoin_data basecoin start ``` @@ -38,7 +92,7 @@ So far we have run Basecoin and Tendermint in a single process. However, since we use ABCI, we can actually run them in different processes. First, initialize them: -``` +```shelldown[3] basecoin init $ME ``` @@ -47,13 +101,13 @@ information for both Basecoin and Tendermint. Now, In one window, run -``` +```shelldown[4] basecoin start --without-tendermint ``` and in another, -``` +```shelldown[5] TMROOT=~/.basecoin tendermint node ``` @@ -62,7 +116,7 @@ You should see Tendermint start making blocks! Alternatively, you could ignore the Tendermint details in `~/.basecoin/genesis.json` and use a separate directory by running: -``` +```shelldown[6] tendermint init tendermint node ``` @@ -81,14 +135,14 @@ Now let's make our own custom Basecoin data. First, create a new directory: -``` +```shelldown[7] mkdir example-data ``` We can tell `basecoin` to use this directory by exporting the `BCHOME` environment variable: -``` +```shelldown[8] export BCHOME=$(pwd)/example-data ``` @@ -97,13 +151,13 @@ variable to your shell startup scripts (eg. `~/.bashrc`). Now, let's create a new key: -``` +```shelldown[9] basecli keys new foobar ``` The key's info can be retrieved with -``` +```shelldown[10] basecli keys get foobar -o=json ``` @@ -173,13 +227,13 @@ guide](https://tendermint.com/docs/guides/using-tendermint). You can reset all blockchain data by running: -``` +```shelldown[11] basecoin unsafe_reset_all ``` Similarly, you can reset client data by running: -``` +```shelldown[12] basecli reset_all ``` From 4e93be304e4bb63424ea75f1346917030dc7e504 Mon Sep 17 00:00:00 2001 From: rigel rozanski Date: Thu, 29 Jun 2017 05:40:42 -0400 Subject: [PATCH 7/8] circle fix, minor IBC tutorial --- Makefile | 4 ++-- circle.yml | 1 + docs/guide/ibc.md | 52 +++++++++++++++++++++++++---------------------- 3 files changed, 31 insertions(+), 26 deletions(-) diff --git a/Makefile b/Makefile index 594cfab229..036d8fdabf 100644 --- a/Makefile +++ b/Makefile @@ -22,7 +22,7 @@ test_unit: go test `glide novendor` #go run tests/tendermint/*.go -test_cli: tests/cli/shunit2 +test_cli: get_shunit2 # sudo apt-get install jq @./tests/cli/basictx.sh @./tests/cli/counter.sh @@ -35,7 +35,7 @@ test_tutorial: bash $$script ; \ done -tests/cli/shunit2: +get_shunit2: wget "https://raw.githubusercontent.com/kward/shunit2/master/source/2.1/src/shunit2" \ -q -O tests/cli/shunit2 cp tests/cli/shunit2 docs/guide/shunit2 diff --git a/circle.yml b/circle.yml index 3034760d62..9884cd530e 100644 --- a/circle.yml +++ b/circle.yml @@ -12,6 +12,7 @@ dependencies: override: - go get github.com/Masterminds/glide - go version + - go get -u github.com/tendermint/tendermint/cmd/tendermint - glide --version - mkdir -p "$PROJECT_PARENT_PATH" - ln -sf "$HOME/$CIRCLE_PROJECT_REPONAME/" "$REPO" diff --git a/docs/guide/ibc.md b/docs/guide/ibc.md index c19d0d1854..0656fd3264 100644 --- a/docs/guide/ibc.md +++ b/docs/guide/ibc.md @@ -2,8 +2,8 @@ One of the most exciting elements of the Cosmos Network is the InterBlockchain Communication (IBC) protocol, which enables interoperability across different -blockchains. We implemented IBC as a basecoin plugin, and we'll show you -how to use it to send tokens across blockchains! +blockchains. We implemented IBC as a basecoin plugin, and we'll show you how to +use it to send tokens across blockchains! Please note, this tutorial assumes you are familiar with [Basecoin plugins](/docs/guide/basecoin-plugins.md), but we'll explain how IBC works. You @@ -175,15 +175,15 @@ The results of a query can thus be used as proof in an `IBCPacketPostTx`. ## Relay -While we need all these packet types internally to keep track of all the -proofs on both chains in a secure manner, for the normal work-flow, -we can run a relay node that handles the cross-chain interaction. +While we need all these packet types internally to keep track of all the proofs +on both chains in a secure manner, for the normal work-flow, we can run a relay +node that handles the cross-chain interaction. -In this case, there are only two steps. First `basecoin relay init`, -which must be run once to register each chain with the other one, -and make sure they are ready to send and recieve. And then -`basecoin relay start`, which is a long-running process polling the queue -on each side, and relaying all new message to the other block. +In this case, there are only two steps. First `basecoin relay init`, which +must be run once to register each chain with the other one, and make sure they +are ready to send and recieve. And then `basecoin relay start`, which is a +long-running process polling the queue on each side, and relaying all new +message to the other block. This requires that the relay has access to accounts with some funds on both chains to pay for all the ibc packets it will be forwarding. @@ -195,14 +195,14 @@ tutorial. Make sure you have installed [basecoin and basecli](/docs/guide/install.md). -Basecoin is a framework for creating new cryptocurrency applications. It -comes with an `IBC` plugin enabled by default. +Basecoin is a framework for creating new cryptocurrency applications. It comes +with an `IBC` plugin enabled by default. You will also want to install the [jq](https://stedolan.github.io/jq/) for handling JSON at the command line. -If you have any trouble with this, you can also look at the -[test scripts](/tests/cli/ibc.sh) or just run `make test_cli` in basecoin repo. +If you have any trouble with this, you can also look at the [test +scripts](/tests/cli/ibc.sh) or just run `make test_cli` in basecoin repo. Otherwise, open up 5 (yes 5!) terminal tabs.... ### Preliminaries @@ -225,7 +225,9 @@ alias basecoin1="basecoin --home $BCHOME1_SERVER" alias basecoin2="basecoin --home $BCHOME2_SERVER" ``` -This will give us some new commands to use instead of raw `basecli` and `basecoin` to ensure we're using the right configuration for the chain we want to talk to. +This will give us some new commands to use instead of raw `basecli` and +`basecoin` to ensure we're using the right configuration for the chain we want +to talk to. We also want to set some chain IDs: @@ -234,7 +236,8 @@ export CHAINID1="test-chain-1" export CHAINID2="test-chain-2" ``` -And since we will run two different chains on one machine, we need to maintain different sets of ports: +And since we will run two different chains on one machine, we need to maintain +different sets of ports: ``` export PORT_PREFIX1=1234 @@ -282,8 +285,9 @@ basecli1 query account $GOTNONE ### Setup Chain 2 -This is the same as above, except with `basecli2`, `basecoin2`, and `$CHAINID2`. -We will also need to change the ports, since we're running another chain on the same local machine. +This is the same as above, except with `basecli2`, `basecoin2`, and +`$CHAINID2`. We will also need to change the ports, since we're running +another chain on the same local machine. Let's create new keys for test-chain-2: @@ -315,13 +319,13 @@ basecli2 query account $BROKE ### Connect these chains -OK! So we have two chains running on your local machine, with different -keys on each. Let's hook them up together by starting a relay process to -forward messages from one chain to the other. +OK! So we have two chains running on your local machine, with different keys on +each. Let's hook them up together by starting a relay process to forward +messages from one chain to the other. -The relay account needs some money in it to pay for the ibc messages, so -for now, we have to transfer some cash from the rich accounts before we start -the actual relay. +The relay account needs some money in it to pay for the ibc messages, so for +now, we have to transfer some cash from the rich accounts before we start the +actual relay. ``` # note that this key.json file is a hardcoded demo for all chains, this will From 78787ccd239becb49fc99dc75da6e67808bbf144 Mon Sep 17 00:00:00 2001 From: Ethan Frey Date: Thu, 29 Jun 2017 14:52:38 +0200 Subject: [PATCH 8/8] Cleanup Makefile - cache shunit2 files --- Makefile | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/Makefile b/Makefile index 036d8fdabf..b13954ce4f 100644 --- a/Makefile +++ b/Makefile @@ -22,23 +22,26 @@ test_unit: go test `glide novendor` #go run tests/tendermint/*.go -test_cli: get_shunit2 +test_cli: tests/cli/shunit2 # sudo apt-get install jq @./tests/cli/basictx.sh @./tests/cli/counter.sh @./tests/cli/restart.sh @./tests/cli/ibc.sh -test_tutorial: +test_tutorial: docs/guide/shunit2 shelldown ${TUTORIALS} for script in docs/guide/*.sh ; do \ bash $$script ; \ done -get_shunit2: +tests/cli/shunit2: wget "https://raw.githubusercontent.com/kward/shunit2/master/source/2.1/src/shunit2" \ -q -O tests/cli/shunit2 - cp tests/cli/shunit2 docs/guide/shunit2 + +docs/guide/shunit2: + wget "https://raw.githubusercontent.com/kward/shunit2/master/source/2.1/src/shunit2" \ + -q -O docs/guide/shunit2 get_vendor_deps: tools glide install