EIP-3224: Described Data

[ricmoo]

Discussion for EIP-3224: Described Data

PR: #3224.

Abstract

Human-readable descriptions for machine executable operations, described in higher level machine readable data, so that wallets can provide meaningful feedback to the user describing the action the user is about to perform.

[MicahZoltu]

Am I correct that this is the same as #719 with the exception that it has the contract derive the friendly string rather than having the contract validate a DSL and then processing the DSL in a higher level language?

I assume the reason for this is because of the thing in the rationale section about how it is hard to define a DSL language?

[ricmoo]

I had not seen that EIP before, but it is similar. That EIP looks similar to a previous attempt I had made too, but has some short-coming when I actually tried to use it.

It did not work well on hardware wallets and was hard to extend to different purposes but more importantly there were use cases it couldn't actually handle; case where you need to actually process data.

For example, to commit to ENS, you need to commit a hash of the name, owner and a secret. Which means description needs to be computed independently from the data, but both need the same inputs.

This is the main motivation for moving to a meta description of the data that can generate the data required, also having a chance to describe it from the parameters passed in.

I assume the reason for this is because of the thing in the rationale section about how it is hard to define a DSL language?

Yes, that's a concise way of saying it. :)

[ricmoo]

There are two main points for discussion regarding this EIP that have come up during review, which need further discussion. a) Localization and b) Splitting the EIP up into possibly smaller EIPs.

[ricmoo]

Localizations

A few ideas have been put forward, both of which change the signature:

• (a) eipXXXDescribe(bytes describer_inputs, string[] locales)
• (b) eipXXXDescribe(bytes describer_inputs, bytes32 requested_formats) returns (bytes32 format, string description, bytes data)

The idea of the first (a) is to pass in a string of locales, which the contract could then process in order, choosing the best match for the requested language, date formats, delimiter, etc.

Pros

• This is how many high-level language APIs work today for localization
• Easy to understand
• Simple for clients to use

Cons

• It is largely focused on the case of locale selection, and may not adapt well to other constraints
• String comparison is already difficult enough in Solidity, and the way locale strings need to be processed has a lot of caveats that each developer would be responsible for (e.g. zh vs zh_cn vs zh_tw); and additionally if strings include mime-types or other constraints, string parsing is required
• The ABI encoding for this is quite complex (but that is easily handled by helper functions)

The idea of the second (b) is to use a bitfield similar to the ENS ABI support. Each bit or clump of bits can be used to encode some desired OR-ed feature or set of features. For now the value would be specified by the specification to be 0, but allows for expanding in the future. A given bit set may also consume some other bits in the field as a value, for example, maybe if bit 5 is set, then the locale is read from the 4 bytes in bits 96 through 64. The matching format is returned in the result. So, for example, if you requested the format by "markdown+english or plain-text", and the contract only understood "plain-english" the returned format would be the format value for "plain-english".

Basically it gives us space to add any feature we want in the future, while making sure current contracts can respond to current and future clients and the current clients can request descriptions from current and future contracts.

Pros

