Ran through the docs, more cleanup, everything except ibc ready
This commit is contained in:
Ethan Frey
@@ -1,6 +1,6 @@
|
||||
# Basecoin Basics
|
||||
|
||||
Here we explain how to get started with a simple Basecoin blockchain,
|
||||
Here we explain how to get started with a simple Basecoin blockchain,
|
||||
how to send transactions between accounts using the `basecoin` tool,
|
||||
and what is happening under the hood.
|
||||
|
||||
@@ -9,7 +9,7 @@ and what is happening under the hood.
|
||||
Installing Basecoin is simple:
|
||||
|
||||
```
|
||||
go get -u github.com/tendermint/basecoin/cmd/basecoin
|
||||
go get -u github.com/tendermint/basecoin/cmd/...
|
||||
```
|
||||
|
||||
If you have trouble, see the [installation guide](install.md).
|
||||
@@ -19,7 +19,10 @@ If you have trouble, see the [installation guide](install.md).
|
||||
To initialize a new Basecoin blockchain, run:
|
||||
|
||||
```
|
||||
basecoin init
|
||||
# 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
|
||||
basecoin init
|
||||
```
|
||||
|
||||
This will create the necessary files for a Basecoin blockchain with one
|
||||
@@ -30,6 +33,9 @@ For this example, we will change the genesis account to a new account named
|
||||
`cool`. First create a new account:
|
||||
|
||||
```
|
||||
# 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
|
||||
basecli keys new cool
|
||||
```
|
||||
|
||||
@@ -46,17 +52,18 @@ basecli keys get cool -o=json
|
||||
vi ~/.basecoin/genesis.json
|
||||
-> cut/paste your pubkey from the results above
|
||||
```
|
||||
or alternatively, without manual copy pasting:
|
||||
or alternatively, without manual copy pasting:
|
||||
```
|
||||
GENKEY=`basecli keys get cool -o json | jq .pubkey.data`
|
||||
GENJSON=`cat ~/.basecoin/genesis.json`
|
||||
echo $GENJSON | jq '.app_options.accounts[0].pub_key.data='$GENKEY > ~/.basecoin/genesis.json
|
||||
echo $GENJSON | jq '.app_options.accounts[0].pub_key.data='$GENKEY > ~/.basecoin/genesis.json
|
||||
```
|
||||
|
||||
Hurray! you are very rich and cool on this blockchain now.
|
||||
|
||||
## Start
|
||||
|
||||
|
||||
Now we can start Basecoin:
|
||||
|
||||
```
|
||||
@@ -106,7 +113,7 @@ basecli query account $YOU
|
||||
We can send some of these coins back like so:
|
||||
|
||||
```
|
||||
basecli tx send --name=friend --amount=500mycoin --to=0x$ME --sequence=1
|
||||
basecli tx send --name=friend --amount=500mycoin --to=$ME --sequence=1
|
||||
```
|
||||
|
||||
Note how we use the `--name` flag to select a different account to send from.
|
||||
@@ -114,7 +121,16 @@ 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:
|
||||
|
||||
```
|
||||
basecli tx send --name=friend --amount=500000mycoin --to=0x$ME --sequence=1
|
||||
basecli tx send --name=friend --amount=500000mycoin --to=$ME --sequence=1
|
||||
```
|
||||
|
||||
And if you want to see the original tx, as well as verifying that it
|
||||
really is in the blockchain, look at the send response:
|
||||
|
||||
```
|
||||
basecli tx send --name=cool --amount=2345mycoin --to=$YOU --sequence=2
|
||||
# TXHASH from the json output
|
||||
basecli query tx $TXHASH
|
||||
```
|
||||
|
||||
See `basecli tx send --help` for additional details.
|
||||
|
||||
@@ -14,24 +14,28 @@ functionality. The Counter plugin is bundled with basecoin, so if you have
|
||||
already [installed basecoin](install.md) then you should be able to run a full
|
||||
node with `counter` and the a light-client `countercli` from terminal. The
|
||||
Counter plugin is just like the `basecoin` tool. They both use the same
|
||||
library of commands, including one for signing and broadcasting `SendTx`.
|
||||
library of commands, including one for signing and broadcasting `SendTx`.
|
||||
|
||||
Counter transactions take two custom inputs, a boolean argument named `valid`,
|
||||
and a coin amount named `countfee`. The transaction is only accepted if both
|
||||
`valid` is set to true and the transaction input coins is greater than
|
||||
`countfee` that the user provides.
|
||||
`countfee` that the user provides.
|
||||
|
||||
A new blockchain can be initialized and started just like with in the [previous
|
||||
guide](basecoin-basics.md):
|
||||
|
||||
```
|
||||
# WARNING: this wipes out data - but counter is only for demos...
|
||||
rm -rf ~/.counter
|
||||
countercli reset_all
|
||||
|
||||
counter init
|
||||
countercli keys new cool
|
||||
countercli keys new friend
|
||||
|
||||
GENKEY=`countercli keys get cool -o json | jq .pubkey.data`
|
||||
GENJSON=`cat ~/.counter/genesis.json`
|
||||
echo $GENJSON | jq '.app_options.accounts[0].pub_key.data='$GENKEY > ~/.counter/genesis.json
|
||||
echo $GENJSON | jq '.app_options.accounts[0].pub_key.data='$GENKEY > ~/.counter/genesis.json
|
||||
|
||||
counter start
|
||||
|
||||
@@ -58,7 +62,7 @@ countercli tx counter --name cool --amount=1mycoin --sequence=3 --valid
|
||||
The first transaction is rejected by the plugin because it was not marked as
|
||||
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:
|
||||
them. Of course, we can also expose queries on our plugin:
|
||||
|
||||
```
|
||||
countercli query counter
|
||||
@@ -70,15 +74,25 @@ If we send another transaction, and then query again, we will see the value
|
||||
increment:
|
||||
|
||||
```
|
||||
countercli tx counter --name cool --amount=1mycoin --sequence=4 --valid
|
||||
countercli tx counter --name cool --amount=2mycoin --sequence=4 --valid --countfee=2mycoin
|
||||
countercli query counter
|
||||
```
|
||||
|
||||
The value Counter value should be 2, because we sent a second valid transaction.
|
||||
Notice how the result of the query comes with a proof. This is a Merkle proof
|
||||
that the state is what we say it is. In a latter [guide on InterBlockchain
|
||||
Communication](ibc.md), we'll put this proof to work!
|
||||
And this time, since we sent a countfee (which must be less than or equal to the
|
||||
total amount sent with the tx), it stores the `TotalFees` on the counter as well.
|
||||
|
||||
Even if you don't see it in the UI, the result of the query comes with a proof.
|
||||
This is a Merkle proof that the state is what we say it is, and ties that query
|
||||
to a particular 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.
|
||||
|
||||
Now, before we implement our own plugin and tooling, it helps to understand the
|
||||
`AppTx` and the design of the plugin system.
|
||||
@@ -91,8 +105,8 @@ some data.
|
||||
|
||||
```golang
|
||||
type AppTx struct {
|
||||
Gas int64 `json:"gas"`
|
||||
Fee Coin `json:"fee"`
|
||||
Gas int64 `json:"gas"`
|
||||
Fee Coin `json:"fee"`
|
||||
Input TxInput `json:"input"`
|
||||
Name string `json:"type"` // Name of the plugin
|
||||
Data []byte `json:"data"` // Data for the plugin to process
|
||||
@@ -161,18 +175,19 @@ more details.
|
||||
|
||||
First is the `cmd/counter/main.go`, which drives the program. It can be left
|
||||
alone, but you should change any occurrences of `counter` to whatever your
|
||||
plugin tool is going to be called.
|
||||
plugin tool is going to be called. You must also register your plugin(s) with
|
||||
the basecoin app with `RegisterStartPlugin`.
|
||||
|
||||
The light-client which is located in `cmd/countercli/main.go` allows for is
|
||||
where transaction and query commands are designated. Similarity this command
|
||||
can be mostly left alone besides replacing the application name and adding
|
||||
references to new plugin commands
|
||||
references to new plugin commands
|
||||
|
||||
Next is the custom commands in `cmd/countercli/commands/`. These files is
|
||||
where we extend the tool with any new commands and flags we need to send
|
||||
transactions or queries to our plugin. Note the `init()` function, where we
|
||||
register a new transaction subcommand with `RegisterTxSubcommand`, and where we
|
||||
load the plugin into the Basecoin app with `RegisterStartPlugin`.
|
||||
transactions or queries to our plugin. You define custom `tx` and `query`
|
||||
subcommands, which are registered in `main.go` (avoiding `init()`
|
||||
auto-registration, for less magic and more control in the main executable).
|
||||
|
||||
Finally is `plugins/counter/counter.go`, where we provide an implementation of
|
||||
the `Plugin` interface. The most important part of the implementation is the
|
||||
|
||||
@@ -3,8 +3,7 @@
|
||||
On a good day, basecoin can be installed like a normal Go program:
|
||||
|
||||
```
|
||||
go get github.com/tendermint/basecoin/
|
||||
make all
|
||||
go get -u github.com/tendermint/basecoin/cmd/...
|
||||
```
|
||||
|
||||
In some cases, if that fails, or if another branch is required,
|
||||
@@ -15,7 +14,6 @@ the correct way to install is:
|
||||
```
|
||||
cd $GOPATH/src/github.com/tendermint/basecoin
|
||||
git pull origin master
|
||||
make get_vendor_deps
|
||||
make all
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user