youchain.you

youchain-you 这个模块可以让开发者使用 YOUChain 并和 YOUChain 上的智能合约进行交互。

const YOUChain = require('youchain');
const YOU = require('youchain-you');

const you = new YOU(YOUChain.givenProvider || 'ws://localhost:8284/ws', options);

Subscribe

请参考 Subscribe 用法说明

Contract

请参考 Contract 用法说明

Personal

请参考 Personal 用法说明

Accounts

请参考 Accounts 用法说明

ABI

请参考 ABI 用法说明

Net

请参考 Net 用法说明

options

youchain 模块为交易确认流程提供多种初始化配置,以下是目前常用的配置属性:

  • defaultAccount
  • defaultBlock
  • defaultGas
  • defaultGasPrice
  • transactionBlockTimeout
  • transactionConfirmationBlocks
  • transactionPollingTimeout
const YOUChain = require('youchain');
const options = {
    defaultAccount: '0x59677fd68ec54e43ad4319d915f81748b5a6ff8b',  // 默认账户
    defaultBlock: 'latest',    // 默认区块
    defaultGas: 1,              // 用于发送请求
    defaultGasPrice: 0,      // 用于发送请求
    transactionBlockTimeout: 50,  // 交易区块超时时间
    transactionConfirmationBlocks: 12,  //交易确认区块数。默认为 12 个区块
    transactionPollingTimeout: 750  // 交易长连接超时时间
}

const youchain = new YOUChain('http://localhost:8283', null, options);

defaultBlock

描述:发出请求的默认区块

返回值:String | Number - defaultBlock 属性值

youchain.defaultBlock 
youchain.you.defaultBlock

defaultAccount

描述:默认账户地址

属性:Null | String - 当前默认账号属性,20 字节

youchain.defaultAccount
youchain.you.defaultAccount

defaultGasPrice

描述:默认 Gas 价格

返回值:Null | String - 当前默认账号属性,20 字节

youchain.defaultGasPrice
youchain.you.defaultGasPrice

defaultGas

描述:本块允许的最大 Gas 用量

返回值:Null | String - 当前默认账号属性,20 字节

youchain.defaultGas
youchain.you.defaultGas

transactionBlockTimeout

描述:交易区块超时时长

返回值:Number - 交易块的超时时间

youchain.transactionBlockTimeout
youchain.you.transactionBlockTimeout

transactionConfirmationBlocks

描述:交易确认区块数量

返回值:Number - 交易确认块的值

youchain.transactionConfirmationBlocks
youchain.you.transactionConfirmationBlocks

transactionPollingTimeout

描述:交易长连接超时时长

返回值:Number - 交易长连接超时时间

youchain.transactionPollingTimeout
youchain.you.transactionPollingTimeout

getGasPrice

描述:获取当前 gasPrice 设置

youchain.you.getGasPrice().then(console.log);
> 10000

setProvider

描述:设置 Provider 参数

youchain.setProvider(myProvider) //设置所有模块的 provider
youchain.you.setProvider(myProvider) // 设置单独模块的 provider

示例:

const YOUChain = require('youchain');
const youchain = new YOUChain('http://localhost:8283');
// 或者
youchain.setProvider(new YOUChain.providers.HttpProvider('http://localhost:8283'));
youchain.setProvider(new YOUChain.providers.WebsocketProvider('ws://localhost:8283'));

providers

描述:获取所有的 providers 类型。

YOUChain.providers;
> {
    HttpProvider: [Function: HttpProvider],
    WebsocketProvider: [Function: WebsocketProvider]
}

示例

const YOUChain = require('youchain');
const youchain = new YOUChain(YOUChain.givenProvider || 'ws://localhost:8284/ws');
// 或者
const youchain = new YOUChain(YOUChain.givenProvider || new YOUChain.providers.WebsocketProvider('ws://localhost:8284/ws'));

givenProvider

使用与 YOUChain 兼容的浏览器,浏览器环境会默认设置一个 provider 否则值为 null.

YOUChain.givenProvider
youchain.you.givenProvider

currentProvider

描述:获取当前 provider 的值,否则为 null。

youchain.currentProvider
youchain.you.currentProvider

BatchRequest

描述:可以执行多个请求。

初始化实例:

new youchain.BatchRequest()
或
new youchain.you.BatchRequest()

添加请求:

