README.md

   1 # Bytom Node.js SDK
   2
   3 ## Terminology
   4
   5 ### Keys
   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 api doc if you want
  11 to operate with keys.
  12
  13 ### Account
  14
  15 An account is an object in Bytom that tracks ownership of assets on a blockchain.
  16 It's defined under one Bytom node created with one or serveral keys.
  17
  18 ### Asset
  19
  20 An asset is a type of value that can be issued on a blockchain. All units of
  21 a given asset are fungible. Units of an asset can be transacted directly
  22 between parties without the involvement of the issuer.
  23
  24 ### Transaction
  25
  26 Blockchain is chain of blocks, while block consists of numbers of transactions.
  27
  28 ### Unspent Output(UTXO)
  29
  30 Bytom is UTXO based blockchain. One transaction spend some UTXOs, and produces new UTXOs.
  31
  32 ### Balance
  33
  34 Any balance on the blockchain is simply a summation of UTXOs. In one bytomd, balance means
  35 summation of UTXOs of one account.
  36
  37 ## Usage
  38
  39 ### In your code
  40
  41 ```
  42 const bytom = require('bytom-sdk')
  43 const url = 'http://localhost:9888'
  44
  45 const client = new bytom.Client(url)
  46 ```
  47
  48 ## Interaction with bytom
  49
  50 We will walk you through the process to issue some assets.
  51
  52 ### Step 1: create a key
  53
  54 ```javascript
  55 const keyPromise = client.keys.create('alias', 'password')
  56 ```
  57
  58 It will create a key whose alias is 'alias' while password is 'password'.
  59
  60 ### Step 2: create a account
  61
  62 ```javascript
  63 const accountPromise = keyPromise.then(key => client.accounts.create([key.xpub], 1, 'account'))
  64 ```
  65
  66 ### Step 3: create account address
  67
  68 const addressPromise = accountPromise.then(account => {
  69   return client.accounts.createReceiverById(account.id)
  70 })
  71
  72 ### Step 4: create asset
  73
  74 ```javascript
  75 const definition = {name: "GOLD", symobol: "GOLD", decimals: 8, description: {}}
  76 const assetPromise = keyPromise.then(key => {
  77   return client.assets.create([key.xpub], 1, 'asset', definition)
  78 })
  79 ```
  80
  81 ### Step 5: issue asset
  82
  83 #### First, build the transaction
  84
  85 ```javascript
  86 const buildPromise = Promise.all([accountPromise, addressPromise, assetPromise]).then(([account, address, asset]) => {
  87   const issueAction = {
  88     amount: 10000000000,
  89     asset_alias: asset.alias,
  90     type: 'issue'
  91   }
  92
  93   const gasAction = {
  94     type: 'spend_account',
  95     account_alias: account.alias,
  96     asset_alias: 'BTM',
  97     amount: 50000000
  98   }
  99
 100   const controlAction = {
 101     type: 'control_address',
 102     amount: 10000000000,
 103     asset_alias: asset.alias,
 104     address: address.address
 105   }
 106
 107   return client.transactions.build(null, [issueAction, gasAction, controlAction])
 108 })
 109
 110 ```
 111
 112 #### Second, sign the transaction
 113
 114 ```javascript
 115 const signPromise = buildPromise.then(transactionTemplate => {
 116   return client.transactions.sign(transactionTemplate, 'password')
 117 })
 118 ```
 119
 120 #### Finally, submit the signed transaction to the bytom network
 121
 122 ```javascript
 123 signPromise.then(signed => {
 124   return client.transactions.submit(signed.transaction.raw_transaction)
 125 })
 126 ```