README.md

   1 # Bytom Node.js SDK
   2
   3 ## Terminology
   4
   5 ### [Keys](https://bytom.github.io/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/list/resetPassword` the key. Please check the
  11 [API doc](https://bytom.github.io/node-sdk/module-KeysApi.html) if you want
  12 to operate with keys.
  13
  14 ### [Account](https://bytom.github.io/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/node-sdk/module-AccountsApi.html)
  20
  21 ### [Asset](https://bytom.github.io/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/node-sdk/module-AssetsApi.html)
  28
  29 ### [Transaction](https://bytom.github.io/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/node-sdk/module-TransactionsApi.html)
  34
  35 ### [Unspent Output(UTXO)](https://bytom.github.io/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/node-sdk/module-UnspentOutputsApi.html)
  40
  41 ### [Balance](https://bytom.github.io/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/node-sdk/module-BalancesApi.html)
  47
  48 ## Usage
  49
  50 ### In your code
  51
  52 ```javascript
  53 const bytom = require('bytom-sdk')
  54 const url = 'http://localhost:9888'
  55
  56 // access token is required when client is not in same origin
  57 // with the request bytom node
  58 const accessToken = ''
  59
  60 const client = new bytom.Client(url, accessToken)
  61 ```
  62
  63 ## Interaction with bytom
  64
  65 We will walk you through the process to issue some assets.
  66
  67 ### Step 1: create a key
  68
  69 ```javascript
  70 const keyPromise = client.keys.create('alias', 'password')
  71 ```
  72
  73 It will create a key whose alias is 'alias' while password is 'password'.
  74
  75 ### Step 2: create a account
  76
  77 ```javascript
  78 const accountPromise = keyPromise.then(key => {
  79  client.accounts.create([key.xpub], 1, 'account')
  80 })
  81 ```
  82
  83 ### Step 3: create account address
  84
  85 ```javascript
  86 const addressPromise = accountPromise.then(account => {
  87   return client.accounts.createReceiverById(account.id)
  88 })
  89 ```
  90
  91 ### Step 4: create asset
  92
  93 ```javascript
  94 const definition = {
  95   name: "GOLD",
  96   symobol: "GOLD",
  97   decimals: 8,
  98   description: {}
  99 }
 100 const assetPromise = keyPromise.then(key => {
 101   return client.assets.create([key.xpub], 1, 'asset', definition)
 102 })
 103 ```
 104
 105 ### Step 5: issue asset
 106
 107 #### First, build the transaction
 108
 109 ```javascript
 110 const buildPromise = Promise.all([
 111   accountPromise,
 112   addressPromise,
 113   assetPromise]
 114   ).then(([account, address, asset]) => {
 115   const issueAction = {
 116     amount: 10000000000,
 117     asset_alias: asset.alias,
 118     type: 'issue'
 119   }
 120
 121   const gasAction = {
 122     type: 'spend_account',
 123     account_alias: account.alias,
 124     asset_alias: 'BTM',
 125     amount: 50000000
 126   }
 127
 128   const controlAction = {
 129     type: 'control_address',
 130     amount: 10000000000,
 131     asset_alias: asset.alias,
 132     address: address.address
 133   }
 134
 135   return client.transactions.build(null,
 136   [issueAction, gasAction, controlAction])
 137 })
 138
 139 ```
 140
 141 #### Second, sign the transaction
 142
 143 ```javascript
 144 const signPromise = buildPromise.then(transactionTemplate => {
 145   return client.transactions.sign(transactionTemplate, 'password')
 146 })
 147 ```
 148
 149 #### Finally, submit the signed transaction to the bytom network
 150
 151 ```javascript
 152 signPromise.then(signed => {
 153   return client.transactions.submit(signed.transaction.raw_transaction)
 154 })
 155 ```