web3.eth.Contract详解

该web3.eth.Contract对象可以轻松地与以太坊区块链上的智能合约进行交互。当你创建一个新的合约对象时，你给它相应的智能合约的json接口，web3将自动将所有的调用转换为RPC的低级别ABI调用。

这允许您与智能合约进行交互，就像它们是JavaScript对象一样。
独立使用：

新合约

new web3.eth.Contract(jsonInterface[, address][, options])
创建一个新的契约实例及其在json接口对象中定义的所有方法和事件。

参数

1. jsonInterface- Object：实例化合约的json接口
2. address- String（可选）：要调用的智能合约的地址，可以在以后添加myContract.options.address = ‘0x1234…’
3. options- Object（可选）：合约的选项。有些用作调用和交易的后备：

• from- String：地址交易应该来自。
• gasPrice- String：用于交易的用于天然气的价格。
• gas- Number：为交易提供的最大气体（气体限制）。
• data- String：合约的字节代码。合约部署时使用。

返回

Object：合约实例及其所有方法和事件。

示例

var myContract = new web3.eth.Contract([…], ‘0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe’, {
from: ‘0x1234567890123456789012345678901234567891’, // 交易地址
gasPrice: ‘20000000000’ // 默认gas
});

=属性=

选项

myContract.options
object合约实例的选项。from，gas并gasPrice在发送事务时用作后备值。

属性

Object - 选项：
• address- String：部署合约的地址。请参阅options.address。
• jsonInterface- Array：合约的json接口。请参见options.jsonInterface。
• data- String：合约的字节代码。合约部署时使用。
• from- String：地址交易应该来自。
• gasPrice- String：用于交易的用于天然气的价格。
• gas- Number：为交易提供的最大气体（气体限制）。

示例

myContract.options;

{
address: ‘0x1234567890123456789012345678901234567891’,
jsonInterface: […],
from: ‘0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe’,
gasPrice: ‘10000000000000’,
gas: 1000000
}

myContract.options.from = ‘0x1234567890123456789012345678901234567891’; // 交易地址
myContract.options.gasPrice = ‘20000000000000’; // 默认的gas价格
myContract.options.gas = 5000000; // 默认的gas

options.address

myContract.options.address
用于此合约实例的地址。web3.js从此合约生成的所有事务都将此地址包含为“to”。

地址将以小写形式存储。

属性

address- String|null：此合约的地址，或者null尚未设置的地址。

示例

myContract.options.address;

‘0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae’

// 设置新地址
myContract.options.address = ‘0x1234FFDD…’;

---

options.jsonInterface

myContract.options.jsonInterface
的JSON接口从派生对象ABI本合约。

属性

jsonInterface- Array：此合约的json接口。重新设置它将重新生成合约实例的方法和事件。

示例

myContract.options.jsonInterface;

[{
“type”:“function”,
“name”:“foo”,
“inputs”: [{“name”:“a”,“type”:“uint256”}],
“outputs”: [{“name”:“b”,“type”:“address”}]
},{
“type”:“event”,
“name”:“Event”
“inputs”: [{“name”:“a”,“type”:“uint256”,“indexed”:true},{“name”:“b”,“type”:“bytes32”,“indexed”:false}],
}]

//设置接口
myContract.options.jsonInterface = […];

=方法=
克隆

myContract.clone()
克隆当前合约实例。

参数

没有

返回

Object：新的合约实例。

示例

var contract1 = new eth.Contract(abi, address, {gasPrice: ‘12345678’, from: fromAddress});

var contract2 = contract1.clone();
contract2.options.address = address2;

(contract1.options.address !== contract2.options.address);

true

部署

myContract.deploy(options)
调用此函数将合约部署到区块链。成功部署后，承诺将通过新的合约实例解决。

参数

1. options- Object：用于部署的选项。
   • data- String：合约的字节代码。
   • arguments- Array（可选）：在部署时传递给构造函数的参数。

返回

