Contract Transaction Previews

[mshakeg]

Background

It would be helpful for users to gain visibility into a contract transaction before signing it to validate its correctness and potential effects, particularly when working with complex smart contracts that may execute HTS actions such as transfers and approvals. AFAIK there's no standard way of doing this on Ethereum, however, a few 3rd party node providers have developed services for simulating/previewing a transaction such as Alchemy and Blocknative[1] [2]. Aptos is a non-EVM chain that supports transaction simulation with detailed insights into effects[3].

HIP-584 adds an EVM module to the mirror node which allows for the transient execution of EVM transactions to facilitate gas estimates and static EVM calls exposed by the eth_estimateGas and eth_call json rpc methods respectively. However, while eth_estimateGas and eth_call return some information about transactions, such as the gas_used and call_result (or error_message in the case of a revert), neither method returns the event logs which if set up correctly can be used to gain greater insight into a transaction.

Proposal

The mirror node should expose a /api/v1/contracts/simulate endpoint that accepts the same request body as the /api/v1/contracts/call endpoint proposed in HIP-584, however, adds an additional simulationType field that could be either of the following 4 values:

1. simulateAssetChanges - Simulates a transaction and returns a list of HTS asset changes. The return data is in a standard predefined format and unlike the following simulateExecution type does NOT require the contract ABI to decode.
2. simulateExecution - Simulates a transaction and returns the same data as /api/v1/contracts/results/{transactionIdOrHash}; most importantly the call_result, error_message(in the case of a revert), logs and the result.
3. simulateAssetChangesBundle - Similar to simulateAssetChanges however simulates multiple transactions sequentially and returns a list of HTS asset changes.
4. simulateExecutionBundle - Similar to simulateExecution however simulates multiple transactions sequentially.

The Hedera JSON RPC Relay can expose the following 4 corresponding methods(with identical request schema to eth_call):

1. hedera_simulateAssetChanges
2. hedera_simulateExecution
3. hedera_simulateAssetChangesBundle
4. hedera_simulateExecutionBundle

Methods 3 and 4 will probably be more useful to developers and researchers than the typical user who'll likely only be executing a single transaction at a time at the "latest" blockTag. If a user wishes to gain insight into a transaction pre-signing wallets should allow a user to globally turn on contract transaction previews or whitelist contracts and toggle on the transaction preview functionality on a per contract basis since request simulations will take some time to fetch. Additionally, when whitelisting a contract wallets should request an ABI that is a union of all ABIs for contracts that could be called by the contract that is being whitelisted, since in order for the results of simulateExecution calls to be decoded and displayed to the user not only will the function inputs for the whitelisted contract have to be decoded but also events and errors that could occur at any call depth beyond the whitelisted contract.

Conclusion

The addition of these four simulation methods would greatly improve the ability of developers and users to test and validate the correctness and potential effects of transactions before submitting them to the Hedera network. This would help reduce issues arising from signing transactions that result in the loss of funds due to users unknowingly signing malicious transactions or potentially due to a bug in the contract.

In order for end users to benefit from this wallets will have to integrate this functionality and display the simulation results in a user-friendly format and highlight any potential issues or errors. Additionally, allowing users to adjust transaction details(i.e. the inputs to the function) and to re-simulate transactions until they are satisfied with the potential outcome can improve the overall user experience of the wallet.

References

1. Alchemy Transaction Simulation Docs
2. Blocknative Transaction Preview Docs
3. Aptos Docs - Testing transactions or transaction pre-execution

[mgarbs]

Thanks for starting this discussion @mshakeg, I really like this idea and feel it could benefit our users a great deal. I have a few questions about this so we can flesh out this proposal a bit more.

Can you give a scenario of a simulation and how it gets implemented in the in the /api/v1/contracts/simulate endpoint? It would be nice if the example showed HTS transfers and perhaps some associations since those are unique to us. This will help expand the specification for implementation. In the same vein of thinking, what would the expected format be for the response data for each of the simulation types?

Here's another train of thought here: will the simulation methods be available for all types of smart contracts including those developed outside the Hedera ecosystem? What I mean by that is, could we simulate bridging transactions? We aren't integrated with Axelar, but thinking forward to when it will be common to see cross-chain swaps and that sort of thing, how would we simulate those types of transactions?

I would imagine this will increase the usage of our community service rpc relay Hashio, and we may need to think about how this would affect our current throttle. Thank you again for bringing up this discussion. We have a hip template in the root of this repository. If you fork this repo and use that template to fill out the details of this discussion and make a PR, we can start moving this discussion formally as a hip if you like.

@Nana-EC what are your thoughts as to how we can flesh this out with a specification?

[mshakeg]

Thanks for the questions @mgarbs , I'll try to address them below.

Can you give a scenario of a simulation and how it gets implemented in the /api/v1/contracts/simulate endpoint?

