ERC-1066: Ethereum Status Codes (ESC)

EIPs
,
26

Great discussion here and on Telegram.

Some comments:

  • “insufficient allowance” vs. “invalid operator” - these are somewhat similar concepts I think, the former more tied to the ERC20 approve / transferFrom and the latter more tied to the ERC777 operator semantics. Could possibly be wrapped up in a single code “invalid operator”.

  • “funds locked” - I wonder if this could be made a bit more general. Locked funds could be due to vesting, seasoning periods (e.g. 12 month lock up for Reg. D) etc… There are also restrictions at the token level (e.g. maximum number of investors or maximum volume per period). I wonder if distinguishing these two cases (restricted due to sender properties, restricted due to token properties) might be useful?

I’ll def. be dialing into the community call on this - thanks @bmann for organising!

1 Like
27

Sharing an example permissioned ERC20 token impementation that utilizes these status codes: https://github.com/TPL-protocol/tpl-contracts/blob/master/contracts/examples/token/ERC20/TPLERC20Permissioned.sol

I also feel like 0x59 invalid balance (for representing cases where a minimum or maximum allowed balance would be exceeded) and 0x5a invalid state (for cases where the maximum number of total token holders would be exceeded or other similar errors) are common enough issues to warrant inclusion in the standard.

Looking forward to the discussion on the 4th!

28

Hello guys,

