Skip to content

Commit

Permalink
update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@ebuchman
ebuchman committed Mar 14, 2017
1 parent 0943329 commit fa5d7b3
Show file tree
Hide file tree
Showing 4 changed files with 78 additions and 51 deletions.
88 changes: 60 additions & 28 deletions docs/guide/basecoin-tool.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,18 +4,36 @@ In previous tutorials we learned the [basics of the `basecoin` CLI](/docs/guides
and [how to implement a plugin](/docs/guides/example-plugin).
In this tutorial, we provide more details on using the `basecoin` tool.

# Data Directory

By default, `basecoin` works out of `~/.basecoin`. To change this, set the `BCHOME` environment variable:

```
export BCHOME=~/.my_basecoin_data
basecoin init
basecoin start
```

or

```
BCHOME=~/.my_basecoin_data basecoin init
BCHOME=~/.my_basecoin_data basecoin start
```

# ABCI Server

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 both Basecoin and Tendermint:
First, initialize them:

```
basecoin init
tendermint init
```

In one window, run
This will create a single `genesis.json` file in `~/.basecoin` with the information for both Basecoin and Tendermint.

Now, In one window, run

```
basecoin start --without-tendermint
Expand All @@ -24,17 +42,24 @@ basecoin start --without-tendermint
and in another,

```
tendermint node
TMROOT=~/.basecoin tendermint node
```

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:

```
tendermint init
tendermint node
```

For more details on using `tendermint`, see [the guide](https://tendermint.com/docs/guides/using-tendermint).

# Keys and Genesis

In previous tutorials we used `basecoin init` to initialize `~/.basecoin` with the default configuration.
This command creates files both for Tendermint and for Basecoin.
The Tendermint files are stored in `~/.basecoin/tendermint`, and are the same type of files that would exist in `~/.tendermint` after running `tendermint init`.
This command creates files both for Tendermint and for Basecoin, and a single `genesis.json` file for both of them.
For more information on these files, see the [guide to using tendermint](https://tendermint.com/docs/guides/using-tendermint).

Now let's make our own custom Basecoin data.
Expand All @@ -59,19 +84,19 @@ Now, let's create a new private key:
basecoin key new > $BCHOME/key.json
```

Here's what my `key.json looks like:
Here's what my `key.json looks like (TODO: change `keys` so it looks like this ...):

```json
{
"address": "15F591CA434CFCCBDEC1D206F3ED3EBA207BFE7D",
"priv_key": [
1,
"737C629667A9EAADBB8E7CF792D5A8F63AA4BB51E06457DDD7FDCC6D7412AAAD43AA6C88034F9EB8D2717CA4BBFCBA745EFF19B13EFCD6F339EDBAAAFCD2F7B3"
],
"pub_key": [
1,
"43AA6C88034F9EB8D2717CA4BBFCBA745EFF19B13EFCD6F339EDBAAAFCD2F7B3"
]
"address": "4EGEhnqOw/gX326c7KARUkY1kic=",
"pub_key": {
"type": "ed25519",
"data": "a20d48b5caff42892d0ac67ccdeee38c1dcbbe42b15b486057d16244541e8141"
},
"priv_key": {
"type": "ed25519",
"data": "654c845f4b36d1a881deb0ff09381165d3ccd156b4aabb5b51267e91f1d024a5a20d48b5caff42892d0ac67ccdeee38c1dcbbe42b15b486057d16244541e8141"
}
}
```

Expand All @@ -80,26 +105,33 @@ Yours will look different - each key is randomly derrived.
Now we can make a `genesis.json` file and add an account with our public key:

```json
[
"base/chain_id", "example-chain",
"base/account", {
"pub_key": [1, "43AA6C88034F9EB8D2717CA4BBFCBA745EFF19B13EFCD6F339EDBAAAFCD2F7B3"],
"coins": [
{
"denom": "gold",
"amount": 1000000000,
}
]
{
"chain_id": "example-chain",
"app_options": {
"accounts": [{
"pub_key": {
"type": "ed25519",
"data": "a20d48b5caff42892d0ac67ccdeee38c1dcbbe42b15b486057d16244541e8141"
},
"coins": [
{
"denom": "gold",
"amount": 1000000000
}
]
}]
}
]
}
```

Here we've granted ourselves `1000000000` units of the `gold` token.
Note that we've also set the `base/chain_id` to be `example-chain`.
Note that we've also set the `chain_id` to be `example-chain`.
All transactions must therefore include the `--chain_id example-chain` in order to make sure they are valid for this chain.
Previously, we didn't need this flag because we were using the default chain ID ("test_chain_id").
Now that we're using a custom chain, we need to specify the chain explicitly on the command line.

Note we have also left out the details of the tendermint genesis. These are documented in the [tendermint guide](https://tendermint.com/docs/guides/using-tendermint).


# Reset

Expand Down
8 changes: 4 additions & 4 deletions docs/guide/example-plugin.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -319,21 +319,21 @@ example-plugin start
In another window, we can try sending some transactions:

```
example-plugin tx send --to 0x1B1BE55F969F54064628A63B9559E7C21C925165 --amount 100gold
example-plugin tx send --to 0x1DA7C74F9C219229FD54CC9F7386D5A3839F0090 --amount 100mycoin
```

Ok, so that's how we can send a `SendTx` transaction using our `example-plugin` CLI,
but we were already able to do that with the `basecoin` CLI.
With our new CLI, however, we can also send an `ExamplePluginTx`:

```
example-plugin tx example --amount 1gold
example-plugin tx example --amount 1mycoin
```

The transaction is invalid! That's because we didn't specify the `--valid` flag:

```
example-plugin tx example --valid --amount 1gold
example-plugin tx example --valid --amount 1mycoin
```

Tada! We successfuly created, signed, broadcast, and processed our custom transaction type.
Expand All @@ -353,7 +353,7 @@ which contains only an integer.
If we send another transaction, and then query again, we'll see the value increment:

```
example-plugin tx example --valid --amount 1gold
example-plugin tx example --valid --amount 1mycoin
example-plugin query ExamplePlugin.State
```

Expand Down
14 changes: 7 additions & 7 deletions docs/guide/ibc.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -194,15 +194,15 @@ The relevant data is now in the `data` directory.
We can start the two chains as follows:

```
TMROOT=./data/chain1/tendermint tendermint node &> chain1_tendermint.log &
BCHOME=./data/chain1/basecoin basecoin start --without-tendermint &> chain1_basecoin.log &
TMROOT=./data/chain1 tendermint node &> chain1_tendermint.log &
BCHOME=./data/chain1 basecoin start --without-tendermint &> chain1_basecoin.log &
```

and

```
TMROOT=./data/chain2/tendermint tendermint node --node_laddr tcp://localhost:36656 --rpc_laddr tcp://localhost:36657 --proxy_app tcp://localhost:36658 &> chain2_tendermint.log &
BCHOME=./data/chain2/basecoin basecoin start --without-tendermint --address tcp://localhost:36658 &> chain2_basecoin.log &
TMROOT=./data/chain2 tendermint node --node_laddr tcp://localhost:36656 --rpc_laddr tcp://localhost:36657 --proxy_app tcp://localhost:36658 &> chain2_tendermint.log &
BCHOME=./data/chain2 basecoin start --without-tendermint --address tcp://localhost:36658 &> chain2_basecoin.log &
```

Note how we refer to the relevant data directories. Also note how we have to set the various addresses for the second node so as not to conflict with the first.
Expand All @@ -224,16 +224,16 @@ For the sake of convenience, let's first set some environment variables:
export CHAIN_ID1=test_chain_1
export CHAIN_ID2=test_chain_2
export CHAIN_FLAGS1="--chain_id $CHAIN_ID1 --from ./data/chain1/basecoin/key.json"
export CHAIN_FLAGS2="--chain_id $CHAIN_ID2 --from ./data/chain2/basecoin/key.json --node tcp://localhost:36657"
export CHAIN_FLAGS1="--chain_id $CHAIN_ID1 --from ./data/chain1/key.json"
export CHAIN_FLAGS2="--chain_id $CHAIN_ID2 --from ./data/chain2/key.json --node tcp://localhost:36657"
export BCHOME="."
```

Let's start by registering `test_chain_1` on `test_chain_2`:

```
basecoin tx ibc --amount 10mycoin $CHAIN_FLAGS2 register --chain_id $CHAIN_ID1 --genesis ./data/chain1/tendermint/genesis.json
basecoin tx ibc --amount 10mycoin $CHAIN_FLAGS2 register --chain_id $CHAIN_ID1 --genesis ./data/chain1/genesis.json
```

Now we can create the outgoing packet on `test_chain_1`:
Expand Down
19 changes: 7 additions & 12 deletions docs/guide/more-examples.md
View file
Original file line number Diff line number Diff line change
@@ -1,19 +1,14 @@
# Plugin Examples

Now that we've seen [how to write a simple plugin](example-plugin.md)
and taken a look at [how the plugin system is designed](plugin-design.md),
Now that we've seen [how to write a simple plugin](/docs/guide/example-plugin.md)
and taken a look at [how the plugin system is designed](/docs/guide/plugin-design.md),
it's time for some more advanced examples.

For now, most examples are contained in the `github.com/tendermint/basecoin-examples` repository.
In particular, we have the following:

1. [Mintcoin][0] - a plugin for issuing new Basecoin tokens
2. [Trader][1] - a plugin for adding escrow and options features to Basecoin
3. [Stakecoin][2] - a plugin for bonding and unbonding Tendermint validators and updating the validator set accordingly
4. [PayToVote][3] - a plugin for creating issues and voting on them
5. [IBC][4] - a plugin for facilitating InterBlockchain Communication
[0]: https://github.com/tendermint/basecoin-examples/tree/develop/mintcoin
[1]: https://github.com/tendermint/basecoin-examples/tree/develop/trader
[2]: https://github.com/tendermint/basecoin-examples/tree/develop/stake
[3]: https://github.com/tendermint/basecoin-examples/tree/develop/paytovote
[4]: ibc.md
1. [Mintcoin](https://github.com/tendermint/basecoin-examples/tree/develop/mintcoin) - a plugin for issuing new Basecoin tokens
2. [Trader](https://github.com/tendermint/basecoin-examples/tree/develop/trader) - a plugin for adding escrow and options features to Basecoin
3. [Stakecoin](https://github.com/tendermint/basecoin-examples/tree/develop/stake) - a plugin for bonding and unbonding Tendermint validators and updating the validator set accordingly
4. [PayToVote](https://github.com/tendermint/basecoin-examples/tree/develop/paytovote) - a plugin for creating issues and voting on them
5. [IBC](/docs/guide/ibc.md) - a plugin for facilitating InterBlockchain Communication

0 comments on commit fa5d7b3

Please sign in to comment.