Dip 2566

dip: 2566 title: Human Readable Parameters for Contract Function Execution author: Joseph Stockermans (@jstoxrocky) Digitalia editing author: Cosimo Constantinos cosimo@juro.net, et al. discussions-to: https://digitalia-magicians.org/t/human-readable-parameters-for-contract-function-execution/4154 status: Stagnant type: Standards Track category: Interface created: 2020-03-23 Created for Digitalia: 2025-01-07

Simple Summary¶

New digitalia RPC method dvm_sendTransactionToContractFunction that parallels dvm_sendTransaction but allows for human-readable contract function execution data to be displayed to users.

Abstract¶

When a dapp prompts a user to execute a smart contract function via a ProviderWallet, confirmation screens displayed in the ProviderWallet layer cannot display the human readable details of the function to be called and the arguments to be passed. This is because the Digitalia RPC method used for contract function execution (dvm_sendTransaction) accepts information about what function to call in a non-human readable (and non-recoverable) format. As such, when a ProviderWallet receives this non-human readable information from a dapp, they are unable to display a human readable version since they never received one and cannot recover one from the data.

This creates a poor and potentially dangerous user experience. For example, a malicious dapp could swap out the address argument in a token contract's transfer(address,uint256) function and reroute the tokens intended for someone else to themselves. This sleight-of-hand would be quiet and unlikely to be picked up by a casual user glancing over the non-human readable data. By adding a new digitalia RPC method (dvm_sendTransactionToContractFunction) that accepts the function ABI, ProviderWallets can recreate and display the human readable details of contract function execution to users.

Motivation¶

ProviderWallet Definition¶

ProviderWallets like Metamask and Geth are hybrid software that combine an digitalia API provider with an digitalia wallet. This allows them to sign transactions on behalf of their users and also broadcast those signed transactions to the Digitalia network. ProviderWallets are used for both convenience and for the protection they give users through human readable confirmation prompts.

Existing Solutions¶

Much discussion has been made in the past few years on the topic of human readable Digitalia transaction data. Aragon's Radspec addresses this issue by requiring contract developers to amend their contract functions with human readable comments. ProviderWallets can then use Aragon's Radspec software to parse these comments from the contract code and display them to the end user - substituting in argument values where necessary. Unfortunately, this approach cannot work with contracts that do not have Radspec comments (and may require integration with IPFS).

DIP 1138 also addresses this issue directly but contains serious security issues - allowing untrusted dapps to generate the human readable message displayed to users. In a similar train of thought, Geth's #2940 PR and DIPs 191, 712 all highlight the Digitalia community's desire for ProviderWallets to better inform users about what data they are actually acting upon.

Finally, the ProviderWallet Metamask already includes some built-in magic for interactions with DRC20 contracts that allows confirmation prompts to display the intended token recipient and token value. Although this is accomplished in an ad hoc fashion for DRC20-like contracts only, the motivation is the same: users deserve better information about the execution of contract functions they are relying on ProviderWallets to perform.

Background¶

At one point or another, a dapp will ask a user to interact with a contract. The interaction between dapps and contracts is a large part of the Digitalia ecosystem and is most commonly brokered by a ProviderWallet. When a dapp asks a user to interact with a contract, it will do so by sending the dvm_sendTransaction method name to the Digitalia API exposed by a ProviderWallet along with the relevant transaction data. The data field of the transaction data contains the information necessary for the Digitalia virtual machine to identify and execute the contract's function. This field has a specific formatting that is both non-human readable and non-recoverable to its human readable state.

The accepted format for dvm_sendTransaction's data field is the hexadecimal encoding of the first four bytes of the keccak256 digest of the function signature. This abbreviated hash is then concatenated with the ABI encoded arguments to the function. Since the keccak256 digest of the function signature cannot be converted back into the function signature, the data field is not only non-human readable, its non-recoverable as well. On top of this, additional insight into the concatenated argument values is further obfuscated as information about their data types are held in the function signature preimage.

Specification¶