Object：事务对象：
• Array - arguments：之前传递给方法的参数。它们可以改变。
• Function- 发送：将部署合约。承诺将通过新的合约实例解决，而不是收据！
• Function- 估计气体：估计用于部署的气体。
• Function- encodeABI：对部署的ABI进行编码，即合约数据+构造函数参数
有关方法的详细信息，请参阅以下文档。

示例

myContract.deploy({
data: ‘0x12345…’,
arguments: [123, ‘My String’]
})
.send({
from: ‘0x1234567890123456789012345678901234567891’,
gas: 1500000,
gasPrice: ‘30000000000000’
}, function(error, transactionHash){ … })
.on(‘error’, function(error){ … })
.on(‘transactionHash’, function(transactionHash){ … })
.on(‘receipt’, function(receipt){
console.log(receipt.contractAddress) // 合约地址内容
})
.on(‘confirmation’, function(confirmationNumber, receipt){ … })
.then(function(newContractInstance){
console.log(newContractInstance.options.address) //合约地址实例
});

// 合约数据设置
myContract.options.data = ‘0x12345…’;

myContract.deploy({
arguments: [123, ‘My String’]
})
.send({
from: ‘0x1234567890123456789012345678901234567891’,
gas: 1500000,
gasPrice: ‘30000000000000’
})
.then(function(newContractInstance){
console.log(newContractInstance.options.address) //合约地址实例
});

// 合约编码
myContract.deploy({
data: ‘0x12345…’,
arguments: [123, ‘My String’]
})
.encodeABI();

‘0x12345…0000012345678765432’

//气体估算
myContract.deploy({
data: ‘0x12345…’,
arguments: [123, ‘My String’]
})
.estimateGas(function(err, gas){
console.log(gas);
});

方法

myContract.methods.myMethod([param1[, param2[, …]]])
为该方法创建一个事务对象，然后可以调用，发送，估计。
这种智能合约的方法可通过以下方式获得：

• 名字： myContract.methods.myMethod(123)
• 带参数的名称： myContract.methods’myMethod(uint256)’
• 签名： myContract.methods’0x58cf5f10’
这允许调用与JavaScript合约对象具有相同名称但不同参数的函数。

参数

任何方法的参数都取决于JSON接口中定义的智能契约方法。

返回

Object：事务对象：
• Array - arguments：之前传递给方法的参数。它们可以改变。
• Function- call：将调用“常量”方法并在EVM中执行其智能合约方法而不发送事务（不能改变智能合约状态）。
• Function- send：将事务发送到智能合约并执行其方法（可以改变智能合约状态）。
• Function- 估计气体：将估算方法在链上执行时使用的气体。
• Function- encodeABI：为此方法编码ABI。这可以使用事务发送，调用方法或传入另一个智能合约方法作为参数。
有关方法的详细信息，请参阅以下文档。

示例

//调用方法
myContract.methods.myMethod(123).call({from: ‘0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe’}, function(error, result){
…
});

// 调用send方法
myContract.methods.myMethod(123).send({from: ‘0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe’})
.then(function(receipt){
//接收也可以是一个新的合约实例，来自一个"contract.deploy({…}).send()"
});

// 调用和事件事件使用
myContract.methods.myMethod(123).send({from: ‘0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe’})
.on(‘transactionHash’, function(hash){
…
})
.on(‘receipt’, function(receipt){
…
})
.on(‘confirmation’, function(confirmationNumber, receipt){
…
})
.on(‘error’, console.error);

methods.myMethod.call

myContract.methods.myMethod([param1[, param2[, …]]]).call(options[, callback])
将调用“常量”方法并在EVM中执行其智能合约方法而不发送任何事务。注意调用不能改变智能合约状态。

参数

1. options- Object（可选）：用于调用的选项。
   • from- String（可选）：应该从中调用“事务”的地址。
   • gasPrice- String（可选）：用于此调用“交易”的wei的汽油价格。
   • gas- Number（可选）：为此调用“交易”（气体限制）提供的最大气体。
2. callback- Function（可选）：将使用智能合约方法执行的结果作为第二个参数或使用错误对象作为第一个参数来触发此回调。

返回