batch.add(youchain.you.getBalance.request(address, tag, callback))
batch.add(contractInstance.methods.myMethod.call.request(options, callback2))

示例:

// 初始化合约实例
const contract = new youchain.you.Contract(abi, address);

// 构建批量请求
const batch = new youchain.you.BatchRequest();
batch.add(youchain.you.getBalance.request(
    '0xd7bad0135F8c6bE4C77D8Bc9bE60a51F9b9Ec77B',
    'latest',
    (error, balance) => {
        console.log('balance: ', balance);
    }
));
batch.add(myContract.methods.greet().call.request(
    {
        from: '0xd7bad0135F8c6bE4C77D8Bc9bE60a51F9b9Ec77B'
    },
    (error, result) => {
        console.log('method return:', result);
    }
));

// 执行请求
batch.execute();

getProtocolVersion

描述;获取节点的协议 (protocol) 版本代码

返回值:Promise - 当前 protocol 版本

youchain.you.getProtocolVersion().then(console.log);
> "0x8"

getCoinbase

描述:获取 coinbase 地址,即挖矿奖励的地址

返回值:Promise - 节点挖矿奖励地址

youchain.you.getCoinbase().then(console.log);
> "0x59677fd68ec54e43ad4319d915f81748b5a6ff8a"

getNetworkId

描述:获取当前节点的网络编号,

返回值:Promise - 网络编号

youchain.you.getNetworkId().then(console.log);
> 2

getBlockNumber

描述:获取当前区块号

返回值:Promise - 最新区块的编号

youchain.you.getBlockNumber().then(console.log);
> 807239

getBalance

描述:获取给定区块的账户余额

参数值:

1.String - 获取余额的地址 2.Number | String:可选参数,区块高度 3.Callback:可选参数,回调函数

返回值:Promise - 当前地址的余额,单位为 lu

youchain.you.getBalance("0x0B9d85bB0E36379ee32F02912DCC3dfB01f36235").then(console.log);
> 0

getStorageAt

描述:获取给定区块位置的存储值

参数值:

  1. String - 获取存储的地址
  2. Number - 在存储里的索引位置
  3. Number | String:可选参数,默认值为 default block
  4. Callback:可选参数,回调函数

返回值:Promise - 在给定位置的存储值

youchain.you.getStorageAt("0x0B9d85bB0E36379ee32F02912DCC3dfB01f36235", 0).then(console.log);
> "0x0000000000000000000000000000000000000000000000000000000000000000"
  ### <strong>getCode</strong>

描述:获取指定区块的数据

参数值:

  1. String - 获取 code 的地址
  2. Number | String:可选参数,默认值为 default block
  3. Callback:可选参数,回调函数

返回值:Promise - 在给定位置的数据

youchain.you.getCode("0x0B9d85bB0E36379ee32F02912DCC3dfB01f36235").then(console.log);
> "0x"

getBlock

描述:根据区块号或区块哈希获取区块的信息

参数值:

类型 备注
String 或 Number 区块高度或 "latest", "pending"
Boolean 可选值
Callback 回调函数

返回值:Promise

名称 类型 备注
consensus Bytes 共识有关数据
number Number 区块高度。挂起区块,值为 null
hash String, 32 Bytes 区块哈希值。挂起区块,值为 null
parentHash String, 32 Bytes 父区块的哈希值
logsBloom String, 256 Bytes 区块日志的 bloom 过滤器。挂起区块,值为 null
transactionsRoot String, 32 Bytes 区块交易树的根节点
stateRoot String, 32 Bytes 区块最终状态树的根节点
receiptsRoot 32 Bytes String 交易票据树的根节点,当交易执行后会在这个索引树保存状态。
miner String 挖矿奖励地址
mixHash String UCon MixDigest 哈希值
extraData String 区块中 "extra data" 字段
size Number 区块大小
gasLimit Number 预估值,区块允许的最大 gas 费
gasUsed Number 区块中交易所用的 gas 费
gasRewards Bytes 本块中所有交易的总费用
timestamp Number 块时间戳
transactions Array 交易对象数组或 32 Bytes 交易哈希值
slashData Bytes 罚款信息
bltRoot Bytes BloomBits 树根,与chtRoot在相同块高出现
certificate Bytes 对 chtRoot 和 bltRoot 的附加投票数据
chtRoot Bytes 权威哈希树根,只在特定块高上出现(主网将会是 i*32768 )
valRoot Bytes 验证者集合树根节点
signature Bytes 区块验证签名
validator Bytes 区块提议者对区块的签名
youchain.you.getBlock(1000, (error, block) => {
    console.log('\n====== getBlock ======');
    console.log('getBlock: ', block);
});