I think I've already addressed both questions in the initial proposal:

how it gets implemented in the /api/v1/contracts/simulate endpoint?

HIP-584 adds an EVM module to the mirror node which allows for the transient execution of EVM transactions ...

So whereas HIP-584's /api/v1/contracts/call POST REST API endpoint is used for gas estimation or static calls typically accessed via the eth_estimateGas and eth_call json rpc methods and discards all event logs the /api/v1/contracts/simulate endpoint will return all logs in addition to a gas estimate and static call return value.

Can you give a scenario of a simulation?

1. A user connects their wallet to a dApp interface
2. User requests to sign a transaction in their connected wallet from the dApp ui
3. The wallet detects that the transaction is "to" a whitelisted contract and requests a simulation to either the mirror node directly or via the json rpc relay with the request body using the same request format as the 4 Alchemy methods and expecting the same response format as those Alchemy methods. I've specified the request and response formats below:

Mirror node request body for single and bundle requests(similar structure to /api/v1/contracts/call):

{ // single
  "type": "{singleSimulationType}"
  "block": "latest", 
  "data": "0x...",
  "estimate": true,
  "from": "0x...", 
  "gas": 100000000, 
  "gas_price": "0x...",
  "to": "0x...", 
  "value": "0x..."
}

{ // bundle
  "type": "{bundleSimulationType}",
  [
    "block": "latest", 
    "data": "0x...",
    "estimate": true,
    "from": "0x...", 
    "gas": 100000000, 
    "gas_price": "0x...",
    "to": "0x...", 
    "value": "0x..."  
  ]
}

JSON RPC request body for single and bundle requests(similar structure to eth_call):

{ // single
  "method": "hedera_{singleSimulationType}",
  "params": [
    {
      "data": "0x...",
      "from": "0x...",
      "gas": 100000000,
      "gasPrice": "0x...",
      "to": "0x...",
      "value": "0x..."
    },
    "latest"
  ],
  "id": 1,
  "jsonrpc": "2.0"
}

{ // bundle
  "method": "hedera_{singleSimulationType}",
  "params": [
    [
      {
        "data": "0x...",
        "from": "0x...",
        "gas": 100000000,
        "gasPrice": "0x...",
        "to": "0x...",
        "value": "0x..."
      }
    ],
    "latest"
  ],
  "id": 1,
  "jsonrpc": "2.0"
}

JSON RPC response formats for all 4 methods:

Response format for simulateAssetChanges:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "changes": [
      {
        "assetType": "{assetType}",
        "changeType": "{changeType}",
        "from": "0x...",
        "to": "0x...",
        "rawAmount": "1000000",
        "contractAddress": "0x...",
        "tokenId": null,
        "decimals": 6,
        "symbol": "{symbol}",
        "name": "{name}",
        "logo": "{logoUrl}",
        "amount": "1" // since this token has 6 decimals the "rawAmount" of "1000000" gives an "amount" of "1"
      }
    ],
    "gasUsed": "0x6925",
    "error": null
  }
}

Response format for simulateAssetChangesBundle:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "changes": [
        {
          "assetType": "{assetType}",
          "changeType": "{changeType}",
          "from": "0x...",
          "to": "0x...",
          "rawAmount": "1000000",
          "contractAddress": "0x...",
          "tokenId": null,
          "decimals": 6,
          "symbol": "{symbol}",
          "name": "{name}",
          "logo": "logoUrl",
          "amount": "1"
        }
      ],
      "gasUsed": "0x6925",
      "error": null
    }
  ]
}

Response format for simulateExecution:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "calls": [
      {
        "type": "{callType}",
        "from": "0x...",
        "to": "0x...",
        "value": "0x...",
        "gas": "0x...",
        "gasUsed": "0x...",
        "input": "0x...",
        "output": "0x..."
      }
    ],
    "logs": [
      {
        "address": "0x...",
        "data": "0x...",
        "topics": [
          "0x...",
          "0x...",
          "0x..."
        ]
      }
    ]
  }
}

Response format for simulateExecutionBundle:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "calls": [
        {
          "type": "CALL",
          "from": "0x...",
          "to": "0x...",
          "value": "0x...",
          "gas": "0x...",
          "gasUsed": "0x...",
          "input": "0x...",
          "output": "0x..."
        }
      ],
      "logs": [
        {
          "address": "0x...",
          "data": "0x...",
          "topics": [
            "0x...",
            "0x...",
            "0x..."
          ]
        }
      ]
    }
  ]
}

Where:
simulationType = singleSimulationType | bundleSimulationType
singleSimulationType = "simulateAssetChanges" | "simulateExecution" and
bundleSimulationType = "simulateAssetChangesBundle" | "simulateExecutionBundle"

