doc revisit basecoin-basics.md
This commit is contained in:
parent
a20b640f05
commit
7dad89b152
|
@ -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)
|
||||
|
|
|
@ -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.
|
||||
|
|
|
@ -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.
|
||||
|
||||
|
|
Loading…
Reference in New Issue