> {
      bltRoot: '0x',
      certificate: '0x',
      chtRoot: '0x',
      consensus: '0x',
      extraData: '0x',
      gasLimit: 1616750465,
      gasRewards: '0x0',
      gasUsed: 0,
      hash: '0x45ea1abef0d3075816739269237c814dff0152eb120378a996d098e076a3249a',
      logsBloom: '0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000',
      miner: '0x59677fD68ec54e43aD4319D915f81748B5a6Ff8B',
      mixHash: '0x0000000000000000000000000000000000000000000000000000000000000000',
      number: 1000,
      parentHash: '0x9535fa70bec4404bfc0172e626ef531c7c24f91e873de84036032ed59c615211',
      receiptsRoot: '0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421',
      signature: '0x',
      size: 508,
      slashData: '0x',
      stateRoot: '0xa81b879108935651553639d5e43f014edb6860d5f210e39fec6be1554a20cda5',
      timestamp: 1579170717,
      transactions: [],
      transactionsRoot: '0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421',
      valRoot: '0x582a421de7e96cfef03df3a6df3799556823d0d1f8e6f4acf8663bead8a43c37',
      validator: '0x'
}

getBlockTransactionCount

描述:获取区块的交易数

参数值:

  1. String | Number 区块高度或哈希值
  2. Callback 回调函数

返回值:Promise - 区块中交易的数量

youchain.you.getBlockTransactionCount(8000).then(console.log);      
> 5

getTransaction

描述:获取交易对象信息

参数值:

  1. String - 交易哈希值
  2. Callback:可选,回调函数

返回值:Promise 返回交易信息

  • hash 32 Bytes - String: 交易的哈希值.
  • nonce - Number: 本次交易之前发送方已经生成的交易数量
  • blockHash 32 Bytes - String: 交易所在的区块哈希。挂起块值为 null。
  • blockNumber - Number: 交易所在的区块高度。挂起块值为 null。
  • transactionIndex - Number: 交易在区块中的索引位置。挂起块值为 null。
  • from - String: 发送交易地址
  • to - String: 接收交易地址. 部署合约时此处值为 null。
  • value - String: 交易转账的值,单位为 lu
  • gasPrice - String: 交易发送者愿意支付的 gas 费用的价格.
  • gas - Number: 该交易的执行时使用gas的上限。
  • input - String: 交易携带的数据信息。
youchain.you.getTransaction("0x4fc5806ed2d56fa03e0024fb94081456889a285e7b930e3b53060bc2918a36bf").then(console.log);

getTransactionFromBlock

描述:获取交易对象信息

参数值:

  1. String,Number - 交易哈希值或区块高度
  2. Number - 交易所在的索引位置
  3. Callback:可选参数,回调函数

返回值:Promise - 返回交易信息

  • hash 32 Bytes - String: 交易的哈希值
  • nonce - Number: 本次交易之前发送方已经生成的交易数量
  • blockHash 32 Bytes - String: 交易所在的区块哈希。挂起块值为 null
  • blockNumber - Number: 交易所在的区块高度。挂起块值为 null
  • transactionIndex - Number: 交易在区块中的索引位置。挂起块值为 null
  • from - String: 发送交易地址
  • to - String: 接收交易地址. 部署合约时此处值为 null
  • value - String: 交易转账的值,单位为 lu
  • gasPrice - String: 交易发送者愿意支付的 gas 费用的价格
  • gas - Number: 该交易的执行时使用 gas 的上限
  • input - String: 交易携带的数据信息
youchain.you.getTransactionFromBlock("0xb5bb44870ac5ac8950bd32c40421db4f45b9b83f6d5a8022158f787cf900975b", 2).then(console.log);

getTransactionReceipt

描述:获取交易票据

参数值:

  1. String - 交易哈希值
  2. Callback:可选,回调函数

