Described transactions

EIPS/eip-4430.md

@@ -0,0 +1,154 @@
+---
+eip: 4430
+title: Described Transactions
+description: Contract methods to compute human-readable descriptions for machine readable transaction data.
+author: Richard Moore (@ricmoo), Nick Johnson (@arachnid)
+discussions-to: https://github.com/ethereum/EIPs/issues/4431
+status: Draft
+type: Standards Track
+category: ERC
+created: 2021-11-07
+---
+
+## Simple Summary
+
+A technique for contract authors to enable wallets to provide a
+human-readable description of the effect of of a transaction with a
+given contract.
+
+
+## Abstract
+
+Use a contract method to provide *virtual funcions* which can generate
+a human-readable description at the same time as the machine-readable
+bytecode, allowing the user to agree to the human-readable component
+in a UI while the machine can execute the bytecode once accepted.
+
+
+## Motivation
+
+When using an Ethereum Wallet (e.g. MetaMask, Clef, Hardware Wallets)
+users must accept a transaction before it can be submitted (or the user
+may decline).
+
+Due to the complexity of Ethereum transactions, wallets are very limited
+in their ability to provide insight into the effects of a transaction
+that the user is approving; outside special-cased support for common
+transactions such as ERC20 transfers, this often amounts to asking the
+user to sign an opaque blob of binary data.
+
+This EIP presents a method for dapp developers to enable a more comfortable
+user experience by providing wallets with a means to generate a better
+description about what the contract claims will happen.
+
+It does not address malicious contracts which wish to lie, it only addresses
+honest contracts that want to make their user's life better. We believe
+that this is a reasonable security model, as transaction descriptions can be
+audited at the same time as contract code, allowing auditors and code
+reviewers to check that transaction descriptions are accurate as part of
+their review.
+
+
+## Specification
+
+The **description** (a string) and the matching **execcode** (bytecode)
+are generated simultaneously by evaluating the method on a contract:
+
+```solidity
+function eipXXXDescribe(bytes inputs, bytes32 reserved) view returns (string description, bytes execcode)
+```
+
+The human-readable **description** can be shown in any client which supports
+user interaction for approval, while the **execcode** is the data that
+should be included in a transaction to the contract to perform that operation.
+
+The method must be executable in a static context, (i.e. any side effects,
+such as logX, sstore, etc.), including through indirect calls may be ignored.
+
+During evaluation, the `ADDRESS` (i.e. `to`), `CALLER` (i.e. `from`), `VALUE`,
+and `GASPRICE` must be the same as the values for the transaction being
+described, so that the code generating the description can rely on them.
+
+When executing the bytecode, best efforts should be made to ensure `BLOCKHASH`,
+`NUMBER`, `TIMESTAMP` and `DIFFICULTY` match the `"latest"` block. The
+`COINBASE` should be the zero address.
+
+The method may revert, in which case the signing must be aborted.
+
+
+## Rationale
+
+### Meta Description
+
+There have been many attempts to solve this problem, many of which attempt
+to examine the encoded transaction data or message data directly.
+
+In many cases, the information that would be necessary for a meaningful
+description is not present in the final encoded transaction data or message
+data.
+
+Instead this EIP uses an indirect description of the data.
+
+For example, the `commit(bytes32)` method of ENS places a commitement
+**hash** on-chain. The hash contains the **blinded** name and address; 
+since the name is blinded, the encoded data (i.e. the hash) no longer 
+contains the original values and is insufficient to access the necessary 
+values to be included in a description.
+
+By instead describing the commitment indirectly (with the original information
+intact: NAME, ADDRESS and SECRET) a meaningful description can be computed
+(e.g. "commit to NAME for ADDRESS (with SECRET)") and the matching data can
+be computed (i.e. `commit(hash(name, owner, secret))`).
+
+This technique of blinded data will become much more popular with L2
+solutions, which use blinding not necessarily for privacy, but for 
+compression.
+
+### Entangling the Contract Address
+
+To prevent signed data being used across contracts, the contract address
+is entanlged into both the transaction implicitly via the `to` field.
+
+
+### Alternatives
+
+- NatSpec and company are a class of more complex languages that attempt to describe the encoded data directly. Because of the language complexity they often end up being quite large requiring entire runtime environments with ample processing power and memory, as well as additional sandboxing to reduce security concerns. One goal of this is to reduce the complexity to something that could execute on hardware wallets and other simple wallets. These also describe the data directly, which in many cases (such as blinded data), cannot adequately describe the data at all
+
+- Custom Languages; due to the complexity of Ethereum transactions, any language used would require a lot of expressiveness and re-inventing the wheel. The EVM already exists (it may not be ideal), but it is there and can handle everything necessary.
+
+- Format Strings (e.g. Trustless Signing UI Protocol; format strings can only operate on the class of regular languages, which in many cases is insufficient to describe an Ethereum transaction. This was an issue quite often during early attempts at solving this problem.
+
+- The signTypedData [EIP-712](./eip-712.md) has many parallels to what this EIP aims to solve
+
+
+## Backwards Compatibility
+
+This does not affect backwards compatibility.
+
+
+## Reference Implementation
+
+@TODO (consider adding it as one or more files in `../assets/eip-####/`)
+
+I will add examples in Solidity and JavaScript.
+
+
+## Security Considerations
+
+### Escaping Text
+
+Wallets must be careful when displaying text provided by contracts and proper
+efforts must be taken to sanitize it, for example, be sure to consider:
+
+- HTML could be enbedded to attempt to trick web-based wallets into [executing code](https://en.wikipedia.org/wiki/Code_injection) using the script tag (possibly uploading any private keys to a server)
+- In general, extreme care must be used when rendering HTML; consider the ENS names `<span style="display:none">not-</span>ricmoo.eth` or `&thinsp;ricmoo.eth`, which if rendered without care would appear as `ricmoo.eth`, which it is not
+- Other marks which require escaping could be included, such as quotes (`"`), formatting (`\n` (new line), `\f` (form feed), `\t` (tab), any of many [non-standard whitespaces](https://en.wikipedia.org/wiki/Whitespace_character#Spaces_in_Unicode)), back-slassh (`\`)
+- UTF-8 has had bugs in the past which could allow arbitrary code execution and [crashing renderers](https://osxdaily.com/2015/05/27/bug-crashes-messages-app-ios-workaround/); consider using the UTF-8 replacement character (or *something*) for code-points outside common planes or common sub-sets within planes
+- [Homoglyphs attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack)
+- [Right-to-left](https://en.wikipedia.org/wiki/Right-to-left_mark) mark may affect rendering
+- Many other things, deplnding on your environment
+
+
+## Copyright
+
+Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).