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 $ cd ./cmd/bytomd
  68 $ go build
  69 ```
  70
  71 - Bytomcli
  72
  73 ```go
  74 $ cd $GOPATH/src/github.com/bytom/cmd/bytomcli
  75 $ go build
  76 ```
  77
  78 ## Example
  79
  80 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`.
  81
  82 ### Create and launch a single node
  83
  84 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:
  85
  86 ```bash
  87 $ cd ./cmd/bytomd
  88 $ ./bytomd init
  89 ```
  90
  91 After that, you'll see `.bytom` generated in current directory, then launch the single node:
  92
  93 ``` bash
  94 $ ./bytomd node --wallet.enable
  95 ```
  96
  97 Given the `bytom` node is running, the general workflow is as follows:
  98
  99 - create an account
 100 - create an asset
 101 - create/sign/submit a transaction to transfer an asset
 102 - query the assets on-chain
 103
 104
 105 #### Create an account
 106
 107 Create an account named `alice`:
 108
 109 ```bash
 110 $ ./bytomcli create-account alice
 111 xprv:<alice_account_private_key>
 112 responses:<create-account-responses>
 113 account id:<alice_account_id>
 114 ```
 115
 116 Check out the new created account:
 117
 118 ```bash
 119 $ ./bytomcli list-accounts
 120 ```
 121
 122 #### Create an asset
 123
 124 Create an asset named `gold`:
 125
 126 ```bash
 127 $ ./bytomcli create-asset gold
 128 xprv:<gold_asset_private_key>
 129 xpub:<gold_asset_public_key>
 130 responses:<create-asset-responses>
 131 asset id:<gold_asset_id>
 132 ```
 133
 134 Check out the new created asset:
 135
 136 ```bash
 137 $ ./bytomcli list-assets
 138 ```
 139
 140 #### Asset issuance test
 141
 142 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:
 143
 144 ```bash
 145 $ ./bytomcli create-account bob
 146 ```
 147
 148 Firstly, Alice issue `<issue_amount>`, e.g., 10000, `gold`:
 149
 150 ```bash
 151 $ ./bytomcli sub-create-issue-tx <alice_account_id> <bob_account_id> <gold_asset_id> <gold_asset_private_key> <issue_amount>
 152 ```
 153
 154 When the transaction above is mined, query the balances:
 155
 156 ```bash
 157 # Alice should have 10000 gold now
 158 $ ./bytomcli list-balances
 159 ```
 160
 161 #### Expenditure test
 162
 163 - Alice -> Bob
 164
 165 Alice pays Bob `<payment_amount>`, e.g., 1000, `gold`:
 166
 167 ```bash
 168 $ ./bytomcli sub-spend-account-tx <alice_account_id> <bob_account_id> <gold_asset_id> <alice_private_key> <payment_amount>
 169 # In our case, after Alice pays Bob 1000 gold, the amount of Alice's gold should be 9000, Bob's balances should be 1000
 170 $ ./bytomcli list-balances
 171 ```
 172
 173 - Bob -> Alice
 174
 175 Bob pays Alice `<payment_amount>`, e.g., 500, `gold`:
 176
 177 ```bash
 178 $ ./bytomcli sub-spend-account-tx <bob_account_id> <alice_account_id> <gold_asset_id> <bob_private_key> <payment_amount>
 179 # In our case, after Bob pays Alice 500 gold, the amount of Alice's gold should be 9500, Bob's balances should be 500
 180 $ ./bytomcli list-balances
 181 ```
 182
 183 ### Set up a wallet and manage the key
 184
 185 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.
 186
 187 ```bash
 188 $ ./bytomcli create-key account_name password   # Create an account named account_name using password
 189 $ ./bytomcli delete-key password pubkey         # Delete account pubkey
 190 $ ./bytomcli reset-password oldpassword newpassword pubkey  # Update password
 191 ```
 192
 193 ### Multiple node
 194
 195 Get the submodule depenency for the two-node test:
 196
 197 ```bash
 198 $ git submodule update --init --recursive
 199 ```
 200
 201 Create the first node `bytomd0` and second node `bytomd1`:
 202
 203 ```bash
 204 $ cd cmd/bytomd/2node-test
 205 $ ./test.sh bytomd0  # Start the first node
 206 $ ./test.sh bytomd1  # Start the second node
 207 ```
 208
 209 Then we have two nodes:
 210
 211 ```bash
 212 $ ./bytomcli net-info
 213 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]]]]]
 214 ```
 215
 216 ## Running Bytom in Docker
 217
 218 Ensure your [Docker](https://www.docker.com/) version is 17.05 or higher.
 219
 220 ```bash
 221 $ docker build -t bytom .
 222 ```
 223
 224 ## Contributing
 225
 226 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!
 227
 228 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!
 229
 230 ## License
 231
 232 [AGPL v3](./LICENSE)