certusone
/
cosmos-sdk
mirror of https://github.com/certusone/cosmos-sdk.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

doc revisit basecoin-basics.md

This commit is contained in:
rigel rozanski 2017-06-17 21:15:54 -04:00
parent a20b640f05
commit 7dad89b152
3 changed files with 111 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/go_basics.md
View File

@ -115,7 +115,7 @@ git log | head -1
In the main repo (tendermint, basecoin, ...) where the binary will be built:
```
cd $GOPATH/src/github.com/tendermint/tendermin
cd $GOPATH/src/github.com/tendermint/tendermint
git checkout master
git pull
# -> edit glide.lock, set the version of go-p2p (for example)

169
docs/guide/basecoin-basics.md
View File

@ -6,7 +6,7 @@ and what is happening under the hood.
## Install
Installing basecoin is simple:
Installing Basecoin is simple:
```
go get -u github.com/tendermint/basecoin/cmd/basecoin
@ -14,7 +14,7 @@ go get -u github.com/tendermint/basecoin/cmd/basecoin
If you have trouble, see the [installation guide](install.md).
## Initialization
## Initialize Basecoin
To initialize a new Basecoin blockchain, run:
@ -22,12 +22,42 @@ To initialize a new Basecoin blockchain, run:
basecoin init
```
This will create the necessary files for a Basecoin blockchain with one validator and one account in `~/.basecoin`.
For more options on setup, see the [guide to using the Basecoin tool](/docs/guide/basecoin-tool.md).
This will create the necessary files for a Basecoin blockchain with one
validator and one account in `~/.basecoin`. For more options on setup, see the
[guide to using the Basecoin tool](/docs/guide/basecoin-tool.md).
For this example, we will change the genesis account to a new account named
`cool`. First create a new account:
```
basecli keys new cool
```
While we're at it let's setup a second account which we will use later in the tutorial
```
basecli keys new friend
```
Next we need to copy in the public address from our new key into the genesis block:
```
basecli keys get cool -o=json
vi ~/.basecoin/genesis.json
-> cut/paste your pubkey from the results above
```
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
```
Hurray! you are very rich and cool on this blockchain now.
## Start
Now we can start basecoin:
Now we can start Basecoin:
```
basecoin start
@ -35,64 +65,71 @@ basecoin start
You should see blocks start streaming in!
## Send transactions
## Initialize Light-Client
Now we are ready to send some transactions. First, open another window.
If you take a look at the `~/.basecoin/genesis.json` file, you will see one account listed under the `app_options`.
This account corresponds to the private key in `~/.basecoin/key.json`.
We also included the private key for another account, in `~/.basecoin/key2.json`.
Leave basecoin running and open a new terminal window.
Let's check the balance of these two accounts:
Now that Basecoin is running we can initialize the light-client utility named
`basecli`. Basecli is used for sending transactions and querying the state.
Leave Basecoin running and open a new terminal window. Here run:
```
basecoin account 0x1B1BE55F969F54064628A63B9559E7C21C925165
basecoin account 0x1DA7C74F9C219229FD54CC9F7386D5A3839F0090
basecli init --chain-id=test_chain_id --node=tcp://localhost:46657
```
## Send transactions
Now we are ready to send some transactions. First Let's check the balance of
the two accounts we setup earlier these two accounts:
```
ME=`basecli keys get cool -o=json | jq .address | tr -d '"'`
YOU=`basecli keys get friend -o=json | jq .address | tr -d '"'`
basecli query account $ME
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:
```
basecoin tx send --to 0x1DA7C74F9C219229FD54CC9F7386D5A3839F0090 --amount 10mycoin
basecli tx send --name=cool --amount=1000mycoin --to=0x$YOU --sequence=1
```
By default, the CLI looks for a `key.json` to sign the transaction with.
To specify a different key, we can use the `--from` flag.
Now if we check the second account, it should have `10` 'mycoin' coins!
Now if we check the second account, it should have `1000` 'mycoin' coins!
```
basecoin account 0x1DA7C74F9C219229FD54CC9F7386D5A3839F0090
basecli query account $YOU
```
We can send some of these coins back like so:
```
basecoin tx send --to 0x1B1BE55F969F54064628A63B9559E7C21C925165 --from key2.json --amount 5mycoin
basecli tx send --name=friend --amount=500mycoin --to=0x$ME --sequence=1
```
Note how we use the `--from` flag to select a different account to send from.
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:
```
basecoin tx send --to 0x1B1BE55F969F54064628A63B9559E7C21C925165 --from key2.json --amount 100mycoin
basecli tx send --name=friend --amount=500000mycoin --to=0x$ME --sequence=1
```
See `basecoin tx send --help` for additional details.
See `basecli tx send --help` for additional details.
For a better understanding of the options, it helps to understand the underlying data structures.
For a better understanding of the options, it helps to understand the
underlying data structures.
## Accounts
The Basecoin state consists entirely of a set of accounts.
Each account contains a public key,
a balance in many different coin denominations,
and a strictly increasing sequence number for replay protection.
This type of account was directly inspired by accounts in Ethereum,
and is unlike Bitcoin's use of Unspent Transaction Outputs (UTXOs).
Note Basecoin is a multi-asset cryptocurrency, so each account can have many different kinds of tokens.
The Basecoin state consists entirely of a set of accounts. Each account
contains a public key, a balance in many different coin denominations, and a
strictly increasing sequence number for replay protection. This type of
account was directly inspired by accounts in Ethereum, and is unlike Bitcoin's
use of Unspent Transaction Outputs (UTXOs). Note Basecoin is a multi-asset
cryptocurrency, so each account can have many different kinds of tokens.
```golang
type Account struct {
@ -109,17 +146,21 @@ type Coin struct {
}
```
Accounts are serialized and stored in a Merkle tree under the key `base/a/<address>`, where `<address>` is the address of the account.
Typically, the address of the account is the 20-byte `RIPEMD160` hash of the public key, but other formats are acceptable as well,
as defined in the [Tendermint crypto library](https://github.com/tendermint/go-crypto).
The Merkle tree used in Basecoin is a balanced, binary search tree, which we call an [IAVL tree](https://github.com/tendermint/go-merkle).
Accounts are serialized and stored in a Merkle tree under the key
`base/a/<address>`, where `<address>` is the address of the account.
Typically, the address of the account is the 20-byte `RIPEMD160` hash of the
public key, but other formats are acceptable as well, as defined in the
[Tendermint crypto library](https://github.com/tendermint/go-crypto). The
Merkle tree used in Basecoin is a balanced, binary search tree, which we call
an [IAVL tree](https://github.com/tendermint/go-merkle).
## Transactions
Basecoin defines a simple transaction type, the `SendTx`, which allows tokens to be sent to other accounts.
The `SendTx` takes a list of inputs and a list of outputs,
and transfers all the tokens listed in the inputs from their corresponding accounts to the accounts listed in the output.
The `SendTx` is structured as follows:
Basecoin defines a simple transaction type, the `SendTx`, which allows tokens
to be sent to other accounts. The `SendTx` takes a list of inputs and a list
of outputs, and transfers all the tokens listed in the inputs from their
corresponding accounts to the accounts listed in the output. The `SendTx` is
structured as follows:
```golang
type SendTx struct {
@ -143,32 +184,38 @@ type TxOutput struct {
}
```
Note the `SendTx` includes a field for `Gas` and `Fee`.
The `Gas` limits the total amount of computation that can be done by the transaction,
while the `Fee` refers to the total amount paid in fees.
This is slightly different from Ethereum's concept of `Gas` and `GasPrice`,
where `Fee = Gas x GasPrice`. In Basecoin, the `Gas` and `Fee` are independent,
and the `GasPrice` is implicit.
Note the `SendTx` includes a field for `Gas` and `Fee`. The `Gas` limits the
total amount of computation that can be done by the transaction, while the
`Fee` refers to the total amount paid in fees. This is slightly different from
Ethereum's concept of `Gas` and `GasPrice`, where `Fee = Gas x GasPrice`. In
Basecoin, the `Gas` and `Fee` are independent, and the `GasPrice` is implicit.
In Basecoin, the `Fee` is meant to be used by the validators to inform the ordering
of transactions, like in Bitcoin. And the `Gas` is meant to be used by the application
plugin to control its execution. There is currently no means to pass `Fee` information
to the Tendermint validators, but it will come soon...
In Basecoin, the `Fee` is meant to be used by the validators to inform the
ordering of transactions, like in Bitcoin. And the `Gas` is meant to be used
by the application plugin to control its execution. There is currently no
means to pass `Fee` information to the Tendermint validators, but it will come
soon...
Note also that the `PubKey` only needs to be sent for `Sequence == 0`.
After that, it is stored under the account in the Merkle tree and subsequent transactions can exclude it,
using only the `Address` to refer to the sender. Ethereum does not require public keys to be sent in transactions
as it uses a different elliptic curve scheme which enables the public key to be derived from the signature itself.
Note also that the `PubKey` only needs to be sent for `Sequence == 0`. After
that, it is stored under the account in the Merkle tree and subsequent
transactions can exclude it, using only the `Address` to refer to the sender.
Ethereum does not require public keys to be sent in transactions as it uses a
different elliptic curve scheme which enables the public key to be derived from
the signature itself.
Finally, note that the use of multiple inputs and multiple outputs allows us to send many
different types of tokens between many different accounts at once in an atomic transaction.
Thus, the `SendTx` can serve as a basic unit of decentralized exchange. When using multiple
inputs and outputs, you must make sure that the sum of coins of the inputs equals the sum of
coins of the outputs (no creating money), and that all accounts that provide inputs have signed the transaction.
Finally, note that the use of multiple inputs and multiple outputs allows us to
send many different types of tokens between many different accounts at once in
an atomic transaction. Thus, the `SendTx` can serve as a basic unit of
decentralized exchange. When using multiple inputs and outputs, you must make
sure that the sum of coins of the inputs equals the sum of coins of the outputs
(no creating money), and that all accounts that provide inputs have signed the
transaction.
## Conclusion
In this guide, we introduced the `basecoin` tool, demonstrated how to use it 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` tool, demonstrated how to use it 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.

4
docs/guide/basecoin-tool.md
View File

@ -125,8 +125,8 @@ Now we can make a `genesis.json` file and add an account with our public key:
```
Here we've granted ourselves `1000000000` units of the `gold` token.
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.
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.