README.md

   1 Bytom
   2 =====
   3 [![Build Status](https://travis-ci.org/Bytom/bytom.svg)](https://travis-ci.org/Bytom/bytom)
   4 [![AGPL v3](https://img.shields.io/badge/license-AGPL%20v3-brightgreen.svg)](./LICENSE)
   5
   6 ## Table of Contents
   7 <!-- vim-markdown-toc GFM -->
   8
   9 * [What is Bytom?](#what-is-bytom)
  10 * [Build from source](#build-from-source)
  11   * [Requirements](#requirements)
  12   * [Installation](#installation)
  13     * [Get the source code](#get-the-source-code)
  14     * [Build](#build)
  15 * [Example](#example)
  16   * [Create and launch a single node](#create-and-launch-a-single-node)
  17     * [Create an account](#create-an-account)
  18     * [Create an asset](#create-an-asset)
  19     * [Asset issuance test](#asset-issuance-test)
  20     * [Expenditure test](#expenditure-test)
  21   * [Set up a wallet and manage the key](#set-up-a-wallet-and-manage-the-key)
  22   * [Multiple node](#multiple-node)
  23 * [Running Bytom in Docker](#running-bytom-in-docker)
  24 * [Contributing](#contributing)
  25 * [License](#license)
  26
  27 <!-- vim-markdown-toc -->
  28
  29 ## What is Bytom?
  30
  31 Bytom is software designed to operate and connect to highly scalable blockchain networks confirming to the Bytom Blockchain Protocol, which allows partipicants to define, issue and transfer digitial assets on a multi-asset shared ledger. Please refer to the [White Paper](https://github.com/Bytom/wiki/blob/master/White-Paper/%E6%AF%94%E5%8E%9F%E9%93%BE%E6%8A%80%E6%9C%AF%E7%99%BD%E7%9A%AE%E4%B9%A6-%E8%8B%B1%E6%96%87%E7%89%88.md) for more details.
  32
  33 In the current state `bytom` is able to:
  34
  35 - Issue assets
  36 - Manage account as well as asset
  37 - Spend assets
  38
  39 ## Build from source
  40
  41 ### Requirements
  42
  43 - [Go](https://golang.org/doc/install) version 1.8 or higher, with `$GOPATH` set to your preferred directory
  44
  45 ### Installation
  46
  47 Ensure Go with the supported version is installed properly:
  48
  49 ```bash
  50 $ go version
  51 $ go env GOROOT GOPATH
  52 ```
  53
  54 #### Get the source code
  55
  56 ``` bash
  57 $ git clone https://github.com/Bytom/bytom $GOPATH/src/github.com/bytom
  58 ```
  59
  60 #### Build
  61
  62 - Bytomd
  63
  64 ``` bash
  65 $ cd $GOPATH/src/github.com/bytom
  66 $ make install
  67 $ make bytomd
  68 ```
  69
  70 - Bytomcli
  71
  72 ```go
  73 $ cd $GOPATH/src/github.com/bytom/cmd/bytomcli
  74 $ make bytomcli
  75 ```
  76
  77 ## Example
  78
  79 Currently, bytom is still in active development and a ton of work needs to be done, but we also provide the following content for these eager to do something with `bytom`.
  80
  81 ### Create and launch a single node
  82
  83 When successfully building the project, the `bytom` and `bytomcli` binary should be present in `cmd/bytomd` and `cmd/bytomcli` directory, respectively. The next step is to initialize the node:
  84
  85 ```bash
  86 $ cd ./cmd/bytomd
  87 $ ./bytomd init
  88 ```
  89
  90 After that, you'll see `.bytom` generated in current directory, then launch the single node:
  91
  92 ``` bash
  93 $ ./bytomd node --wallet.enable
  94 ```
  95
  96 Given the `bytom` node is running, the general workflow is as follows:
  97
  98 - create an account
  99 - create an asset
 100 - create/sign/submit a transaction to transfer an asset
 101 - query the assets on-chain
 102
 103
 104 #### Create an account
 105
 106 Create an account named `alice`:
 107
 108 ```bash
 109 $ ./bytomcli create-account alice
 110 xprv:<alice_account_private_key>
 111 responses:<create-account-responses>
 112 account id:<alice_account_id>
 113 ```
 114
 115 Check out the new created account:
 116
 117 ```bash
 118 $ ./bytomcli list-accounts
 119 ```
 120
 121 #### Create an asset
 122
 123 Create an asset named `gold`:
 124
 125 ```bash
 126 $ ./bytomcli create-asset gold
 127 xprv:<gold_asset_private_key>
 128 xpub:<gold_asset_public_key>
 129 responses:<create-asset-responses>
 130 asset id:<gold_asset_id>
 131 ```
 132
 133 Check out the new created asset:
 134
 135 ```bash
 136 $ ./bytomcli list-assets
 137 ```
 138
 139 #### Asset issuance test
 140
 141 Since the account `alice` and the asset `gold` are ready, we need to create another account `bob`, which is also neccessary for the following Expenditure test:
 142
 143 ```bash
 144 $ ./bytomcli create-account bob
 145 ```
 146
 147 Firstly, Alice issue `<issue_amount>`, e.g., 10000, `gold`:
 148
 149 ```bash
 150 $ ./bytomcli sub-create-issue-tx <alice_account_id> <bob_account_id> <gold_asset_id> <gold_asset_private_key> <issue_amount>
 151 ```
 152
 153 When the transaction above is mined, query the balances:
 154
 155 ```bash
 156 # Alice should have 10000 gold now
 157 $ ./bytomcli list-balances
 158 ```
 159
 160 #### Expenditure test
 161
 162 - Alice -> Bob
 163
 164 Alice pays Bob `<payment_amount>`, e.g., 1000, `gold`:
 165
 166 ```bash
 167 $ ./bytomcli sub-spend-account-tx <alice_account_id> <bob_account_id> <gold_asset_id> <alice_private_key> <payment_amount>
 168 # In our case, after Alice pays Bob 1000 gold, the amount of Alice's gold should be 9000, Bob's balances should be 1000
 169 $ ./bytomcli list-balances
 170 ```
 171
 172 - Bob -> Alice
 173
 174 Bob pays Alice `<payment_amount>`, e.g., 500, `gold`:
 175
 176 ```bash
 177 $ ./bytomcli sub-spend-account-tx <bob_account_id> <alice_account_id> <gold_asset_id> <bob_private_key> <payment_amount>
 178 # In our case, after Bob pays Alice 500 gold, the amount of Alice's gold should be 9500, Bob's balances should be 500
 179 $ ./bytomcli list-balances
 180 ```
 181
 182 ### Set up a wallet and manage the key
 183
 184 If you have started a bytom node, then you can create an account via `create-key password`, which will generate a `keystore` directory containing the keys under the project directory.
 185
 186 ```bash
 187 $ ./bytomcli create-key account_name password   # Create an account named account_name using password
 188 $ ./bytomcli delete-key password pubkey         # Delete account pubkey
 189 $ ./bytomcli reset-password oldpassword newpassword pubkey  # Update password
 190 ```
 191
 192 ### Multiple node
 193
 194 Get the submodule depenency for the two-node test:
 195
 196 ```bash
 197 $ git submodule update --init --recursive
 198 ```
 199
 200 Create the first node `bytomd0` and second node `bytomd1`:
 201
 202 ```bash
 203 $ cd cmd/bytomd/2node-test
 204 $ ./test.sh bytomd0  # Start the first node
 205 $ ./test.sh bytomd1  # Start the second node
 206 ```
 207
 208 Then we have two nodes:
 209
 210 ```bash
 211 $ ./bytomcli net-info
 212 net-info:map[listening:true listeners:[Listener(@192.168.199.43:3332)] peers:[map[node_info:map[listen_addr:192.168.199.43:3333 version:0.1.2 other:[wire_version=0.6.2 p2p_version=0.5.0] pub_key:D6B76D1B4E9D7E4D81BA5FAAE9359302446488495A29D7E70AF84CDFEA186D66 moniker:anonymous network:bytom remote_addr:127.0.0.1:51036] is_outbound:false connection_status:map[RecvMonitor:map[Start:2017-10-30T13:45:47.18+08:00 Bytes:425130 AvgRate:27010 Progress:0 Active:true Idle:1.04e+09 Samples:42 InstRate:4591 CurRate:3540 PeakRate:114908 BytesRem:0 TimeRem:0 Duration:1.574e+10] Channels:[map[RecentlySent:5332 ID:64 SendQueueCapacity:100 SendQueueSize:0 Priority:5]] SendMonitor:map[Active:true Idle:1.24e+09 Bytes:16240 Samples:41 CurRate:125 AvgRate:1032 Progress:0 Start:2017-10-30T13:45:47.18+08:00 Duration:1.574e+10 InstRate:147 PeakRate:4375 BytesRem:0 TimeRem:0]]]]]
 213 ```
 214
 215 ## Running Bytom in Docker
 216
 217 Ensure your [Docker](https://www.docker.com/) version is 17.05 or higher.
 218
 219 ```bash
 220 $ docker build -t bytom .
 221 ```
 222
 223 ## Contributing
 224
 225 Thank you for considering to help out with the source code! Any contributions are highly appreciated, and we are grateful for even the smallest of fixes!
 226
 227 If you run into an issue, feel free to [file one](https://github.com/Bytom/bytom/issues/) in this repository. We are glad to help!
 228
 229 ## License
 230
 231 [AGPL v3](./LICENSE)