and
assetType = "NATIVE" | "ERC20" | "ERC721" | "ERC1155" | "FungibleHTS" | "NFTHTS"

and
changeType = "APPROVAL" | "TRANSFER" | "MINT" | "BURN" | "ASSOCIATE" | "DISSOCIATE"; obviously the ASSOCIATE and DISSOCIATE changeTypes will only be relevant to the FungibleHTS and NFTHTS assetTypes.

and callType = "CALL" | "DELEGATECALL". Note the initial call(i.e. result.calls[0]) from the EOA(i.e. "from") to the contract(i.e. "to") will always be of type CALL(sinceDELEGATECALL directly from the EOA is not possible); however, calls at non-zero call depth could be of either callType. Also, note that Alchemy includes a decoded field in each call of calls but ONLY if it is able to determine the contract's ABI from an authority such as Etherscan. Hashscan currently does not support verified contracts so this won't be possible on Hedera at this point, but if this ever gets implemented then the decoded field can be introduced, until then wallets will have to request a complete ABI that is a union of all ABIs for contracts that could be called at any depth as described in the initial proposal to be able to decode all calls and logs at any call depth.

The mirror node endpoint can return the response in the same format(as the json rpc relay) such that the relay can simply return the response it receives from the mirror node directly to the consumer.

4. If the user is happy with the preview(decoded inputs, logs, return value, gas, etc) they can sign the transaction in the wallet, if not they can cancel or alternatively if the wallet supports easy/user-friendly adjustments to the inputs and re-simulation that could be done too.

---

Here's another train of thought here: will the simulation methods be available for all types of smart contracts including those developed outside the Hedera ecosystem? What I mean by that is, could we simulate bridging transactions? We aren't integrated with Axelar, but thinking forward to when it will be common to see cross-chain swaps and that sort of thing, how would we simulate those types of transactions?

You'd only be able to simulate transactions to the extent that they are executed on Hedera, and provided the bridge contract's events are set up adequately this will provide sufficient insight to users into the bridging transaction. For example, a user wants to bridge x amount of token y to chain z to recipient a, a suitable event for this could be PortToken(address tokenOut, uint amount, address recipient, uint chainId). The wallet will decode the simulated transaction's logs and the user will be able to preview this PortToken event.

---

I would imagine this will increase the usage of our community service rpc relay Hashio, and we may need to think about how this would affect our current throttle.

Wallets can obviously integrate their own paid providers(limited to Arkhia at this point) if the rate limits of Hashio become an issue.

---

If you fork this repo and use that template to fill out the details of this discussion and make a PR, we can start moving this discussion formally as a hip if you like.

I think it's a bit too early as this idea has not yet received much attention.

[mshakeg]

Radix's Transaction Manifests appear to offer a simpler(as it doesn't require any tx simulation at the time of signing) and more secure method(as it's enforced at the network level) for achieving the same objectives as this concept, at least for the most common DeFi interactions. It seems feasible to adapt this concept for the HSCS(involving HTS interactions). As I understand it, the transaction manifest outlines conditions for asset checks, which are validated after the execution of the smart contract. If these conditions are met, the transaction is not reverted; otherwise, it is. For instance, if you wish to exchange X amount of tokenA for at least Y amount of tokenB, the transaction manifest would stipulate that your tokenA balance should decrease by no more than X and your tokenB balance should increase by at least Y following EVM execution.

[Nana-EC]

Hey @mshakeg
Reading through my understanding is you'd like to expose the logs and state changes for a simulated smart contract transaction
to inform the impacts should a user actually submit it to the network.
Is that correct?

Assuming so, I totally agree with the need and would like to see wallets and DApps highlight this to users for security reasons.
Your proposal is a unique take on so thanks for putting it together.

One consideration is does https://hips.hedera.com/hip/hip-801 using debug_traceTransaction assist you?
My guess is partially but not completely for the developer.

Will review the additional links you shared and circle back.

[mshakeg]

Hey @Nana-EC,

Thank you for your input. Regarding your suggestion of debug_traceTransaction, I believe it wouldn't quite fit the intended purpose here, as it is primarily designed for tracing already processed transactions. Perhaps you meant to refer to the trace_call method? However, even trace_call may not completely align with the requirements of this proposal.

The main objective is not to analyze every state change in depth but to focus on capturing all simulated emitted event logs. If these logs are emitted accurately and effectively, they should provide a thorough overview of all state changes. Although this can be generally beneficial, I still believe that for DeFi transactions involving HSCS and HTS, a method akin to Radix's Transaction Manifest could be a more efficient and secure alternative. As detailed in this comment, the transaction manifest offers a simpler, more secure approach. It eliminates the need for transaction simulation at the time of signing and is enforced at the network level. I may consider drafting a proposal for Hedera Smart Contract Transaction Manifests if time permits.