语法指南 | 发明者量化

exchange.IO("api", ...)

在Web3交易所对象上调用智能合约方法：只读方法返回解码后的值，写方法则签名并广播交易。


    
    
    
exchange.IO(k, address, method)


    
    
    
exchange.IO(k, address, method, ...args)


    
    
    
exchange.IO(k, address, method, value, ...args)


    
    
    
exchange.IO(k, address, method, ...args, options)

示例

decimals方法是ERC20的一个constant方法，调用时不消耗gas，用于查询指定token的精度。
decimals方法无参数。返回值：token的精度。


    javascript
    
    
function main(){
    var tokenAddress = "0x111111111117dC0aa78b770fA6A738034120C302"    // 代币的合约地址，示例中的代币为1INCH
    Log(exchange.IO("api", tokenAddress, "decimals"))
    // 输出：18（1INCH代币的精度）
}

allowance方法是ERC20的一个constant方法，调用时不消耗gas，用于查询指定token对某个合约地址的授权额度。
allowance方法需要传入2个参数：第一个参数为钱包地址，第二个参数为被授权的地址。返回值：token的授权额度。
owner：钱包地址，示例中以字符串"owner"代替，实际使用时需填写具体地址。
spender：被授权的合约地址，示例中以字符串"spender"代替，实际使用时需填写具体地址，例如Uniswap V3 router v1的地址。
```
    javascript
    
    
function main(){
    // 代币的合约地址，示例中的代币为1INCH
    var tokenAddress = "0x111111111117dC0aa78b770fA6A738034120C302"

    // 例如查询结果为1000000000000000000，除以该token的精度单位1e18，即当前交易所对象绑定的钱包已向spender地址授权了1个1INCH
    Log(exchange.IO("api", tokenAddress, "allowance", "owner", "spender"))
}
```
approve方法是ERC20的一个非constant方法，调用时会消耗gas，用于向指定合约地址授权token的操作额度。
approve方法需要传入2个参数：第一个参数为被授权的地址，第二个参数为授权额度。返回值：txid。
spender：被授权的合约地址，示例中以字符串"spender"代替，实际使用时需填写具体地址，例如Uniswap V3 router v1的地址。
0xde0b6b3a7640000：授权数量，此处以十六进制字符串表示，对应的十进制数值为1e18，除以示例中token的精度单位（即1e18），即授权了1个token。
exchange.IO()函数的第三个参数传入方法名approve，也可以使用methodId形式，例如："0x095ea7b3"；还可以使用完整的标准方法签名，例如："approve(address,uint256)"。
```
    javascript
    
    
function main(){
    // 代币的合约地址，示例中的代币为1INCH
    var tokenAddress = "0x111111111117dC0aa78b770fA6A738034120C302"

    // 授权量的十六进制字符串: 0xde0b6b3a7640000 , 对应的十进制数值: 1e18 , 1e18除以该token的精度单位即为1个代币 , 因此这里表示授权1个代币
    Log(exchange.IO("api", tokenAddress, "approve", "spender", "0xde0b6b3a7640000"))
}
```
multicall方法是Uniswap V3中的一个非constant方法，调用时会消耗gas，用于多路径兑换代币。
multicall方法可能有多种传参方式，具体可查询包含该方法的ABI，调用前需要先注册ABI。返回值：txid。
在Uniswap、PancakeSwap上兑换时，可直接使用Uniswap、PancakeSwap交易所对象，无需自行编码调用。

以下使用伪代码说明部分细节：
```
            javascript
            
            
exchange.IO("api", ContractV3SwapRouterV2, "multicall(uint256,bytes[])", value, deadline, data)
```
ContractV3SwapRouterV2：Uniswap V3的router v2合约地址。
value：随交易附带的原生币数量，单位为wei（链上整数，可使用exchange.IO("toUnits", "0.01", 18)换算）；当兑换的tokenIn代币不是ETH时，设置为0。
deadline：deadline是multicall方法的参数，可设置为(new Date().getTime() / 1000) + 3600，表示交易在一小时内有效。
data：data是multicall方法的参数，类型为bytes[]，即由各个待执行操作的调用数据（以0x开头的十六进制字符串）组成的数组。与exchange.IO("api", "eth", "send", "toAddress", toAmount)类似，调用multicall方法时也可以指定本次调用的gasLimit/gasPrice/nonce，同样以伪代码说明：
```
            javascript
            
            
exchange.IO("api", ContractV3SwapRouterV2, "multicall(uint256,bytes[])", value, deadline, data, {gasPrice: 123456, gasLimit: 300000})
```
可根据实际需求设置{gasPrice: 11, gasLimit: 111, nonce: 111}参数，该参数作为exchange.IO()函数的最后一个参数传入。
可以省略其中的nonce，使用系统默认值；也可以不设置gasLimit/gasPrice/nonce，全部使用系统默认值。