返回值:Promise - 返回交易信息

  • status - String: 交易返回状态,0x1 表示成功
  • blockHash 32 Bytes - String: 交易所在的区块哈希
  • blockNumber - Number: 交易所在的区块高度
  • transactionHash 32 Bytes - String: 交易哈希
  • transactionIndex - Number: 交易在区块
  • from - String: 发送交易方地址
  • to - String: 接收交易方地址。合约创建的交易值为 null
  • contractAddress - String: 合约地址
  • cumulativeGasUsed - Number: 在块中执行所有交易的费用总和
  • gasUsed- Number: 执行特定交易花费的费用总和
  • logs - Array: 交易产生的日志对象数组
youchain.you.getTransactionReceipt("0x6c2c514731d81ca31fa2b094e570b9db6f701098fa2ce2a2e7cf7e1056f90095")
.then(console.log);
> {
    "status": "0x1",
    "transactionHash": "0x6c2c514731d81ca31fa2b094e570b9db6f701098fa2ce2a2e7cf7e1056f90095",
    "transactionIndex": 1,
    "blockHash": "0x69edd2c3d81fa46294c4413b57aecdc1f67ef5cee241fa2114265d7e6d1d3a93",
    "blockNumber": 925496,
    "contractAddress": "0x11f4d0A3c12e86B4b5F39B213F7E19D048276DAe",
    "cumulativeGasUsed": 314159,
    "gasUsed": 30234,
    "logs": [{
    }, ...]
}

getTransactionCount

描述:获取账户的交易数

参数值:

  1. String 获取交易数量的账户地址
  2. Number | String 默认值为 default block
  3. Callback 回调函数

返回值:Promise - 账户的交易数量

youchain.you.getTransactionCount("0x59677fD68ec54e43aD4319D915f81748B5a6Ff8B").then(console.log);
> 166

sendTransaction

描述:在网络中发送交易

参数值:

  1. 发送的交易对象
    • from - String | Number:发送账户的地址
    • to - String:接收消息的地址
    • value - Number | String | BN | BigNumber:交易转账的值
    • gas - 发送该交易时使用 gas 的上限
    • gasPrice - 交易发送者愿意支付的 gas 费用的价格
    • data - 合约调用的 ABI 字节码数据
    • nonce - nonce。可以使用同一个nonce来实现挂起的交易的重写
  2. 回调函数 - Callback

返回值:

  • transactionHash - String:交易哈希值
  • receipt - Object:交易票据
  • confirmation - Number | Object:确认交易数
  • error - Error:发送交易的错误信息
const code = "603d80600c6000396000f3007c01000000000000000000000000000000000000000000000000000000006000350463c6888fa18114602d57005b6007600435028060005260206000f3";
youchain.you.sendTransaction({
    from: '0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe',
    to: '0x11f4d0A3c12e86B4b5F39B213F7E19D048276DAe',
    value: '1000000000000000'
})
.then(function(receipt){
    ...
});

sendSignedTransaction

描述:在网络中发送已签名的交易

参数值:

  1. String 十六进制签名交易的数据
  2. Callback 回调函数

返回值:

  • transactionHash - String:交易哈希值
  • receipt - Object:交易票据
  • confirmation - Number | Object:确认交易数
  • error - Error:发送交易的错误信息
youchain.you.accounts.signTransaction({
    gasPrice: '0x09184e72a000',
    gas: 40000,
    to: '0x9c75211DBE849b1b9Ee8b7068E6fb64DF6Be600e',
    value: 100000000000    
}, privateKey )
.then(async ({rawTransaction}) => {
    console.log('balance ###', await youchain.you.getBalance(address));
youchain.you.sendSignedTransaction(rawTransaction)
.on('transactionHash', (hash) => {
    console.log('transactionHash', hash);
})
.on('receipt', (receipt) => {
    console.log('receipt', receipt);
})            
.on('error', (error) => {                
    console.log('error', error);
});
})
.catch(console.log);

sign

描述:用账户对数据进行签名,账户地址需要处于解锁状态。

参数值:

Type Note
String 签名数据的地址
String 添加需要签名的数据
Callback (可选值) 回调函数

返回值:

Promise 返回字符串 - 数据的签名

