TIP-544: Add `data` to the http interfaces interacting with smart contract

[yanghang8612]

tip: 544
title: Add `data` to the http interfaces interacting with smart contract
author: yanghang8612@163.com
status: Last Call
type: Standards Track
category: Interface
created: 2023-05-15

Simple Summary

This TIP is designed to optimize the http interfaces interacting with smart contract in order to make them more user-friendly.

Abstract

The http interfaces interacting with smart contract must pass the function_selector and parameters fields, the user cannot interact with smart contracts by passing data directly.

Meanwhile it is not possible to estimate the energy consumption for creating smart contract transactions through the http interfaces.

Specifications

wallet/triggersmartcontract

User can call this API to read/write the smart contract.

Params:

1. owner_address - Required. Account address.
2. contract_address - Required. Contract address.
3. call_value - Optional. The amount of TRX transferred into the contract.
4. call_token_value - Optional. The amount of TRC-10 transferred into the contract.
5. token_id - Optional. The token id of TRC-10 transferred into the contract.
6. function_selector - Optional (Used to be required). The signature of the function (like transfer(address,uint256)).
7. parameter - Optional. Parameter encoding needs to be in accordance with the ABI rules.
8. New! data: Optional. The data passed along with a transaction that allows us to interact with smart contracts.
9. fee_limit - Required. Maximum TRX consumption, measured in SUN.
10. permission_id - Optional. For multi-signature transactions.
11. visible - Optional. Whehter the address is in BASE58 format.

Returns: unsigned transaction, data type is JSON string.

Example:

curl --request POST \
     --url https://api.shasta.trongrid.io/wallet/triggersmartcontract \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "owner_address": "TZ4UXDV5ZhNW7fb2AMSbgfAEZ7hWsnYS2g",
  "contract_address": "TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs",
  "function_selector": "balanceOf(address)",
  "parameter": "000000000000000000000000a614f803b6fd780986a42c78ec9c7f77e6ded13c",
  "visible": true
}
'

or

curl --request POST \
     --url https://api.shasta.trongrid.io/wallet/triggersmartcontract \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "owner_address": "TZ4UXDV5ZhNW7fb2AMSbgfAEZ7hWsnYS2g",
  "contract_address": "TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs",
  "data": "70a08231000000000000000000000000a614f803b6fd780986a42c78ec9c7f77e6ded13c",
  "visible": true
}
'

wallet/triggerconstantcontract

User can call this API to read or simulate writing the smart contract.

Params:

1. owner_address - Same as wallet/triggersmartcontract.
2. contract_address - Optional (Used to be required). If this parameter is not empty, then it means that the user wants to interact with the smart contract. Otherwise, it means that the user is trying to deploy a smart contract using data.
3. call_value - Same as wallet/triggersmartcontract.
4. call_token_value - Same as wallet/triggersmartcontract.
5. token_id - Same as wallet/triggersmartcontract.
6. function_selector - Optional (Used to be required). Same as wallet/triggersmartcontract.
7. parameter - Same as wallet/triggersmartcontract.
8. New! data: Optional. The data passed along with a transaction that allows us to interact with smart contracts.
9. visible - Same as wallet/triggersmartcontract.

Returns:

1. result - Run result.
2. energy_used - Energy consumed during execution.
3. constant_result - Result list of tiggered functions.
4. transaction - Transaction information.

wallet/estimateenergy

User can call this API to estimate the energy consumption of smart contract transactions.

Params:

Same as wallet/triggerconstantcontract

Returns:

1. result - Run result.
2. energy_required - Energy consumption.

Backwards Compatibility

None.

Security Considerations

None.

[ExOCeo]

Finally, funciont_selector can be skipped. So if implemented, only call_data is needed to call the contract through HTTP interface?

[yanghang8612]

The energy consumption of deploying a smart contract on shasta testnet equals that on mainnet right? Previously, I use this method to estimate.

Yes, the Shasta testnet and the Mainnet currently consume exactly the same amount of energy when deploying contracts with the same code.

[yanghang8612]

Finally, funciont_selector can be skipped. So if implemented, only call_data is needed to call the contract through HTTP interface?

Yes, if the contract is called by passing call_data, then the parameter will also not need to be passed.

[jernganl]

Finally, we can estimate the energy consumption by calling smart contracts. Is the estimate accurate?

[souppopnix]

Is there any update, looking forward to this.

If I'm not mistaken, we can pass the call data only and emit the function_selector when calling a smart contract. In this way, somehow we can estimate the energy to be consumed based on that call data?

[Bellgin]

So once call data is passed, function selector and other params would be ignored? It is a decent way to resolve the issue in HTTP.

[yanghang8612]

Finally, we can estimate the energy consumption by calling smart contracts. Is the estimate accurate?

After GreatVoyage-v4.7.0.1(Aristotle), you can use /wallet/estimateenergy to estimate the more accurate energy consumption.

[yanghang8612]

Is there any update, looking forward to this.

If I'm not mistaken, we can pass the call data only and emit the function_selector when calling a smart contract. In this way, somehow we can estimate the energy to be consumed based on that call data?

Yes, passing call_data or function_selector&parameter is fine.

If you want to estimate energy consumption, you can use /wallet/estimateenergy instead of /wallet/triggerconstantcontract.

[yanghang8612]

So once call data is passed, function selector and other params would be ignored? It is a decent way to resolve the issue in HTTP.

Yes, that would be more user-friendly, especially for Ethereum-based developers.

[yanghang8612]

Close this issue as it is implemented by GreatVoyage-v4.7.2. Check TIP detail at TIP-544 Check implementation PR at https://github.com/tronprotocol/java-tron/pull/5079

Note: We use data instead of call_data in implementation.