• Simple for contracts to process and clients to use
• Easy to extend in the future to allow either mutually-exclusive or combinational options with optional additional properties
• Can be used for many things, not necessarily just raw localization
• With the returned format, we can (I'm pretty sure?) drop the mime-type from the returned description string

Cons

• In the case of multiple fallback locales, multiple calls may need to be made in the event the earlier locales do not match
• Limited to 256-bits (although, some bit set could be used to indicate additional fields in the bytes describer_input)

---

The most important thing is that we have a way forward regarding forwards and backwards compatibility as new uses for this come up. I personally prefer option (b).

[ricmoo]

Splitting

There are a few things here that could be split up. First there are two goals trying to be solved here:

• signing described transactions
• signing described messages

For each there is a corresponding JSON-RPC method being proposed.

---

I would prefer keeping the methods together in a single EIP, since they are highly overlapping, and move the JSON-RPC calls out into their own EIP or possibly two separate EIPs referencing the described data EIP.

If the EIP is to be split up though, I'm most in favour of two EIPs, one for described data in general (including transactions and messages) and one for the JSON-RPC.

But this is up for discussion, so feedback please.

[ricmoo]

Another note: EIP-165 should be added along with the selectors to indicate whether signing a described transaction is supported, signing a described message is supported or if both are supported (or is that covered in the individual cases?).

[ricmoo]

Another point on localization, is that I expect domain specific languages (DSL) to become an important part for localizing, so a given bit set in the requested_format along with some reserved bytes for a maximum version, could indicate that a given template language is desired, in which case a reserved set of bytes in the format could indicate a DSL version to process the description string against.

For example, if the resulting string was "transfer(0x1234, 123)" to a DSL that understood this format, it could then re-localize it in the client. Clients that do not support the version of the DSL would simply get back the text/plain description.

[MicahZoltu]

Re: splitting the EIP:
If an EIP can be split, then it should be split. In this case, it is totally reasonable for any given contract to implement either just describeTransaction or just describeMessage. We want a contract to be able to easily say "I support EIP-XXX` and not have to say something like "I support EIP-XXX but only the following subset of features".

[MicahZoltu]

The bitfield thing seems way over-engineered to me. These functions will always be called off-chain, so we aren't constrained in any meaningful way by gas costs. Libraries can be built and used to handle the string manipulation so individual developers don't have to, and I think in the end the string parsing will be easier to grok for dapp developers (assuming library use) than the bitfield, plus debugging will be substantially easier.

As an example, I discussed the bitfield thing with you previously I believe, and I have read over what you put above a couple times and I still don't really get it.

[MicahZoltu]

Consider a registry instead of requiring the code live in the contract itself. A registry would address two problems:

1. Contract size limits.
2. Immutable contracts with an owner.

(1) is arguably not too big of a deal because the contract could just delegate to an external contract, thus making the minimum code required for implementing this very small.

(2) is a bit more compelling to me as there are a lot of existing contract wallets out there that may want to add support for this. These contract wallets can execute arbitrary code (e.g., calling into a standardized global registry contract to register itself) but they cannot mutate their own implementation (for good reason!). This also would mean that people in the future with Account Abstraction wallets who may get some generic AA wallet would be able to "enhance it" after the fact.

Since all interactions are off-chain, the cost of the external call to lookup the target contract in a registry seems to be very worth it to me given even marginal benefits.

[github-actions]

There has been no activity on this issue for two months. It will be closed in a week if no further activity occurs. If you would like to move this EIP forward, please respond to any outstanding feedback or add a comment indicating that you have addressed all required feedback and are ready for a review.

[github-actions]

This issue was closed due to inactivity. If you are still pursuing it, feel free to reopen it and respond to any feedback or request a review in a comment.

[ricmoo]

I don’t seem to have permission to reopen?

[MicahZoltu]

This is a discussion for a stagnant EIP. Do you plan on shepherding EIP-3224 through the process? If so, you will need to create a PR against EIP-3224 to move it back to Draft or Review, and in that PR post a comment that this also needs to be reopened.

If you don't plan on shepherding that EIP through the process, then this discussion issue should remain closed.

[ricmoo]

I'm working on updating the EIP right now, and splitting it into 4 separate EIPs. I'll message in that PR then once this is up. Thanks! :)

[drllau]

Question on domain specific language application ... LexDAO is looking at a use case for soft voting, typically Roman voting is yes/no but we want for certain situations to have yes/no/abstain/veto (last for privileged delegates). So we can write a description of the vote subject (different languages), but encode the options in the DSL, and the signature binds the two so no man-in-middle substitution.

Is this how your EIP could work?

[sambacha]

I'm working on updating the EIP right now, and splitting it into 4 separate EIPs. I'll message in that PR then once this is up. Thanks! :)

with a v5 (yes version 5) of eip712, is there any desire on your part @ricmoo to take this further?

[ricmoo]

Yes, I am still working on this EIP. Sorry for the delay.

[sambacha]

Yes, I am still working on this EIP. Sorry for the delay.

Nothing to be sorry about!

Would you like or need any help? Would very much like to assist in anyway possible, I ended up here after following the rabbit hole of #719 The all core wallet's dev discord server brought that EIP, and after reading into it this seems the most sane option.