web3.js使用手册

web3.js是一组用来和本地或远程以太坊节点进行交互的js库，它可以使用HTTP或IPC建立与以太坊节点旳连接。

本文档是web3.js 1.0的API参考手册，其中每个API都包含有示例代码。

web3

web3是顶层包，它包含了所有以太坊相关的模块。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
var Web3 = require('web3');

> Web3.utils
> Web3.version
> Web3.modules

// 在支持以太坊的浏览器中，Web3.providers.givenProvider将被自动设置
var web3 = new Web3(Web3.givenProvider || 'ws://some.local-or-remote.node:8546');

> web3.eth
> web3.shh
> web3.bzz
> web3.utils
> web3.version

web3.eth

web3-eth这个包用来和以太坊区块链与智能合约交互。

1
2
3
4
5
6
7
8
9
10
11
12
var Eth = require('web3-eth');

// "Eth.providers.givenProvider" will be set if in an Ethereum supported browser.
var eth = new Eth(Eth.givenProvider || 'ws://some.local-or-remote.node:8546');


// or using the web3 umbrella package

var Web3 = require('web3');
var web3 = new Web3(Web3.givenProvider || 'ws://some.local-or-remote.node:8546');

// -> web3.eth

web3.eth.subscribe

web3.eth.subscribe函数系列的作用是订阅区块链上的事件。

web3.eth.Contract

web3.eth.Contract对象简化了与以太坊区块链上合约的交互。 合约对象的json接口与 相应的智能合约相匹配，web3会自动帮你将所有的调用转化为底层的基于RPC的ABI调用。

这使得与智能合约的交互和操作JavaScript对象一样简单。

web3.eth.accounts

web3.eth.accounts包含了与以太坊账户创建、交易和数据签名相关的函数。

可以单独使用这个包：

1
2
3
4
5
var Accounts = require('web3-eth-accounts');

// Passing in the eth or web3 package is necessary to allow retrieving chainId, gasPrice and nonce automatically
// for accounts.signTransaction().
var accounts = new Accounts('ws://localhost:8546');

web3.eth.personal

web3-eth-personal包的作用是与以太坊节点上的账户进行交互。

1
2
3
4
5
6
7
8
9
10
11
12
var Personal = require('web3-eth-personal');

// 在支持以太坊的浏览器中，`Personal.providers.givenProvider`将被自动设置
var personal = new Personal(Personal.givenProvider || 'ws://some.local-or-remote.node:8546');


// 也可以通过web3顶层包使用

var Web3 = require('web3');
var web3 = new Web3(Web3.givenProvider || 'ws://some.local-or-remote.node:8546');

// -> web3.eth.personal

web3.eth.Iban

web3.eth.Iban函数系列用于在以太坊地址、IBAN/BBAN地址之间进行转换。

web3.eth.abi

web3.eth.abi函数系列用于将函数调用编码为ABI格式，或者反之。

web3.*.net

web3-net包用来访问以太坊节点旳网络属性。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
var Net = require('web3-net');

// 在支持以太坊的浏览器中，Personal.providers.givenProvider被自动赋值
var net = new Net(Net.givenProvider || 'ws://some.local-or-remote.node:8546');


// 也可以使用web3顶层报

var Web3 = require('web3');
var web3 = new Web3(Web3.givenProvider || 'ws://some.local-or-remote.node:8546');

// -> web3.eth.net
// -> web3.bzz.net
// -> web3.shh.net

web3.bzz

web3-bzz包用来与去中心化文件存储系统swarm进行交互。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
var Bzz = require('web3-bzz');

// 可以自动检测ethereum对象是否存在，将连接到本地节点或swarm-gateways.net
// 可选地，可以指定一个服务提供器URL，当没有指定服务提供器URL时，将使用http://swarm-gateways.net
var bzz = new Bzz(Bzz.givenProvider || 'http://swarm-gateways.net');


// 也可以通过web3顶层包使用

var Web3 = require('web3');
var web3 = new Web3(Web3.givenProvider || 'ws://some.local-or-remote.node:8546');

// -> web3.bzz.currentProvider 
// 如果Web3.givenProvider时一个以太坊服务提供器，该属性将被赋值为 http://localhost:8500 ，
//否则被赋值为 http://swarm-gateways.net

// 必要时可以手工设置服务提供器
web3.bzz.setProvider("http://localhost:8500");

web3.shh

web3-shh包用来与whisper协议进行交互，以便进行广播。

1
2
3
4
5
6
7
8
9
10
11
12
var Shh = require('web3-shh');

// `Shh.providers.givenProvider`在支持以太坊的浏览器中将被自动赋值
var shh = new Shh(Shh.givenProvider || 'ws://some.local-or-remote.node:8546');


// 也可以通过web3顶层包使用

var Web3 = require('web3');
var web3 = new Web3(Web3.givenProvider || 'ws://some.local-or-remote.node:8546');

// -> web3.shh

web3.utils

这个包提供以太坊Dapp开发相关的工具函数等。