I would be very interested to participate with your group.
I am working on a similar issue with Mt Pelerin’s bridge protocol (https://github.com/MtPelerin/MtPelerin-protocol)

I’ve also already submitted an EIP 1592 on this very specific topic.

Best,

29

FISSION Codes (prev “ESC”) v1.0.0-beta

Hi everyone :wave:

The past few months have been filled with interviewing around two dozen companies and projects, soliciting general feedback form the community, and exploring alternative code layouts. We had a community call earlier this week, and it’s been great to see the interest both on and beyond Ethereum :tada:

One version that seemed promising at first was adding more structure: encoding the referent plus modal & temporal logics. This turned out to be too rigid, so we fell back to using the lowest bit to signify blocking/non-blocking, which is in the current proposal.

Fun Facts

  • Now have more codes than HTTP
  • Nearly two dozen projects interviewed for research
  • Used by at at least three other ERCs (at least one more being announced by a partner soon)
  • Four FISSION presentations (so far)

Why the major version bump?

As mentioned above, we propose moving a few of the rows to make even numbers “blocking / others have control” and odds “unblocking / you have control”. If there is strong opinion that this should not be the case, it is easily undone.

What’s New?

Columns

0x1* Permission & CONTROL

This column already contained permissions. A prior working design included a column for “stoplight” style transitions. We realized that this is really a type of permission (ie: permission to proceed), and merged it into this column.

Some examples:

  • 0x10 Disallowed or STOP
  • 0x11 Allowed or GO

0x3* Negotiation & GOVERNANCE

Negotiation has been expanded to include decision making and governance, which have lot of overlap.

Some examples:

  • 0x30 Sender Disagreed or NAY
  • 0x31 Sender Agrees or YEA
  • 0x34 Quorum Not Reached

0x4* Availability & Time

Simply expanded to include new rows (see below)

Some examples:

  • 0x42 Paused
  • 0x43 Queued
  • 0x48 Already Complete

Rows

0x*4 Lower Limit

Includes items like:

  • 0x24 Underflow
  • 0x54 Insufficient Funds
  • 0xE4 Untrusted/Unsigned

0x*6 Upper Limit

Includes items like:

  • 0x16 Revoked
  • 0x26 Overflow
  • 0x46 Expired

0x*8 Unnecessary or Duplicate

Includes items like:

  • 0x28 Conflict or Duplicate Entry
  • 0x48 Duplicate Request / Already Complete
  • 0x58 Funds Not Required

Feedback?

We’d love any feedback that the community has before we make a PR against the EIPs repo :smile:

1 Like
30

We spoke about this on the call, but I wanted to put it in the thread for the broader community.

v1.0.0-beta Code v1.0.0-beta Description 0age’s Description
0x50 Transfer Failed transfer failure
0x51 Transfer successful transfer success
0x54 Insufficient funds insufficient balance
0x24 Below Ok Range insufficient allowance
0x42 Paused transfers halted (contract paused)
0x53 Hold or escrow funds locked (lockup period)
0x10 Disallowed invalid sender
0x10 Disallowed invalid receiver
0x10 Disallowed invalid operator (transfer agent)
0x5f Token or financial info token meta or info

The really challenging ones here are the ones that refer to a specific role in the flow (sender/receiver/operator). I really tried to get these to work with absolute and relative roles, but it doesn’t fit well into the current design philosophy. I’m open to options to get these to work, but here are two rough-but-workable solutions in the meantime:

  1. Use application-specific ranges
  2. Have your protocol or other ERC include rider information:
returns (byte statusCode, address subject)
//...
return (hex"10", msg.sender) // specific operator not okay, taken programatically
return (hex"10", receiverAddress) // specific user not authed
return (hex"10", this) // this contract not authed

This pattern is applicable elsewhere, too

returns (byte statusCode, address subject)
//...

return (hex"26", tokenHolder) // holder has hit the max allowed balance for this token
1 Like
31

When a Solidity function returns a boolean, the returned data is padded to an even 32-byte boundary: 0x0000000000000000000000000000000000000000000000000000000000000001.

I presume there was some sort of engineering decision taken by the designers of the RPC to pad the data so drastically. (My guess is that it had something to do with performance. I can’t think of any other reason other than perhaps laziness). Does anyone know why that choice was made?

The reason I’m asking is that this proposal (which inserts a one-byte value at the start of the returned output) may (for all we know) step on that engineering decision. If this proposal takes hold, every previously 32-byte (or 32-byte aligned) return would be off by one byte at the start.

Does anyone know (or has anyone studied) the effect of this, if it becomes widely adopted, on overall system performance or efficiency? (Maybe it kicks something out of some hardware cache, or it causes Solidity compiler to generate horribly inefficient code – no-one knows and that’s the point.)

I recently started this discussion (Small suggested change to EIP 1), in the hopes that EIP authors would try to think about the effect of their proposal system-wide. I’m not sure this EIP does or doesn’t have system-wide effects, but it should be discussed.

Thoughts?

32

Hmm, you’re right to ask :thinking: I would be very surprised if this caused issues. It’s something that you can do right now, with no changes to the VM. For performance, EVM-native 32-byte numbers typically take more to emulate than single bytes, and thus should (in my WIP EVM implementation at least) be easy to emulate. My best guess about why that happens is that numbers on the stack will are padded to 32-bytes, but don’t know of any concrete reason.

@fubuloubu any ideas? Perhaps you could illuminate how Vyper behaves for bools?

33

@tjayrush @expede So the reason why it gets encoded as 0x0…1 (len=32) is because of the ABI encoding. Everything on the ABI uses a 32byte boundary - because of the 32byte “stack-word”. Going sub-32 byte gets really inefficient gas wise (in memory, gains are to be had when storing again).

ERC-1066 as I read it is layered on top of the ABI spec. So looking at ERC-1066 spec briefly the abi would return bytes1 which on the binary level is the same as 1 word \ bytes32. So if one wanted on could easily add 31 bytes more of status codes in for the same cost :wink:

3 Likes
34

Updated the EIP repo’s copy of ERC-1066 to include the v1.0.0 codes :tada:

Next steps:

  • Update fission-suite/fission-codes JS & Solidity helper libraries
  • Min 3 reusable example contracts that use v1.0.0
  • Set EIP to Last Call
    • 2 week clock starts
35

Great work with this @expede and a great presentation on status codes at Devcon also.

It would be great if you could illustrate the revert-with-reason with an example also.
I’ve looked at the examples at https://github.com/Finhaven/EthereumStatusCodes/tree/master/contracts/examples and at the https://eips.ethereum.org/EIPS/eip-1066 page, but didn’t find a revert-with-reason example.

If one would revert-with-reason would you just revert with the status code or would you also be able to add an additional message?

1 Like
36

The Solidity & JS libs just hit v1.0.0-RC1 :muscle:

37

Ooh, the Finhaven lib is pretty out of date! The current repo has its own GitHub org: Fission · GitHub

On the current version of the helper lib, you have the ability to hand it an #erc-1444 localization directly for the require helpers. Both of these should work today:

// Hardcoded Message
requireOk(someCode, "something went wrong!");

// Using an ERC-1444 automated localization based on the specific code
requireOk(someCode, Localization(0xabcdef));

I’m actively working on getting the singleton language registry set up, which can then get hardcoded into the lib. The above would then look like:

// Fully automatic translated message
requireOk(someCode);

…and it would just work, message and all :unicorn::sparkles:

I hope that helps!

1 Like
38

Please set a discussion end date

reference https://eips.ethereum.org/EIPS/eip-1

This should be a full 14 days after the date which the discussion end date is added.

39

Ooh thanks for pointing that out! Will do right now :+1:

UPDATE Add review end date to EIP-1066 by expede · Pull Request #1748 · ethereum/EIPs · GitHub

40

ERC-1066 Now in Last Call

The review ends on Monday, February 25, 2019. I would love to hear any final thoughts or discussion prior to it making it to Final.

Thanks to everyone for the interest and feedback so far :tada::tada::tada:

4 Likes
41

Here is my brief review of EIP-1066. I have not reviewed everything but a few items stand out. First are notes about the standardization.

Standardization is premature

No existing implementations are deployed. Nor are similar deployments cited that show a demand for these features. Therefore it is impossible to know if this EIP provides any value.

Reasons are not motivated

No documentation is shown to explain why these codes were chosen.

Nibbles

I recommend encouraging (SHOULD not MUST) people to use two-nibble returns hex"01" in all cases to promote clarity.

Here are more opinions on the topic itself.

It is wasteful in the default case

This ads one word of output for function calls to return a SUCCESS status code. Competing proposals do not require this extra cost. The cost of including an extra output word is not explained or experimented in this EIP.

Another proposal returns status and other outputs during a revert.

It is not backwards compatible

Adding an additional function return makes this incompatible with every existing contract and other standard, including ERC-20 and ERC-721.

It is unsafe

We learned from ERC-20 that returning (rather than reverting) from a “failed” function call is dangerous. Citation --> https://twitter.com/eth_classic/status/971030641406980096

Stronger motivation should be provided to rewrite this history with a new narrative.

The async DEX examples are not realistic

A DEX will not implement in this way.

Codes are ill-defined

Should I return 0xE1 Decrypt Success or 0x01 Success or 0x21 Found?

If there are so many new codes being introduced, they should have well-defined meanings, including motivations.

In other words, this EIP is basically proposing 100 different mini standards so I am expecting the rationale to be an order of magnitude longer than other EIPs I’ve read.

In all, this is a noble effort. And I think it is close to a good solution. Here’s my overall recommendation and a path forward.

Recommendation

As is, two issues are show stoppers for me:

  • Unsafeness on returning when a function fails
  • This ERC is not backwards compatible with any existing contract or standard

Therefore I do not recommend anybody to use this EIP as-is.

BUT

With one quick modification, this can be easily addressed…

Please consider to update this proposal to only use status codes through reverts.

AND that makes it compatible with another proposal — https://github.com/ethereum/EIPs/issues/838#issuecomment-462363456

The result is efficient, backwards compatible and allows very semantic use.

Also, feel free to reach out to me directly.

1 Like
42

Thanks for the mini-review! Yes, these are the things we hear, explain to folks that it’s a paradigm shift, and they tend to go “oh, yeah that actually makes a lot of sense.” I’m not totally sure how to more get it across in text, so I’m very open to suggestions. Anyhow, in the meantime our standard short rebuttals are below:

In all, this is a noble effort. And I think it is close to a good solution.

Thanks!

No documentation is shown to explain why these codes were chosen.

Fair! You’re right that it should be right in the proposal itself. I’ll copy paste a bunch from the Medium post and the notes from when we did those several dozen company interviews. Thanks :smile:

No existing implementations are deployed

In fact, some contracts are already using this (typically in the the security token world). The ERC1400 Security Token proposal depends on it and we have had discussions with folks looking to use it for blockchain identity use cases, as well.

Nibbles
I recommend encouraging ( SHOULD not MUST ) people to use two-nibble returns hex"01" in all cases to promote clarity.

I’m confused. In all cases, they’ll get cast to two nibbles, even if the first nibble is 0, since you can only work with full bytes. Am I misunderstanding something?

It is wasteful in the default case

Yes, but in what way was it successful? This is important information for many use cases that involve automation. Was it successful accepted but will be run later when quorum is reached? Did the transfer go through now? There are lots of cases here.

Adding an additional function return makes this incompatible with every existing contract and other standard, including ERC-20 and ERC-721.

Good news! You don’t need to change those contracts to wrap them in an interface (in a proxy contract), effectively giving backwards compatibility for those that already rely on ERC20 or ERC721, but giving a separate interface for others. Future contracts can make use of this functionality.

But I should emphasize that this proposal was created to solve problems that we were having when developing security tokens, and enables new use cases that are currently difficult to do interoperatively on Ethereum. Calling ERC20s and NFTs directly as is most commonly done today (largely because of how difficult it is to communicate between contracts autonomously) is not an amazing use case to show off this design pattern.

It is unsafe

As per the EIP, this is in no way a replacement for revert! Exceptional, state-breaking, or dangerous cases should absolutely 100% revert! In fact, the library provides helper functions to aid with a number of revert scenarios!

The async DEX examples are not realistic

Yes, it’s true that today’s DEXes aren’t very smart. They could be smarter and more autonomous by using such a standard, but still IMO doing one on-chain is impractical for most scenarios. And fair, it’s not the greatest use case, but it’s short, and people in the ecosystem understand token-related flows today. Essentially it’s a toy example for illustrating how codes can flow through a system, as per HTTP or BEAM. If you can think of a better example that’s widely understandable to an audience with experience limited to Solidity and JS (and that shockingly often doesn’t fully understand HTTP), I would love to include it!

Codes are ill-defined
Should I return 0xE1 Decrypt Success or 0x01 Success or 0x21 Found?

I mean, it depends on your use case. If you decrypted something, you should use 0xE1, if you looked something up in a table or found something you should use 0x21, and if you want straight dumb compatibility with bools you should use 0x01. HTTP Status Codes have a similar range of more specific codes to help in control flow.

They should have well-defined meanings, including motivations

These are all taken from real-world scenarios from interviews that we did with Ethereum companies, so there are motivations for every code (some cases joined or abstracted), even if they’re not all spelled out. As always with code, we think more documentation and use cases will be useful.

Please consider to update this proposal to only use status codes through reverts.

Evidently the paradigm and purpose of this document is not clear enough at the moment, for which I apologize. I do wonder if people come to this EIP with preexisting assumptions, since (as mentioned before) when I spell it out in detail that “no it doesn’t work like that and isn’t written in that way anywhere”, a light bulb goes off for a lot of people. It’s purpose is to give more semantic information to other contracts, developers, and users, in an automated way, in a similar vein to HTTP status codes. It is not about propagating exceptions: it’s about sending context around for both success and failure, and true errors/exceptional cases should promptly exist this flow and revert.

I’ll give you a simple illustrative real-world example for status codes:

You need to check if someone is 1/n whitelists maintained by several parties. This is key in regulated scenarios, so that not every token has to (for example) check everyone’s photo ID separately, which is time consuming, expensive, and error prone, and does not easily work across borders without multiple domain experts handling this per-domicile.

Since you need to check several of these lists, you need to not revert if it fails, and it’s not an irrecoverable error, it’s a normal part of flow (chances are that you’ll need to check several of these lists). You may not be allowed to read from this list (a closed list), the user being checked may be actively blacklisted, they may not be on that list, or their verification has started off-chain (someone is reviewing their passport) but hasn’t completed. If you need 2/3 to succeed, and 2 have blocking codes (ie: even numbered codes), then you should revert. Likewise, if there is an overflow, it should also revert.

AND that makes it compatible with another proposal — EIP 838: ABI specification for REVERT reason string · Issue #838 · ethereum/EIPs · GitHub

As per the EIP text, this is already fully compatible with revert-with-reason, and the helper lib provides ways of bridging the two with a nice, semantic interface.

Thanks again for the review :tada: Looking forward to further feedback on the above responses!

Relevant Resources

43

Regarding wasteful.

“In what way was it successful”? This will /always/ depend on the application. If a function casts a vote that is effective later when a quorum is reached then that is something that should be documented and already understood by the caller. When I cast I vote I expect that to work like a vote. When I transfer a token I expect the token to be transferred. “Waiting for a quorum to be achieved” is a ridiculous outcome for a standard, generic token transfer. It might be cool for a DAO action, but again that is application-specific.

Regarding upgrades.

Please explain how to make a proxy for the existing CryptoKitties contract to add this feature using less than $100,000 of gas.

Regarding revert with reason.

The abstract says “They are fully compatible with both revert and revert -with-reason.” This conflicts with the specification “Codes are returned either on their own, or as the first value of a multiple return” since the specification only relates to returns, not reverts.

44

since the specification only relates to returns, not reverts.

Yes, because this spec isn’t about the exceptional cases, it’s about the rest. It doesn’t preclude reverts, and the information gleaned from a code can be used in a revert. As an example:

require(someCheck(msg.sender) == 0x41, localize(0x41));

Or with the helper lib

pragma solidity ^0.5.0;

import { FISSION } from "fission-codes/contracts/FISSION.sol";
import { SimpleAuth } from "./SimpleAuth.sol";

contract Portfolio {
    SimpleAuth private auth;
    mapping (address => bool) private holdings;

    constructor (SimpleAuth control) public {
        auth = control;
    }

    function isHeld(address token) external view returns (byte status, bool held) {
        byte permission = auth.min(SimpleAuth.Level.Unregistered);
        if (FISSION.isBlocking(permission)) { return (permission, false); }
        return (FISSION.code(FISSION.Status.Found_Equal_InRange), holdings[token]);
    }

    function setTracking(address token, bool track) external returns (byte status) {
        FISSION.requireSuccess(auth.min(SimpleAuth.Level.Member));
        holdings[token] = track;
        return FISSION.code(FISSION.Status.Success);
    }
}

I’ll add this as an example to the spec. Thanks for raising that!

Regarding upgrades.

Please explain how to make a proxy for the existing CryptoKitties contract to add this feature using less than $100,000 of gas.

I see why you’re confused; not proxy but rather adapter. You create a contract that calls out to regaulr CryptoKitties, and returns the value plus some status code. The extra 700 gas from a CALL isn’t going to break the bank.

This will /always/ depend on the application.

I sympathize with this position! People should be application-specific enums and returning them along with their data. The problem is that there are a lot of contracts and downstream stanards out there that are looking for a high level of genericity and/or can benefit from helper libraries, collaborator contracts, and so on. These codes are indeed intentionally designed to handle common use cases, no all use cases.

“Waiting for a quorum to be achieved” is a ridiculous outcome for a standard, generic token transfer

For a bog-standard OZ ERC20? Of course I agree with you. Again, that’s not really what this enables. For a permissioned or multisig wallet this is a totally valid return! At the end of the day, most use cases fall into a handful of categories. Why make these contracts pluggable to a large number of producers and consumers of these messages that can’t know about your specific contract beforehand? I agree that this is not how things are done today: we’re stuck writing bespoke applications that don’t interoperate with each other, and live in isolation. If you start to see the blockchain as a web of autonomous actors rather than one-off single-call programs, we start to need some way of communicating more generically.

Does that help?

45

Here is the balance of my notes before.

Standardization is premature

Still, no existing implementations are deployed to mainnet. That makes it premature to standardize anything.

Reasons are not motivated

:white_check_mark: Documentation will be or has been added.

Nibbles

I was just recommending against short form. It will be more clear if all references to Success use the form 0x01 or hex"01" (pick one). This consistency can improve clarity.

It is wasteful in the default case

I still have yet to see any single instance where it would be helpful, in a general sense, to know that a call to castVote has the resulting status APP_SPECIFIC_SUCCESS rather than simply SUCCESS . EVM already has a mechanism for showing successful outcomes and the default successful outcome already indicates that the function did what it advertises to do.

I have not seen any counter point here yet.

This proposal would be great as a way to return semantic information during a revert (i.e. throw values instead of return values). I cited a comment that implements throw values. This would be a welcome paradigm shift.

It is not backwards compatible

It is claimed that an existing deployed ERC-721 could use an “adapter” to implement transfers using ERC-1066 DRAFT status codes with an additional 700 gas. But I have yet to see how.

I assert that this would require ~$100,000 worth of gas to implement just for the CryptoKitties contract.

It is unsafe

I disagree with the statement in the text:

The current state of the art is to … return a Boolean pass/fail status

My understanding is that current state of the art is to revert on failure. Also the statement:

Exceptional, state-breaking, or dangerous cases SHOULD revert!

Could be included in the EIP for clarity.

The async DEX examples are not realistic

:white_check_mark: We agree this example is not a good use case.

Realistic and useful use cases should be included in the specification. If only contrived examples can be provided then the value of the document is limited.

If a standard will be passed, the examples should be both conceivable and also deployed on mainnet.

Codes are ill-defined

Regarding successful outcomes, it should not be necessary for me to choose between “compatibility with bools” or other choices. The standard should have a prescriptive answer.

Regarding codes for unsuccessful outcomes, I have no complaints.

Again, I am a fan of using this proposal to describe unsuccessful outcomes.

Here are new notes introduced now.

The language is not strong enough

Please adopt language such as RFC 2119. This will improve clarity of the proposal.

Currently the specification is vague with statements such as:

Codes are returned as the first value of potentially multiple return values.

A much stronger and clearer statement would be:

A function that implements ERC-1066 MUST include a byte -typed value as the first return value and this value MUST follow the specification of the code table below.

It is currently unclear whether a contract can comply with ERC-1066 by having only some functions implement the protocol or if it is necessary for every function to implement the protocol.

Bytes32 is contradictory

The document states:

byte is quite lightweight, and can be easily packed with multiple codes into a bytes32 (or similar) if desired. It is also easily interoperable with uint8 , cast from enum s, and so on.

but later contradicts (using incorrect math, 4≠32):

Packing multiple codes into a single bytes32 is nice in theory, but poses additional challenges. Unused space may be interpeted as 0x00 Failure , you can only efficiently pack four codes at once, and there is a challenge in ensuring that code combinations are sensible. Forcing four codes into a packed representation encourages multiple status codes to be returned, which is often more information than strictly nessesary. This can lead to paradoxical results (ex 0x00 and 0x01 together), or greater resorces allocated to interpreting 2564 (4.3 billion) permutations.

Also, the example implementation does not follow this specification.

This document badly needs to use RFC 2119. At current, I don’t know if an application using multiple status codes packed into one bytes32 would be valid under this EIP. Presumably only the code >> 31 part would be covered by the specification, but this is currently ambiguous.

The output is wasteful

The proposal is rigid in limiting extensions:

Unspecified codes are not free for arbitrary use, but rather open for further specification.

but developers will be sure to demand extensions.

The Ethereum contract ABI specifies that return values will use a full word.

Reference: Contract ABI Specification — Solidity 0.8.26 documentation

This means the current ERC-1066 DRAFT specification (in one possible interpretation) prescribes one status byte and 31 bytes of zeros.

It may be helpful to use this specification:

  • A compliant function MUST have the status code as the first return value
  • The return value MUST be either byte or bytes32 type
  • The left-most 8 bits of the value MUST use the code table. i.e. byte(code)
  • A function that uses bytes32 return type MAY use the right-most 248 bits (i.e. bytes32(code) & ~bytes32(byte(0xff)) ) for application-specific status messaging.

If you choose this approach, definitely check with the Solidity and Vyper teams. You want to get a committment that if a function call returns a bytes32 when you are expecting a byte will not cause a problem. That committment should be documented in the Solidity and Vyper docs and should state that the return value will be truncated in this situation.

(And, per my notes above it will be better if this specification applies to throw values rather than return values.)