Truffle 5 手册:合约抽象层API

合约抽象对象概述

Truffle提供了一个合约抽象层,用来与合约进行交互。

获取合约抽象对象

要获取合约抽象实例,可以使用artifacts对象的require()方法来载入 指定的合约构件。在控制台环境外,artifacts在迁移文件、测试文件和exec 脚本中也是有效的。可以如下方式创建指定合约的抽象对象:

const MyContract = artifacts.require("MyContract");

在开发控制台中也可以获取到合约抽象实例。在开发控制台可以使用 at、deployed或new方法获取到合约抽象实例:

truffle(development)> const myContract = await MyContract.deployed();

现在可以访问MyContract的以下函数:

  • at(): 创建一个合约抽象实例,表征部署在指定地址的MyContract合约
  • deployed():创建一个合约抽象实例,表征MyContract管理的默认地址
  • new():向链上部署一个新版本合约,并获取新合约对应的抽象实例

合约方法调用

每个合约抽象实例都绑定到以太坊网络上的特定地址,并且js实例的方法与合约 方法是一一对应的。例如,如果你的Solidity合约有一个函数 someFunction(uint value) {},那么可以像这样调用其对应的js方法:

let deployed;
MyContract.deployed()
  .then((instance) => {
    deployed = instance;
    return deployed.someFunction(5);
  }).then((result) => {
    // Do something with the result or continue with more transactions.
  });

也可以使用async/await语法来简化上面的代码。在本文的剩余部分将使用 async/await,但是记住你也可以使用promise来与合约交互:

const deployed = await MyContract.deployed();
const result = await deployed.someFunction(5);
// Do something with the result or continue with more transactions.

合约事件监听

合约的方法和事件具有EventEmitter接口,因此可以像下面这样配置 监听句柄:

const example = await artifacts.require("Example").deployed();

example
  .setValue(45)
  .on('transactionHash', hash => {})
  .on('receipt', receipt => {})
  .on('error', error => {})
  .on('confirmation', (num, receipt) => {})
  .then(receipt => {});

example
  .ExampleEvent()
  .on('data', event => ... etc ... )

example
  .ExampleEvent()
  .once('data', event => ... etc ... )

合约抽象API

合约抽象有两组API,一个是静态合约抽象API,另一个是合约实例API。合约抽象 API适用于所有的合约,例如MyContract.at(),而合约实例API则对应于区块链 上合约的特定部署。

MyContract.new - 部署新合约

MyContract.new()在网络上部署合约的新实例。

方法原型

MyContract.new([arg1, arg2, ...], [tx params])
  • arg1,arg2,...:对应与合约的构造函数的参数列表,必须
  • tx params:交易参数,可选,指定交易的发起账号、gas上限和gas价格等

返回结果

MyContract.new()方法返回一个Promise对象,其解析值为新部署的合约实例。

MyContract.at - 载入已部署合约

MyContract.at()方法载入部署在指定地址的合约实例。

方法原型

MyContract.at(address)
  • address:合约部署地址

返回结果

MyContract.at()方法返回一个thenable对象,其解析值为部署在指定地址的合约实例。

MyContract.deployed - 获取默认的部署合约

MyContract.deployed()方法使用项目内部保存的合约部署地址创建一个合约实例。

方法原型

MyContract.deployed()

返回结果

MyContract.deployed()方法返回一个thenable对象,其解析值为已部署合约实例。

MyContract.link()方法链接一个合约库。

方法原型

原型1:

MyContract.link(instance)
  • instance:要连接的合约的抽象对象实例 原型2:
MyContract.link(name, address)
  • name:要链接的合约库名称
  • address:要连接的合约库地址 原型3:
MyContract.link(object)
  • object:链接目标的描述对象,键为库名,值为地址

MyContract.networks - 获取网络列表

MyContract.networks()方法获取合约抽象已配置网络清单。

方法原型

MyContract.networks()

返回结果

返回网络清单

MyContract.setProvider

MyContract.setProvider()方法设置合约抽象执行交易的web3提供器。

方法原型

MyContract.setProvider(provider)

返回结果

MyContract.setNetwork - 设置网络

MyContract.setNetwork() 方法设置合约当前表征的网络。

方法原型

MyContract.setNetwork(network_id)

返回结果

MyContract.hasNetwork - 检测特定网络

MyContract.hasNetwork()方法用来检测该合约抽象是否配置为表征指定的网络。

方法原型

MyContract.hasNetwork(network_id)

返回结果

MyContract.hasNetwork()方法返回一个布尔值,保证该合约抽象是否配置为 表征指定的网络。

MyContract.defaults - 合约实例默认值

MyContract.defaults()方法获取或设置该合约抽象创建的所有实例的默认值。

方法原型

MyContract.defaults([new_defaults])

new_defaults:要设置的默认值

返回结果

如果无参数调用,则返回当前使用的默认值。 如果调用时传入一个对象,那么使用这个对象设置默认值。

示例代码

MyContract.defaults({
  from: ...,
  gas: ...,
  gasPrice: ...,
  value: ...
})

MyContract.clone - 克隆合约

MyContract.clone()方法克隆合约抽象来获得另一个对象,管理同样的 合约构件,但是用不同的网络ID。如果要在不同的网络管理同一个合约, 使用这个方法很有帮助。

方法原型

MyContract.clone(network_id)

返回结果

返回克隆后的对象。

示例代码

const MyOtherContract = MyContract.clone(1337);

MyContract.numberFormat - 数值格式

MyContract.numberFormat属性用来设置合约抽象的方法返回值的数值格式。 默认行为是返回BN对象。可选类型:BigNumber、BN、string。

属性原型

MyContract.numberFormat = number_type

示例代码

// Choices are:  `["BigNumber", "BN", "String"].
const Example = artifacts.require('Example');
Example.numberFormat = 'BigNumber';

MyContract.timeout - 设置交易超时区块数

MyContract.timeout()方法用来设置交易的超时参数。 从该合约抽象创建的实例将具有指定的交易区块超时,这意味着 如果交易不能立即进入区块,将持续尝试指定数量的区块。

方法原型

MyContract.timeout(block_timeout)

返回结果

MyContract.autoGas - 是否自动估算gas

MyContract.autoGas属性用来声明是否自动估算gas。如果设置为true,那么 从该合约抽象创建的实例将使用web3.eth.estimateGas来估算交易gas消耗。

MyContract.autoGas属性的默认值为true。

属性原型

MyContract.autoGas = <boolean>

MyContract.gasMultiplier - gas估算倍数

MyContract.gasMultiplier() 方法用于设置gas倍乘数,该数值与 autoGas属性值一起决定最终的交易gas用量。默认值为1.25。

方法原型

MyContract.gasMultiplier(gas_multiplier)
全部评论(0)
给作者留言