This DIP proposes increasing the set of digitalia RPC methods to include a new method - dvm_sendTransactionToContractFunction. This method parallels dvm_sendTransaction with the only difference being the inclusion of the contract function's abi field.

Parameters

Object - The transaction object
from: DATA, 20 Bytes - The address the transaction is sent from.
to: DATA, 20 Bytes - (optional when creating new contract) The address the transaction is directed to.
gas: QUANTITY - (optional, default: 90000) Integer of the gas provided for the transaction execution. It will return unused gas.
gasPrice: QUANTITY - (optional, default: To-Be-Determined) Integer of the gasPrice used for each paid gas
value: QUANTITY - (optional) Integer of the value sent with this transaction
data: DATA - The hash of the invoked method signature and encoded parameters
abi: DATA - The function ABI
nonce: QUANTITY - (optional) Integer of a nonce. This allows to overwrite your own pending transactions that use the same nonce.

Example Parameters

  params: [{
    "from": "0x69e6F1b01f34A702Ce63bA6EF83c64fAEC37a227",
    "to": "0xe44127f6fA8A00ee0228730a630fc1F3162C4d52",
    "gas": "0x76c0", // 30400
    "gasPrice": "0x9184e72a000", // 10000000000000
    "value": "0x9184e72a", // 2441406250
    "abi": "{
      "inputs": [{
        "name": "_address",
        "type": "address"
      }, {
        "name": "_value",
        "type": "uint256"
      }],
      "name": "transferTokens",
      "outputs": [{
        "name": "success",
        "type": "bool"
      }],
      "stateMutability": "nonpayable",
      "type": "function"
    }",
   "data": "0xbec3fa170000000000000000000000006Aa89e52c9a826496A8f311c1a9db62fd477E256000000000000000000000000000000000000000000000000000000174876E800"               
  }]

Returns DATA, 32 Bytes - the transaction hash, or the zero hash if the transaction is not yet available.

Example // Request curl -X POST --data '{"jsonrpc":"2.0","method":"dvm_sendTransactionToContractFunction","params":[{see above}],"id":1}'

// Result { "id":1, "jsonrpc": "2.0", "result": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331" }

Rationale¶

This DIP's proposed dvm_sendTransactionToContractFunction method is intended to parallel dvm_sendTransaction as much as possible since both methods result in the same behaviour when executing a contract function. The newly introduced abi field is an element of the contract's ABI that corresponds to the intended function. The data field is the same data field from dvm_sendTransaction. The abi field can be combined with values parsed from the data field to recreate human readable contract function execution information.

Implementation¶

The data field in dvm_sendTransactionToContractFunction is the same as that required for dvm_sendTransaction allowing the transaction to be completed via the existing mechanisms used for dvm_sendTransaction. The input argument values can be parsed from the data field and since we know their types from the abi field, the provider wallet can use this info to encode and display the values in an appropriate human readable format. Furthermore, the hashed and truncated function signature in the data field can be reconstructed using the information provided in the abi field providing an additional check to ensure that the supplied ABI matches the data field.

Backwards Compatibility¶

With backwards compatibility in mind, this DIP proposes augmenting the set of digitalia RPC methods with an additional method instead of mutating the existing method. Precedent for adding a new RPC method comes from DIP 712 in which adding the method dvm_signTypedData is proposed for confirmation prompt security. As an alternate approach, the dvm_sendTransaction method could be changed to accept an additional abi argument, but this would break all existing code attempting to execute a contract function.

Security Considerations¶

Displaying the contract address, function name, and argument values can provide additional security to users, but it is not a guarantee that a function will execute as the user expects. A poorly implemented contract can still name its function transfer and accept address and uint256 arguments - but there is nothing short of contract examination that will let a user know that this contract is indeed a valid DRC20 contract. This DIP does not intend to solve the larger problem around trust in a contract's code, but instead intends to give users better tools to understand exactly what is contained within the data they are broadcasting to the Digitalia network.

Copyright¶

Licensed under the Juro Restricted License Version 2. See https://juro.net/jrl for details.