README.md

   1 # Bytom Node.js SDK
   2
   3 ## Terminology
   4
   5 ### [Keys](https://bytom.github.io/bytom-node-sdk/global.html#Key__anchor)
   6
   7 Cryptographic keys are the primary authorization mechanism on a blockchain.
   8
   9 To create accounts or assets, xpub of keys are required. With this sdk, we can
  10 `create/delete/listAll/resetPassword/checkPassword` the key. Please check the
  11 [API doc](https://bytom.github.io/bytom-node-sdk/module-KeysApi.html) if you want
  12 to operate with keys.
  13
  14 ### [Account](https://bytom.github.io/bytom-node-sdk/global.html#Account__anchor)
  15
  16 An account is an object in Bytom that tracks ownership of assets on a blockchain.
  17 It's defined under one Bytom node created with one or serveral keys.
  18
  19 [Related API](https://bytom.github.io/bytom-node-sdk/module-AccountsApi.html)
  20
  21 ### [Asset](https://bytom.github.io/bytom-node-sdk/global.html#Asset__anchor)
  22
  23 An asset is a type of value that can be issued on a blockchain. All units of
  24 a given asset are fungible. Units of an asset can be transacted directly
  25 between parties without the involvement of the issuer.
  26
  27 [Related API](https://bytom.github.io/bytom-node-sdk/module-AssetsApi.html)
  28
  29 ### [Transaction](https://bytom.github.io/bytom-node-sdk/global.html#Transaction__anchor)
  30
  31 Blockchain is chain of blocks, while block consists of numbers of transactions.
  32
  33 [Related API](https://bytom.github.io/bytom-node-sdk/module-TransactionsApi.html)
  34
  35 ### [Unspent Output(UTXO)](https://bytom.github.io/bytom-node-sdk/global.html#UnspentOutput__anchor)
  36
  37 Bytom is UTXO based blockchain. One transaction spend some UTXOs, and produces new UTXOs.
  38
  39 [Related API](https://bytom.github.io/bytom-node-sdk/module-UnspentOutputsApi.html)
  40
  41 ### [Balance](https://bytom.github.io/bytom-node-sdk/global.html#Balance__anchor)
  42
  43 Any balance on the blockchain is simply a summation of UTXOs. In one bytomd, balance means
  44 summation of UTXOs of one account.
  45
  46 [Related API](https://bytom.github.io/bytom-node-sdk/module-BalancesApi.html)
  47
  48 ### [Block](https://bytom.github.io/bytom-node-sdk/global.html#Block__anchor)
  49
  50      A block is a container data structure that aggregates transactions for inclusion in the public ledger, the blockchain.
  51  It is made of a header, containing metadata, followed by a long list of transactions that make up the bulk of its size.
  52   Each block references to the previous block, and all the blocks are linked from the back to the front to grow a blockchain.
  53
  54 [Related API](https://bytom.github.io/bytom-node-sdk/module-BlockApi.html)
  55
  56 ### [Config](https://bytom.github.io/bytom-node-sdk/global.html#Config__anchor)
  57
  58 Config contain the network information that you wanted to know.
  59
  60 [Related API](https://bytom.github.io/bytom-node-sdk/module-ConfigApi.html)
  61
  62 ## Usage
  63
  64 ### In your code
  65
  66 ```javascript
  67 const bytom = require('bytom-sdk')
  68 const url = 'http://localhost:9888'
  69
  70 // access token is required when client is not in same origin
  71 // with the request bytom node
  72 const accessToken = ''
  73
  74 const client = new bytom.Client(url, accessToken)
  75 ```
  76
  77 ## Interaction with bytom
  78
  79 We will walk you through the process to issue some assets.
  80
  81 ### Step 1: create a key
  82
  83 ```javascript
  84 const keyPromise = client.keys.create({
  85           alias:'key',
  86           password: 'password'
  87          })
  88 ```
  89
  90 It will create a key whose alias is 'alias' while password is 'password'.
  91
  92 ### Step 2: create a account
  93
  94 ```javascript
  95 const accountPromise = keyPromise.then(key => {
  96  client.accounts.create({
  97      alias: 'account',
  98      root_xpubs: [key.xpub],
  99      quorum: 1
 100  })
 101 })
 102 ```
 103
 104 ### Step 3: create account address
 105
 106 ```javascript
 107 const addressPromise = accountPromise.then(account => {
 108   return client.accounts.createReceiver({
 109     account_alias: account.alias
 110   })
 111 })
 112 ```
 113
 114 ### Step 4: create asset
 115
 116 ```javascript
 117 const definition = {
 118   name: "GOLD",
 119   symbol: "GOLD",
 120   decimals: 8,
 121   description: {}
 122 }
 123
 124 const assetPromise = keyPromise.then(key => {
 125   return client.assets.create(
 126     {
 127      alias: 'asset',
 128      definition,
 129      root_xpubs: [key.xpub],
 130      quorum: 1
 131     })
 132 })
 133 ```
 134
 135 ### Step 5: issue asset
 136
 137 #### First, build the transaction
 138
 139 ```javascript
 140 const buildPromise = Promise.all([
 141   accountPromise,
 142   addressPromise,
 143   assetPromise]
 144   ).then(([account, address, asset]) => {
 145   const issueAction = {
 146     amount: 100000000,
 147     asset_alias: asset.alias,
 148   }
 149
 150   const gasAction = {
 151     account_alias: account.alias,
 152     asset_alias: 'BTM',
 153     amount: 50000000
 154   }
 155
 156   const controlAction = {
 157     amount: 100000000,
 158     asset_alias: asset.alias,
 159     address: address.address
 160   }
 161
 162   return client.transactions.build(builder => {
 163       builder.issue(issueAction)
 164       builder.spendFromAccount(gasAction)
 165       builder.controlWithAddress(controlAction)
 166   })
 167 })
 168
 169 ```
 170
 171 #### Second, sign the transaction
 172
 173 ```javascript
 174 const signPromise = buildPromise.then(transactionTemplate => {
 175   return client.transactions.sign({
 176     transaction: transactionTemplate,
 177     password: 'password'
 178   })
 179 })
 180 ```
 181
 182 #### Finally, submit the signed transaction to the bytom network
 183
 184 ```javascript
 185 signPromise.then(signed => {
 186   return client.transactions.submit(signed.transaction.raw_transaction)
 187 })
 188 ```