第十六篇墨客区块链(MOAC BlockChain) Chain3 JavaScript API

本文翻译自：https://github.com/MOACChain/moac-core/wiki/Chain3

墨客区块链的Chain3 JavaScript API，兼容以太坊web3.js API，用户可以很方便地将DAPP移植到墨客区块链。

为了让DAPP在墨客网络上运行起来，用户需要使用chain3.js库提供的chain3对象。它通过rpc调用与一个本地vnode节点进行通讯。也就是说，chain3.js作为开放的rpc层，是与墨客vnode节点协同工作的。

chain3包含墨客对象-chain3.mc（用于与墨客区块链vnode间通讯）和account.js（用于交易签名）。

使用回调

chain3 JavaScript API设计为跟一个本地rpc节点协同工作，默认使用同步HTTP请求。

如果想发出异步HTTP请求，可以采用错误优先（error first）回调方式，把一个可选回调函数作为最后一个参数传进去：

chain3.mc.getBlock(48, function(error, result){
    if(!error)
        //If no error occurred, return result
        console.log(result)
    else       
        //If an error occurred, handle it (throw,  etc)
        console.error(error);
})

批量请求

批量请求的处理：

var batch = chain3.createBatch();
batch.add(chain3.mc.getBalance.request('0x0000000000000000000000000000000000000000', 'latest', callback));
batch.add(chain3.mc.contract(abi).at(address).balance.request(address, callback2));
batch.execute();

大数（Big Number）的处理

javaScript本质上对大数对象的处理不在行，比如下面的例子：

"101010100324325345346456456456456456456"
// "101010100324325345346456456456456456456"
101010100324325345346456456456456456456
// 1.0101010032432535e+38

因此，chain3.js会自动加载BigNumber.js库来处理大数和进行完美计算。

下面的例子中，chain3.mc.getBalance()方法获取地址余额，该方法返回一个Big Number对象；此时，需要调用toString()，把它转换成数字字符串。

var balance = new BigNumber('123456786979284780000000000');
// or var balance = chain3.mc.getBalance(someAddress);

balance.plus(21).toString(10); // toString(10) converts it to a number string
// "123456786979284780000000021"

下面的例子中，因为是超过20个浮点数位的大数，BigNumber.js仍然无法正确处理；因此推荐以sha为单位存储余额，仅在向用户呈现时再转换成其他单位。chain3.js自身总是以sha为单位返回和调取余额。

var balance = new BigNumber('13124.234435346456466666457455567456');

balance.plus(21).toString(10);  // toString(10) converts it to a number string, but can only show max 20 floating points 
// "13124.23443534645646666646" // you number would be cut after the 20 floating point

chain3.providers

chain3.isConnected

chain3.setProvider

chain3.currentProvider

chain3.version.network

chain3.providers

为了在node.js中使用chain3.js，可以在项目目录中运行：

d:\myProject>npm install chain3

然后在源代码中使用require导入它；一个chain3实例代表与节点的一个连接。

Example

var Chain3 = require('chain3');   
// create an instance of chain3 using the HTTP provider.
var chain3 = new Chain3(new Chain3.providers.HttpProvider("http://localhost:8545"));

或者，通过检查chain3是否是undefined，来确保代码的可靠运行。

如果chain3被定义了，则使用已经可用的实例；否则，通过连接至自定义节点创建一个实例。

if (typeof chain3 !== 'undefined') {
    chain3 = new Chain3(chain3.currentProvider);
} else {
    // set the provider you want from Chain3.providers
    chain3 = new Chain3(new Chain3.providers.HttpProvider("http://localhost:8545"));
}

直接查看chain3对象：

var Chain3 = require('chain3');
var chain3 = new Chain3();
console.log(chain3); // {mc: .., net: ...} // it's here!

chain3.isConnected

chain3.isConnected()

查询是否已经与Vnode节点连接。

Returns

boolean：true表示已连接，false表示没有连接。

Example

if(!chain3.isConnected()) {  
    // show some dialog to ask the user to start a node
} else { 
    // start chain3 filters, calls, etc  
}

chain3.setProvider

chain3.setProvider(provider)

在创建chain3实例之后，可以使用setProvider方法改变provider，它有一个实参，即新provider实例。

Returns

undefined。

Example

chain3.setProvider(new chain3.providers.HttpProvider('http://localhost:8545')); // 8545 for go/moac

chain3.currentProvider

chain3.currentProvider

chain3.currentProvider属性被自动分配给当前的provider实例。

Returns

object：当前provider实例或者空（null）。

Example

// Check if moac etc. already set a provider
if(!chain3.currentProvider)
    chain3.setProvider(new chain3.providers.HttpProvider("http://localhost:8545"));

chian3.reset

chain3.reset(keepIsSyncing)

重置chain3的状态。

Returns

undefined。

Example

chain3.reset();

chain3.version

chain3的版本信息

chain3.version.api

chain3.version.api
// or async
chain3.version.getApi(callback(error, result){ ... })

Returns

string：chain3.js的api版本。

Example

var version = chain3.version.api;
console.log(version); // "0.2.0"

chain3.version.node

chain3.version.node
// or async
chain3.version.getClient(callback(error, result){ ... })

Returns

string：Vnode节点的版本。

Example

var version = chain3.version.node;
console.log(version); // "Moac/v1.0.2-stable-632a21f0/windows-amd64/go1.9.5"

chain3.version.network

chain3.version.network
// or async
chain3.version.getNetwork(callback(error, result){ ... })

Returns

string：网络协议版本。

Example

var version = chain3.version.network;
console.log(version); // mainnet:99,testnet:101

chain3.version.moac

chain3.version.moac
// or async
chain3.version.getMoac(callback(error, result){ ... })

Returns

string：墨客协议版本。

Example

var version = chain3.version.moac;
console.log(version); // 0x3f

chain3.sha3

chain3.sha3(string [, callback])

Parameters

String：使用SHA3算法将该字符串进行hash；
Function：异步HTTP请求。

Returns

string：通过SHA3算法得到的hash值。

Example

var str = chain3.sha3("Some ASCII string to be hashed in MOAC");
console.log(str); // "0xbfa24877cd68e6734710402a2af3e29cf18bd6d2f304aa528ffa3a32fa7652d2"

chain3.toHex

chain3.toHex(mixed)

将值的类型转换为十六进制。

Parameters

string/Number/Object/Array/BigNumber：如果是对象或者数组，将首先用JSON.stringify进行转换，再转换为Hex。

Returns

string：mixed的Hex形式字符串。

Example

var str = chain3.toHex("moac network");
console.log(str);                           // '0x6d6f6163206e6574776f726b'

console.log(chain3.toHex({moac: 'test'}));  // '0x7b226d6f6163223a2274657374227d'

chain3.toAscii

chain3.toAscii(hexString)

将一个Hex字符串转换为ASCII形式。

Returns

string：ASCII形式字符串。

Example

var str = chain3.toAscii("0x0x6d6f6163206e6574776f726b");
console.log(str); // "moac network"

chain3.fromAscii

chain3.fromAscii(string)

将一个ASCII字符串转换为Hex形式。

Returns

string：十六进制字符串。

Example

var str = chain3.fromAscii('moac network');
console.log(str); // "0x6d6f6163206e6574776f726b"