youchain.you.sign("0x7Ef0b27427bd79F0cbF8f81e5768fc490b553e54", "Hello YOUChain").then(console.log);
> { 
    message: '0x7Ef0b27427bd79F0cbF8f81e5768fc490b553e54',
    messageHash:
    '0x9e1c3056eddb66ec4517c9c021e5346cbb6431792f5e1aa8cb4923c219386a46',
    v: '0x1c',
    r: '0x55a87f8882fdccafccb9828750f3217163de87fc62b20a75ed20050056449758',
    s: '0x74a1d62aa197e28510d8767b0517a8d01ec494ab8a69e80358e38ad7f53aff16',
    signature: '0x55a87f8882fdccafccb9828750f3217163de87fc62b20a75ed2005005644975874a1d62aa197e28510d8767b0517a8d01ec494ab8a69e80358e38ad7f53aff161c' 
}

call

描述:执行虚拟机中的代码,但矿工为其不会挖矿。

参数值:

Type Note
Object 交易对象数据
Number, String 默认值为 default block
Callback (可选参数) 回调函数

返回值:

Promise 返回字符串 - 调用合约返回的数据,如:合约方法的返回值

youchain.you.call({
    to: "0x11f4d0A3c12e86B4b5F39B213F7E19D048276DAe", 
    // contract address
    data: "0xc6888fa10000000000000000000000000000000000000000000000000000000000000003"
})
.then(console.log);
> "0x000000000000000000000000000000000000000000000000000000000000000a"

getPastLogs

描述:通过给定过滤条件查找历史日志

参数值:

名称 类型 备注
fromBlock Number, String "latest", "pending"
toBlock Number, String "latest", "pending"
address String, Array 需要过滤的地址字符串或数组
topic Array 在日志文件中出现的值,值也可以为 null 或 [null, ['option1','option2']]

返回值:

Promise 返回一个日志对象的数组:

名称 类型 备注
address String 产生事件的地址
data String 日志数据
logIndex Number 在日志中的索引
transactionIndex Number 产生事件的交易的索引
transactionHash String,32 byte 交易的哈希值
blockHash String,32 byte 事件所在的区块哈希
blockNumber Number 生成日志的区块号。对于挂起状态,返回值为 null

举例:

youchain.you.getPastLogs({
    "address": "0x11f4d0A3c12e86B4b5F39B213F7E19D048276DAe",
    "topic": null
}).then(console.log);

estimateGas

描述:执行消息调用所消耗的 Gas 费用

参数值;

  1. Object - 交易对象
  2. Callback - 回调函数

返回值:Promise - 调用交易消耗的 gas 费用

youchain.you.estimateGas({
    to: "0x11f4d0A3c12e86B4b5F39B213F7E19D048276DAe",
    data: "0xc6888fa10000000000000000000000000000000000000000000000000000000000000003"
}).then(console.log);
> "0x0000000000000000000000000000000000000000000000000000000000000015"

getPoolNonce

描述:返回指定地址在交易池中的交易数量。

参数值;账户地址

返回值:Promise - 指定地址在交易池中的交易数量

youchain.you.getPoolNonce("0x9c651b933bDCc4Ceb3473b7Dc76930c961067c7a").then( count => {
    console.log("transaction count: ", count);
})

getPoolTransaction

描述:根据指定交易 hash 返回在交易池中的交易信息。若交易已被确认,则返回空,此时使用 youchain.you.getTransactionReceipt 方法进行查询交易。

参数值;transactionHash - 交易哈希

返回值:Promise - 交易池中指定的交易对象

youchain.you.getPoolTransaction("0xbf042e06ad283276978f5e32ff232319da3a73e430500f612be8fc4882cc7fd6").then( transaction => {
    console.log("transaction object: ", transaction);
})

getProof

描述:根据 address,存储值返回包含 Merkle-proof 的指定账户

参数值;

类型 备注
string 账户地址
Array 存储值数组
string or number 整数块编号,或字符串"latest"表示最后挖出的块,"pending"或"earliest"
Function (Optional) callback

返回值:

参数 数据类型 备注
balance number 余额
codeHash string,32 字节 账户的 hash
nonce number 本次交易之前发送方已经生成的交易数量
storageHash string, 32 字节 proof的sha3
accountProof Array MerkleTree 节点数组
storageProof Array 请求的存储入口对象
address string, 20 字节 账户地址

示例:

youchain.you.getProof(
        "0xcF9F5007AA1A9ae7b8092DBE3E12B3B97fD5b18D", 
        ["0x000000000000000000000000000000000000000000000001bc16d674ec800000"], 
        "latest").then(console.log);