Promise返回Mixed：智能合约方法的返回值。如果它返回单个值，则按原样返回。如果它有多个返回值，则它们将作为具有属性和索引的对象返回：

示例

//回调使用
myContract.methods.myMethod(123).call({from: ‘0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe’}, function(error, result){
…
});
// 使用 promise
myContract.methods.myMethod(123).call({from: ‘0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe’})
.then(function(result){
…
});
// 多个返回值
// Solidity
contract MyContract {
function myFunction() returns(uint256 myNumber, string myString) {
return (23456, “Hello!%”);
}
}
// web3.js
var MyContract = new web3.eth.Contract(abi, address);
MyContract.methods.myFunction().call()
.then(console.log);

Result {
myNumber: ‘23456’,
myString: ‘Hello!%’,
0: ‘23456’,
1: ‘Hello!%’
}
// 单个返回值
// Solidity
contract MyContract {
function myFunction() returns(string myString) {
return “Hello!%”;
}
}
// web3.js
var MyContract = new web3.eth.Contract(abi, address);
MyContract.methods.myFunction().call()
.then(console.log);
“Hello!%”

methods.myMethod.send

myContract.methods.myMethod([param1[, param2[, …]]]).send(options[, callback])
将事务发送到智能合约并执行其方法。请注意，这可以改变智能合约状态。

参数

• options- Object：用于发送的选项。
• from- String：应从中发送事务的地址。
• gasPrice- String（可选）：用于此交易的wei的汽油价格。
• gas- Number（可选）：为此交易提供的最大气体（气体限制）。
• value- Number | String | BN | BigNumber（可选）：为wei中的事务传输的值。
• callback- Function（可选）：首先使用“transactionHash”或使用错误对象作为第一个参数触发此回调。

返回

该回调将返回32个字节的交易哈希值。
PromiEvent：一个组合事件发射器的承诺。将在事务收据可用时解决，或者如果send()从a调用someContract.deploy()，则承诺将使用新的合约实例解析。此外，还提供以下活动：

• "transactionHash"返回String：在发送事务并且事务哈希可用之后立即触发。
• "receipt"return Object：在事务收据可用时触发。合约收据不具有logs属性，而是events具有事件名称作为键和事件作为属性的属性。有关返回的事件对象的详细信息，请参阅getPastEvents返回值。
• "confirmation"回报Number，Object：被激发每一个确认直到24日确认。接收确认编号作为第一个参数，将收据作为第二个参数。从确认1开始，这是它的意思。
• "error"返回Error：如果在发送过程中发生错误，则触发。如果出现气体错误，则第二个参数是收货。

示例

//回调
myContract.methods.myMethod(123).send({from: ‘0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe’}, function(error, transactionHash){
…
});
// 调用 promise
myContract.methods.myMethod(123).send({from: ‘0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe’})
.then(function(receipt){
//接收也可以是一个新的合约实例，来自一个"contract.deploy({…}).send()"
});

