汇智网 H web3.js API 中文文档 1 / 52 导读 以太坊是什么 以太坊是一个全新开放的区块链平台，它允许任何人在平台中建立和使用通过区块链技术运行的去中心化应用。就像比特币一样，以太坊丌受任何人控制，也丌归任何人所有 它是一个开放源代码项目，由全球范围内的很多人共同创建。和比特币协议 有所丌同的是，以太坊的设计十分灵活，极具适应性。在以太坊平台上创立新的应用十分简便，随着 Homestead 的发布，任何人都可以安全地使用该平台上的应用。 本电子书原文 最早 发布于 区块链技术博客 （ http// tryblockchain.org） ， 由汇智网（ http//）编目整理， 是目前网上流传的最完整的web3.jsAPI 文档中文版 。 但由于以太坊本身（以及周边生态） 的发展非常快，一些实践性内容已经落后于现状。因此编者建议本电子书的读者，在阅读时应注意吸收核心的理念思想，而丌要过分关注书中的实践操作环节。 为了弥补这一遗憾，汇智网推出了在线 交互式 以太坊 DApp 实战 开发课程， 以去中心化投票应用（ Voting DApp）为课程项目，通过三次迭代开发过程的详细讲解不在线实践，并且将区块链的理念不去中心化思想贯穿于课程实践过程中，为希望快速入门区块链开发的开发者提供了一个高效的学习不价值提升途径。读者可以通过以下链接访问以太坊 DApp 开发实战入门在线教程 汇智网 H web3.js API 中文文档 2 / 52 http// 教程预置了开发环境。进入教程后，可以在每一个知识点 立刻 进行同步实践，而丌必在开发环境的 搭建上浪费时间 汇智网 H 2018.2 web3 web3 对象提供了所有方法。 示例 //初始化过程 var Web3 requireweb3; if typeof web3 undefined { web3 new Web3web3.currentProvider; } else { 汇智网 H web3.js API 中文文档 3 / 52 // set the provider you want from Web3.providers web3 new Web3new Web3.providers.HttpProvider“http//localhost8545“; } web3.version.api web3.version.api 返回值 String - 以太坊 js 的 api 版本 示例 //省略初始化过程 var version web3.version.api; console.logversion; node test.js 0.18.2 web3.version.node 同步方式 web3.verison.node 异步方式 web3.version.getNodecallbackerror, result{ . } 返回值 String - 客户端或节点的版本信息 示例 //省略初始化过程 var version web3.version.node; console.logversion; node test.js EthereumJS TestRPC/v3.0.3/ethereum-js 汇智网 H web3.js API 中文文档 4 / 52 work 同步方式 work 异步方式 web3.version.getNetworkcallbackerror, result{ . } 返回值 String - 网络协议版本 示例 //省略初始化过程 var version work; console.logversion; node test.js 1488546587563 web3.version.ethereum 同步方式 web3.version.ethereum 异步方式 web3.version.getEthereumcallbackerror, result{ . } 返回值 String - 以太坊的协议版本 示例 //省略初始化过程 var version web3.version.ethereum; console.logversion; node test.js 60 汇智网 H web3.js API 中文文档 5 / 52 注意 EthereumJS testRPC 客户端不支持这个命令，报错 Error Error RPC eth_protocolVersion not supported. web3.version.whisper 同步方式 web3.version.whisper 异步方式 web3.version.getWhispercallbackerror, result{ . } 返回值 String - whisper 协议的版本 示例 //省略初始化过程 var version web3.version.whisper; console.logversion; node test.js 20 注意 EthereumJS testRPC 客户端不支持这个命令，报错 Error Error RPC shh_version not supported. web3.isConnected web3.isConnected 可以用来检查到节点的连接是否存在（ connection to node exist）。 参数 无 返回值 Boolean 汇智网 H web3.js API 中文文档 6 / 52 示例 //省略初始化过程 var connected web3.isConnected; ifconnected{ console.log“node not connected“; }else{ console.log“node connected“; } web3.setProvider web3.setProvider 设置 Provider 参数 无 返回值 undefined 示例 web3.setProvidernew web3.providers.HttpProviderhttp//localhost8545; web3.currentProvider web3.currentProvider 如果已经设置了 Provider，则返回当前的 Provider。这个方法可以用来检查在使用 mist 浏览器等情况下已经设置过 Provider，避免重复设置的情况。 返回值 Object - null 或 已经设置的 Provider。 示例 ifweb3.currentProvider web3.setProvidernew web3.providers.HttpProvider“http//localhost8545“; 汇智网 H web3.js API 中文文档 7 / 52 web3.reset web3.reset 用来重置 web3 的状态。重置除了 manager 以外的其它所有东西。卸载 filter，停止状态轮询。 参数 1. Boolean - 如果设置为 true，将会卸载所有的 filter，但会保留web3.eth.isSyncing的状态轮询。 返回值 undefined 示例 //省略初始化过程 console.log“reseting . “; web3.reset; console.log“is connected“ web3.isConnected; node test.js reseting . is connectedtrue web3.sha3 web3.sha3string, options 参数 1. String - 传入的需要使用 Keccak-256 SHA3 算法进行哈希运算的字符串。 2. Object - 可选项设置。如果要解析的是 hex 格式的十六进制字符串。需要设置 encoding 为 hex。因为 JS 中会默认忽略 0 x。 返回值 String - 使用 Keccak-256 SHA3 算法哈希过的结果。 汇智网 H web3.js API 中文文档 8 / 52 示例 //省略初始化过程 var hash web3.sha3“Some string to be hashed“; console.loghash; var hashOfHash web3.sha3hash, {encoding hex}; console.loghashOfHash; web3.toHex web3.toHex 将任何值转为 HEX。 参数 1. String|Number|Object|Array|BigNumber - 需要转化为 HEX 的值。如果是一个对象或数组类型，将会先用 JSON.stringify 1进行转换成字符串。如果传入的是 BigNumber 2，则将得到对应的 Number 的 HEX。 示例 //初始化基本 对象 var Web3 requireweb3; var web3 new Web3new Web3.providers.HttpProvider“http//localhost8545“; var BigNumber requirebignumber.js; var str “abcABC“; var obj {abc ABC}; var bignumber new BigNumber12345678901234567890; var hstr web3.toHexstr; var hobj web3.toHexobj; var hbg web3.toHexbignumber; console.log“Hex of Sring“ hstr; console.log“Hex of Object“ hobj; console.log“Hex of BigNumber“ hbg; node test.js Hex of Sring0 x616263414243 Hex of Object0 x7b22616263223a22414243227d 汇智网 H web3.js API 中文文档 9 / 52 Hex of BigNumber0 xab54a98ceb1f0ad2 web3.toAscii web3.toAsciihexString 将 HEX 字符串转为 ASCII 3字符串 参数 1. String - 十六进制字符串。 返回值 String - 给定十六进制字符串对应的 ASCII 码值。 示例 var str web3.toAscii“0 x657468657265756d000000000000000000000000000000000000000000000000“; console.logstr; // “ethereum“ web3.fromAscii web3.fromAscii 将任何的 ASCII 码字符串转为 HEX 字符串。 参数 1. String - ASCII 码字符串 2. Number - 返回的字符串字节大小，不够长会自动填充。 返回值 String - 转换后的 HEX 字符串。 示例 var str web3.fromAsciiethereum; console.logstr; // “0 x657468657265756d“ var str2 web3.fromAsciiethereum, 32; 汇智网 H web3.js API 中文文档 10 / 52 console.logstr2; // “0 x657468657265756d000000000000000000000000000000000000000000000000“ node test.js 0 x657468657265756d 0 x657468657265756d 备注 填充 padding 功能好像不可用 4。 web3.toDecimal web3.toDecimal 将一个十六进制转为一个十进制的数字 参数 1. String - 十六进制字符串 返回 Number - 传入字符串所代表的十六进制值。 示例 var number web3.toDecimal0 x15; console.lognumber; // 21 web3.fromDecimal web3.fromDecimal 将一个数字，或者字符串形式的数字转为一个十六进制串。 参数 1. Number|String - 数字 返回值 String - 给定数字对应的十六进制表示。 示例 var value web3.fromDecimal21; 汇智网 H web3.js API 中文文档 11 / 52 console.logvalue; // “0 x15“ web3.fromWei web3.fromWeinumber, 单位 以太坊货币单位之间的转换。将以 wei 为单位的数量，转为下述的单位，可取值如下  kwei/ada  mwei/babbage  gwei/shannon  szabo  finney  ether  kether/grand/einstein  mether  gether  tether 参数 1. Number|String|BigNumber - 数字或 BigNumber。 2. String - 单位字符串 返回值 String|BigNumber - 根据传入参数的不同，分别是字符串形式的字符串，或者是BigNumber。 示例 var value web3.fromWei21000000000000, finney; console.logvalue; // “0.021“ web3.toWei web3.toWeinumber, 单位 按对应货币转为以 wei 为单位。可选择的单位如下  kwei/ada  mwei/babbage 汇智网 H web3.js API 中文文档 12 / 52  gwei/shannon  szabo  finney  ether  kether/grand/einstein  mether  gether  tether 参数 1. Number|String|BigNumber - 数字或 BigNumber 2. String - 字符串单位 返回值 String|BigNumber - 根据传入参数的不同，分别是字符串形式的字符串，或者是BigNumber。 示例 var value web3.toWei1, ether; console.logvalue; // “1000000000000000000“ web3.toBigNumber web3.toBigNumber数字或十六进制字符串 将给定的数字或十六进制字符串转为 BigNumber 5。 参数 1. Number|String - 数字或十六进制格式的数字 返回值 BigNumber - BigNumber 的实例 示例 var value web3.toBigNumber200000000000000000000001; console.logvalue; // instanceOf BigNumber console.logvalue.toNumber; // 2.0000000000000002e23 console.logvalue.toString10; // 200000000000000000000001 汇智网 H web3.js API 中文文档 13 / 52 .listening 同步方式 .listening 异步方式 .getListenercallbackerror, result{ . } 此属性是只读的，表示当前连接的节点，是否正在 listen 网络连接与否。 listen可以理解为接收。 返回值 Boolean - true 表示连接上的节点正在 listen 网络请求，否则返回 false。 示例 var listening .listening; console.log“client listening “ listening; node test.js client listening true 备注 如果关闭我们要连接的测试节点，会报错 Error Invalid JSON RPC response undefined。所以这个方法返回的是我们连上节点的 listen 状态。 .peerCount 同步方式 .peerCount 异步方式 .getPeerCountcallbackerror, result{ . } 属性是只读的，返回连接节点已连上的其它以太坊节点的数量。 返回值 汇智网 H web3.js API 中文文档 14 / 52 Number - 连接节点连上的其它以太坊节点的数量 示例 var peerCount .peerCount; console.log“Peer count “ peerCount; node test.js Peer count 0 web3.eth 包含以太坊区块链相关的方法 示例 var eth web3.eth; web3.eth.defaultAccount web3.eth.defaultAccount 默认的地址在使用下述方法时使用，你也可以选择通过指定 from 属性，来覆盖这个默认设置。  web3.eth.sendTransaction  web3.eth.call 默认值为 undefined， 20 字节大小，任何你有私匙的你自己的地址。 返回值 String - 20 字节的当前设置的默认地址。 示例 console.log“Current default “ web3.eth.defaultAccount; web3.eth.defaultAccount 0 x8888f1f195afa192cfee860698584c030f4c9db1; console.log“Current default “ web3.eth.defaultAccount; node test.js Current default undefined Current default 0 x8888f1f195afa192cfee860698584c030f4c9db1 汇智网 H web3.js API 中文文档 15 / 52 web3.eth.defaultBlock web3.eth.defaultBlock 使用下述方法时，会使用默认块设置，你也可以通过传入 defaultBlock 来覆盖默认配置。  web3.eth.getBalance  web3.eth.getCode  web3.eth.getTransactionCount  web3.eth.getStorageAt  web3.eth.call  contract.my.call  contract.my.estimateGas 可选的块参数，可能下述值中的一个  Number - 区块号  String - earliest，创世块。  String - latest，最近刚出的最新块，当前的区块头。  String - pending，当前正在 mine 的区块，包含正在打包的交易。 默认值是 latest 返回值 Number|String - 默认要查状态的区块号。 示例 console.log“defaultBlock “ web3.eth.defaultBlock; web3.eth.defaultBlock 231; console.log“defaultBlock “ web3.eth.defaultBlock; node test.js defaultBlock latest defaultBlock 231 web3.eth.syncing 同步方式 汇智网 H web3.js API 中文文档 16 / 52 web3.eth.syncing 异步方式 web3.eth.getSyncingcallbackerror, result{ . } 这个属性是只读的。如果正在同步，返回同步对象。否则返回 false。 返回值 Object|Boolean - 如果正在同步，返回含下面属性的同步对象。否则返回 false。 返回值  startingBlock Number - 同步开始区块号  currentBlock Number - 节点当前正在同步的区块号  highestBlock Number - 预估要同步到的区块 var sync web3.eth.syncing; console.logsync; node test.js false //正在 sync的情况 node test.js { startingBlock 300, currentBlock 312, highestBlock 512 } web3.eth.isSyncing web3.eth.isSyncingcallback 提供同步开始，更新，停止的回调函数方法。 返回值 Object - 一个 syncing 对象，有下述方法 汇智网 H web3.js API 中文文档 17 / 52  syncing.addCallback 增加另一个回调函数，在节点开始或停止调用时进行调用。  syncing.stopWatching 停止同步回调。 回调返回值  Boolean - 同步开始时，此值为 true，同步停止时此回调值为 false。  Object - 当正在同步时，会返回同步对象。 o startingBlock Number - 同步开始区块号 o currentBlock Number - 节点当前正在同步的区块号 o highestBlock Number - 预估要同步到的区块 示例 //初始化基本对象 var Web3 requireweb3; var web3 new Web3new Web3.providers.HttpProvider“http//localhost8545“; var BigNumber requirebignumber.js; web3.eth.isSyncingfunctionerror, sync{ iferror { // stop all app activity ifsync true { // we use true, so it stops all filters, but not the web3.eth.syncing polling web3.resettrue; // show sync info } else ifsync { console.logsync.currentBlock; // re-gain app operation } else { // run your app init function. } } }; 汇智网 H web3.js API 中文文档 18 / 52 web3.eth.coinbase 同步方式 web3.eth.coinbase 异步方式 web3.eth.getCoinbasecallbackerror, result{ . } 只读属性，节点配置的，如果挖矿成功奖励的地址。 返回值 String - 节点的挖矿奖励地址。 示例 var coinbase web3.eth.coinbase; console.logcoinbase; // “0 x407d73d8a49eeb85d32cf465507dd71d507100c1“ web3.eth.mining 同步方式 web3.eth.mining 异步方式 web3.eth.getMiningcallbackerror, result{ . } 属性只读，表示该节点是否配置挖矿。 返回值 Boolean - true 表示配置挖矿，否则表示没有。 var mining web3.eth.mining; console.logmining; // true or false web3.eth.hashrate 同步方式 web3.eth.hashrate 汇智网 H web3.js API 中文文档 19 / 52 异步方式 web3.eth.getHashratecallbackerror, result{ . } 属性只读，表示的是当前的每秒的哈希难度。 返回值 Number - 每秒的哈希数 示例 var hashrate web3.eth.hashrate; console.loghashrate; web3.eth.gasPrice 同步方式 web3.eth.gasPrice 异步方式 web3.eth.getGasPricecallbackerror, result{ . } 属性是只读的，返回当前的 gas 价格。这个值由最近几个块的 gas 价格的中值6决定。 返回值 BigNumber - 当前的 gas 价格的 BigNumber 实例，以 wei 为单位。 var gasPrice web3.eth.gasPrice; console.loggasPrice.toString10; // “10000000000000“ web3.eth.accounts 同步方式 web3.eth.accounts 异步方式 web3.eth.getAccountscallbackerror, result{ . } 只读属性，返回当前节点持有的帐户列表。 汇智网 H web3.js API 中文文档 20 / 52 返回值 Array - 节点持有的帐户列表。 示例 var accounts web3.eth.accounts; console.logaccounts; web3.eth.blockNumber 同步方式 web3.eth.blockNumber 异步方式 web3.eth.getBlockNumbercallbackerror, result{ . } 属性只读，返回当前区块号。 var number web3.eth.blockNumber; console.lognumber; // 2744 web3.eth.register web3.eth.registeraddressHexString [, callback] （暂未实现）将给定地址注册到 web3.eth.accounts。这将允许无私匙的帐户，如合约被关联到有私匙的帐户，如合约钱包。 参数  String - 要注册的地址。  Function -（可选）回调函数，用于支持异步的方式执行 7。 返回值 待确定 示例 web3.eth.register“0 x407d73d8a49eeb85d32cf465507dd71d507100ca“ 汇智网 H web3.js API 中文文档 21 / 52 web3.eth.unRegister 异步方式 web3.eth.unRegisteraddressHexString [, callback] （暂未实现）取消注册给定地址 参数  String - 要取消注册的地址  Function - （可选） 回调函数，用于支持异步的方式执行 7。 返回值 待确定 示例 web3.eth.unRegister“0 x407d73d8a49eeb85d32cf465507dd71d507100ca“ web3.eth.getBalance web3.eth.getBalanceaddressHexString [, defaultBlock] [, callback] 获得在指定区块时给定地址的余额。 参数  String - 要查询余额的地址。  Number|String -（可选）如果不设置此值使用 web3.eth.defaultBlock 设定的块，否则使用指定的块。  Funciton - （可选）回调函数，用于支持异步的方式执行 7。 返回值 String - 一个包含给定地址的当前余额的 BigNumber 实例，单位为 wei。 示例 var balance web3.eth.getBalance“0 x407d73d8a49eeb85d32cf465507dd71d507100c1“; 汇智网 H web3.js API 中文文档 22 / 52 console.logbalance; // instanceof BigNumber console.logbalance.toString10; // 1000000000000 console.logbalance.toNumber; // 1000000000000 web3.eth.getStorageAt web3.eth.getStorageAtaddressHexString, position [, defaultBlock] [, callback] 获得某个地址指定位置的存储的状态值。 合约由控制执行的 EVM字节码和用来保存状态的 Storage 两部分组成。 Storage在区块链上是以均为 32 字节的键，值对的形式进行存储 8。 参数  String - 要获得存储的地址。  Number - 要获得的存储的序号  Number|String -（可选）如果未传递参数，默认使用web3.eth.defaultBlock 定义的块，否则使用指定区块。  Function - 回调函数，用于支持异步的方式执行 7。 返回值 String - 给定位置的存储值 示例 var state web3.eth.getStorageAt“0 x407d73d8a49eeb85d32cf465507dd71d507100c1“, 0; console.logstate; // “0 x03“ web3.eth.getCode web3.eth.getCodeaddressHexString [, defaultBlock] [, callback] 获取指定地址的代码 参数  String - 要获得代码的地址。 汇智网 H web3.js API 中文文档 23 / 52  Number|String -（可选）如果未传递参数，默认使用web3.eth.defaultBlock 定义的块，否则使用指定区块。  Function - 回调函数，用于支持异步的方式执行 7。 返回值 String - 给定地址合约编译后的字节代码。 示例 var code web3.eth.getCode“0 xd5677cf67b5aa051bb40496e68ad359eb97cfbf8“; console.logcode; // “0 x600160008035811a818181146012578301005b601b6001356025565b8060005260206000f25b600060078202905091905056“ web3.eth.getBlock web3.eth.getBlockblockHashOrBlockNumber [, returnTransactionObjects] [, callback] 返回块号或区块哈希值所对应的区块 参数  Number|String -（可选）如果未传递参数，默认使用web3.eth.defaultBlock 定义的块，否则使用指定区块。  Boolean -（可选）默认值为 false。 true 会将区块包含的所有交易作为对象返回。否则只返回交易的哈希。  Function - 回调函数，用于支持异步的方式执行 7。 返回值 - 区块对象  Number - 区块号。当这个区块处于 pending 将会返回 null。  hash - 字符串，区块的哈希串。当这个区块处于 pending 将会返回 null。  parentHash - 字符串， 32 字节的父区块的哈希值。 汇智网 H web3.js API 中文文档 24 / 52  nonce - 字符串， 8 字节。 POW 生成的哈希。当这个区块处于 pending将会返回 null。  sha3Uncles - 字符串， 32 字节。叔区块的哈希值。  logsBloom - 字符串，区块日志的布隆过滤器 9。当这个区块处于 pending将会返回 null。  transactionsRoot - 字符串， 32 字节，区块的交易前缀树的根。  stateRoot - 字符串， 32 字节。区块的最终状态前缀树的根。  miner - 字符串， 20 字节。这个区块获得奖励的矿工。  difficulty - BigNumber 类型。当前块的难度，整数。  totalDifficulty - BigNumber 类型。区块链到当前块的总难度，整数。  extraData - 字符串。当前块的 extra data 字段。  size - Number。当前这个块的字节大小。  gasLimit - Numbe