在该参数中设置dryRun: true时，只签名不广播，返回包含hash、raw（签名后的交易）等字段的对象。如需预先确认调用能否成功，可将api替换为call，使用exchange.IO("call", ...)模拟执行（不签名、不消耗gas），详见exchange.IO("call", ...)。
```
    javascript
    
    
function main() {
    var ContractV3SwapRouterV2 = "0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45"
    // multicall(uint256,bytes[])不是ERC20方法，需要先注册ABI，这里使用内置模板
    exchange.IO("abi", ContractV3SwapRouterV2, "uniswapV3SwapRouter02")
    var tokenInName = "ETH"
    // 将 0.01 ETH 换算为 wei：payable 方法的 value 为链上整数
    var amountIn = exchange.IO("toUnits", "0.01", 18)
    var options = {gasPrice: 5000000000, gasLimit: 300000, nonce: 100}   // 此处仅为示例，请根据实际场景设置
    // bytes[]：各个操作编码后的调用数据（以 0x 开头的十六进制字符串），此处为空数组，请根据实际场景设置
    var data = []
    var tx = exchange.IO("api", ContractV3SwapRouterV2, "multicall(uint256,bytes[])",
        (tokenInName == 'ETH' ? amountIn : 0), (new Date().getTime() / 1000) + 3600, data,
        options || {})
}
```

返回值

类型	描述
string / number / bool / object / array	只读方法返回解码后的值，写方法返回交易哈希（设置`dryRun`时返回签名后的交易对象）；调用失败时返回空值，可通过`GetLastError()`获取错误信息。返回值的类型及`dryRun`返回的字段详见备注。

参数

名称	类型	必填	描述
k	string	是	固定为`api`，用于发起扩展调用请求。
address	string	是	智能合约地址。
method	string	是	要调用的智能合约方法。
value	number / string	否	调用时附带的原生币数量（链上整数单位，以太坊为wei，波场为sun）。仅当方法的`stateMutability`为`payable`时才需要传入，且须放在方法参数之前；`exchange.IO()`函数根据已注册ABI中的`stateMutability`判断是否需要该参数，`nonpayable`、`view`等方法无需传入`value`参数。`stateMutability`属性可在ABI中查看。
arg	string / number / bool / any	否	要调用的智能合约方法的参数。 `arg`参数可以有多个，`arg`参数的类型与个数取决于所调用的智能合约方法。
options	object	否	发送交易的选项，仅对写方法有效，作为最后一个参数传入（参数个数比方法参数多一个时，最后一个参数被识别为选项）：`gasLimit`为gas上限，未设置时由节点估算（`eth_estimateGas`）；`gasPrice`为gas价格，设置后发送传统（legacy）交易；`nonce`用于指定nonce，未设置时自动分配；`dryRun`为`true`时只签名、不广播。波场（TRON）仅支持`gasLimit`，表示手续费上限feeLimit（单位为sun）。

参考

Web3 exchange.IO exchange.IO("abi") exchange.IO("call") exchange.IO("multicall") exchange.IO("waitReceipt")

备注

只读方法通过eth_call在最新区块上执行，不签名，也不消耗gas。

写方法使用配置的私钥签名后广播。未设置gasPrice时，支持EIP-1559的链发送EIP-1559（type 2）交易：小费取节点建议值（eth_maxPriorityFeePerGas）与最近20个区块实际小费中位数（eth_feeHistory）中的较大者，最高费用为2 × baseFee + 小费；不支持EIP-1559的链则按节点返回的eth_gasPrice出价。

未设置nonce时自动分配，并与链上待处理交易计数保持同步，连续发送不会重复使用nonce，参见exchange.IO("nonce", ...)。交易发送后可使用exchange.IO("waitReceipt", ...)等待上链；长时间未上链时，可使用exchange.IO("speedUp", ...)加价重发，或使用exchange.IO("cancelTx", ...)取消交易。

声明为nonpayable的询价方法（如Uniswap QuoterV2）会被视为写方法，进行签名并发送交易。若只想获取返回值或预演写操作，请使用exchange.IO("call", ...)模拟执行。

调用只读方法（view、pure）时返回解码后的值：只有一个返回值时直接返回该值；有多个返回值时返回以输出参数名为键的对象，未命名的输出依次命名为ret0、ret1……。uint64及以下位宽的整数返回数字，更大的整数返回十进制字符串（在JavaScript、Python中，绝对值不小于2^53的整数也返回十进制字符串，以避免精度丢失）；address返回以0x开头的小写地址（波场为以T开头的地址）；bytes返回不带0x前缀的十六进制字符串；bytes32等定长bytesN返回字节数值数组（例如[17, 17, ...]）。

调用写方法时返回交易哈希（以太坊为以0x开头的字符串，波场为不带0x前缀的交易ID）；设置dryRun时返回包含hash、raw（签名后的交易）、from、to、value、data、nonce、gasLimit、chainId、type、gasPrice、maxFeePerGas、maxPriorityFeePerGas的对象。调用失败时返回空值，可通过GetLastError()获取错误信息。