//使用事件发射器
myContract.methods.myMethod(123).send({from: ‘0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe’})
.on(‘transactionHash’, function(hash){
…
})
.on(‘confirmation’, function(confirmationNumber, receipt){
…
})
.on(‘receipt’, function(receipt){
console.log(receipt);
> {
“transactionHash”: “0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b”,
“transactionIndex”: 0,
“blockHash”: “0xef95f2f1ed3ca60b048b4bf67cde2195961e0bba6f70bcbea9a2c4e133e34b46”,
“blockNumber”: 3,
“contractAddress”: “0x11f4d0A3c12e86B4b5F39B213F7E19D048276DAe”,
“cumulativeGasUsed”: 314159,
“gasUsed”: 30234,
“events”: {
“MyEvent”: {
returnValues: {
myIndexedParam: 20,
myOtherIndexedParam: ‘0x123456789…’,
myNonIndexParam: ‘My String’
},
raw: {
data: ‘0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385’,
topics: [‘0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7’, ‘0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385’]
},
event: ‘MyEvent’,
signature: ‘0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7’,
logIndex: 0,
transactionIndex: 0,
transactionHash: ‘0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385’,
blockHash: ‘0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7’,
blockNumber: 1234,
address: ‘0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe’
},
“MyOtherEvent”: {
…
},
“MyMultipleEvent”:[{…}, {…}] //如果有多个相同的事件，它们将在一个数组中 }
}
})
.on(‘error’, console.error); //如果出现气体不足错误，则第二个参数是收据。

methods.myMethod.estimateGas

myContract.methods.myMethod([param1[, param2[, …]]]).estimateGas(options[, callback])
将调用估计在EVM中执行时执行将执行的方法的气体。估计可能与后来发送交易时使用的实际气体不同，因为智能合约的状态在那时可能不同。

参数

•options- Object（可选）：用于调用的选项。
• from- String（可选）：应该从中调用“事务”的地址。
• gas- Number（可选）：为此调用“交易”（气体限制）提供的最大气体。设置特定值有助于检测气体错误。如果使用所有气体，它将返回相同的数字。
• value- Number | String | BN | BigNumber（可选）：为wei中的调用“transaction”传输的值。
• callback- Function（可选）：将使用气体估计的结果作为第二个参数或使用错误对象作为第一个参数来触发此回调。

返回

Promise返回Number：估计的气体量。

示例

// 回调
myContract.methods.myMethod(123).estimateGas({gas: 5000000}, function(error, gasAmount){
if(gasAmount == 5000000)
console.log(‘Method ran out of gas’);
});

// 调用 promise
myContract.methods.myMethod(123).estimateGas({from: ‘0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe’})
.then(function(gasAmount){
…
})
.catch(function(error){
…
});

---

methods.myMethod.encodeABI

myContract.methods.myMethod([param1[, param2[, …]]]).encodeABI()
为此方法编码ABI。这可用于发送事务，调用方法或将其作为参数传递给另一个智能合约方法。

参数

没有

返回

String：通过事务或调用发送的编码ABI字节代码。

示例

myContract.methods.myMethod(123).encodeABI();

‘0x58cf5f1000000000000000000000000000000000000000000000000000000000000007B’

=事件=

一次
myContract.once(event[, options], callback)

订阅事件并在第一个事件或错误后立即取消订阅。只会针对单个事件开火。
参数
• event- String：合约中的事件名称，或"allEvents"获取所有事件。
• options- Object（可选）：用于部署的选项。
• filter- Object（可选）：允许您通过索引参数过滤事件，例如，表示“myNumber”为12或13的所有事件。{filter: {myNumber: [12,13]}}
• topics- Array（可选）：这允许您手动设置事件过滤器的主题。如果给定过滤器属性和事件签名，则不会自动设置（topic [0]）。
• callback- Function：这个回调将作为第二个参数触发第一个事件，或者作为第一个参数触发错误。有关事件结构的详细信息，请参阅getPastEvents返回值。
返回
undefined

示例

myContract.once(‘MyEvent’, {
filter: {myIndexedParam: [20,23], myOtherIndexedParam: ‘0x123456789…’},
fromBlock: 0
}, function(error, event){ console.log(event); });

//事件输出示例

{
returnValues: {
myIndexedParam: 20,
myOtherIndexedParam: ‘0x123456789…’,
myNonIndexParam: ‘My String’
},
raw: {
data: ‘0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385’,
topics: [‘0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7’, ‘0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385’]
},
event: ‘MyEvent’,
signature: ‘0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7’,
logIndex: 0,
transactionIndex: 0,
transactionHash: ‘0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385’,
blockHash: ‘0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7’,
blockNumber: 1234,
address: ‘0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe’
}

事件
myContract.events.MyEvent([options][, callback])

订阅活动

参数
• options- Object（可选）：用于部署的选项。
• filter- Object（可选）：允许您通过索引参数过滤事件，例如，表示“myNumber”为12或13的所有事件。{filter: {myNumber: [12,13]}}
• fromBlock- Number（可选）：从中获取事件的块编号。
• topics- Array（可选）：这允许手动设置事件过滤器的主题。如果给定过滤器属性和事件签名，则不会自动设置（topic [0]）。
• callback- Function（可选）：将为每个事件触发此回调作为第二个参数，或将错误作为第一个参数触发。

返回

EventEmitter：事件发射器具有以下事件：
• "data"返回Object：以事件对象作为参数触发每个传入事件。
• "changed"返回Object：触发从区块链中删除的每个事件。该活动将拥有额外的财产。“removed: true”
• "error"返回Object：订阅中的错误发生时触发。

返回事件的结构Object如下所示：

• event- String：事件名称。
• signature- String|Null：事件签名，null如果是匿名事件。
• address- String：解决此事件的起源。
• returnValues- Object：来自事件的返回值，例如。{myVar: 1, myVar2: ‘0x234…’}
• logIndex- Number：块中事件索引位置的整数。
• transactionIndex- Number：事件创建时的事务索引位置的整数。
• transactionHash32字节 - String：此事件创建的事务的哈希值。
• blockHash32字节 - String：此事件创建的块的哈希值。null当它仍处于待定状态时。
• blockNumber- Number：此日志创建的块编号。null当仍处于挂起状态时。
• raw.data- String：包含非索引日志参数的数据。
• raw.topics- Array：具有最多4个32字节主题的数组，主题1-3包含事件的索引参数。

示例

myContract.events.MyEvent({
filter: {myIndexedParam: [20,23], myOtherIndexedParam: ‘0x123456789…’},
fromBlock: 0
}, function(error, event){ console.log(event); })
.on(‘data’, function(event){
console.log(event); //与上面的可选回调相同的结果
})
.on(‘changed’, function(event){
//从本地数据库中删除事件
})
.on(‘error’, console.error);

//事件输出示例

{
returnValues: {
myIndexedParam: 20,
myOtherIndexedParam: ‘0x123456789…’,
myNonIndexParam: ‘My String’
},
raw: {
data: ‘0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385’,
topics: [‘0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7’, ‘0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385’]
},
event: ‘MyEvent’,
signature: ‘0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7’,
logIndex: 0,
transactionIndex: 0,
transactionHash: ‘0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385’,
blockHash: ‘0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7’,
blockNumber: 1234,
address: ‘0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe’
}
events.allEvents
myContract.events.allEvents([options][, callback])
与事件相同，但接收来自此智能合约的所有事件。可选地，filter属性可以过滤这些事件。

getPastEvents
myContract.getPastEvents(event[, options][, callback])
获取此合约的过去事件。

参数

• event- String：合约中的事件名称，或"allEvents"获取所有事件。
• options- Object（可选）：用于部署的选项。
• filter- Object（可选）：允许您通过索引参数过滤事件，例如，表示“myNumber”为12或13的所有事件。{filter: {myNumber: [12,13]}}
• fromBlock- Number（可选）：从中获取事件的块编号。
• toBlock- Number（可选）：用于获取事件的块编号（默认为"latest"）。
• topics- Array（可选）：这允许手动设置事件过滤器的主题。如果给定过滤器属性和事件签名，则不会自动设置（topic [0]）。
• callback- Function（可选）：将使用一组事件日志作为第二个参数或作为第一个参数的错误来触发此回调。

返回

Promise返回Array：包含过去事件的数组Objects，匹配给定的事件名称和过滤器。
对于返回事件的结构，Object请参阅getPastEvents返回值。

示例

myContract.getPastEvents(‘MyEvent’, {
filter: {myIndexedParam: [20,23], myOtherIndexedParam: ‘0x123456789…’},
fromBlock: 0,
toBlock: ‘latest’
}, function(error, events){ console.log(events); })
.then(function(events){
console.log(events) //与上面的可选回调相同的结果
});

[{
returnValues: {
myIndexedParam: 20,
myOtherIndexedParam: ‘0x123456789…’,
myNonIndexParam: ‘My String’
},
raw: {
data: ‘0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385’,
topics: [‘0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7’, ‘0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385’]
},
event: ‘MyEvent’,
signature: ‘0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7’,
logIndex: 0,
transactionIndex: 0,
transactionHash: ‘0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385’,
blockHash: ‘0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7’,
blockNumber: 1234,
address: ‘0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe’
},{
…
}]