ERC-1066: Status Codes

Brooklyn Zelenka; Tom Carchrae; Gleb Naumenko

Simple Summary

Broadly applicable status codes for smart contracts.

Abstract

This standard outlines a common set of status codes in a similar vein to HTTP statuses. This provides a shared set of signals to allow smart contracts to react to situations autonomously, expose localized error messages to users, and so on.

The current state of the art is to either revert on anything other than a clear success (ie: require human intervention), or return a low-context true or false. Status codes are similar-but-orthogonal to reverting with a reason, but aimed at automation, debugging, and end-user feedback (including translation). They are fully compatible with both revert and revert-with-reason.

As is the case with HTTP, having a standard set of known codes has many benefits for developers. They remove friction from needing to develop your own schemes for every contract, makes inter-contract automation easier, and makes it easier to broadly understand which of the finite states your request produced. Importantly, it makes it much easier to distinguish between expected errors states, truly exceptional conditions that require halting execution, normal state transitions, and various success cases.

Motivation

Semantic Density

HTTP status codes are widely used for this purpose. BEAM languages use atoms and tagged tuples to signify much the same information. Both provide a lot of information both to the programmer (debugging for instance), and to the program that needs to decide what to do next.

Status codes convey a much richer set of information than Booleans, and are able to be reacted to autonomously unlike arbitrary strings.

User Experience (UX)

End users get little to no feedback, and there is no translation layer.

Since ERC1066 status codes are finite and known in advance, we can leverage ERC-1444 to provide global, human-readable sets of status messages. These may also be translated into any language, differing levels of technical detail, added as revert messages, natspecs, and so on.

Status codes convey a much richer set of information than Booleans, and are able to be reacted to autonomously unlike arbitrary strings.

Developer Experience (DX)

Developers currently have very little context exposed by their smart contracts.

At time of writing, other than stepping through EVM execution and inspecting memory dumps directly, it is very difficult to understand what is happening during smart contract execution. By returning more context, developers can write well-decomposed tests and assert certain codes are returned as an expression of where the smart contract got to. This includes status codes as bare values, events, and reverts.

Having a fixed set of codes also makes it possible to write common helper functions to react in common ways to certain signals. This can live off- or on-chain library, lowering the overhead in building smart contracts, and helping raise code quality with trusted shared components.

We also see a desire for this in transactions, and there's no reason that these status codes couldn't be used by the EVM itself.

Smart Contract Autonomy

Smart contracts don’t know much about the result of a request beyond pass/fail; they can be smarter with more context.

Smart contracts are largely intended to be autonomous. While each contract may define a specific interface, having a common set of semantic codes can help developers write code that can react appropriately to various situations.

While clearly related, status codes are complementary to revert-with-reason. Status codes are not limited to rolling back the transaction, and may represent known error states without halting execution. They may also represent off-chain conditions, supply a string to revert, signal time delays, and more.

All of this enables contracts to share a common vocabulary of state transitions, results, and internal changes, without having to deeply understand custom status enums or the internal business logic of collaborator contracts.

Specification

Format

Codes are returned either on their own, or as the first value of a multiple return.

solidity

// Status only

function isInt(uint num) public pure returns (byte status) {
    return hex"01";
}

// Status and value

uint8 private counter;

function safeIncrement(uint8 interval) public returns (byte status, uint8 newCounter) {
    uint8 updated = counter + interval;

    if (updated >= counter) {
        counter = updated;
        return (hex"01", updated);
    } else {
        return (hex"00", counter);
    }
}

Code Table

Codes break nicely into a 16x16 matrix, represented as a 2-digit hex number. The high nibble represents the code's kind or "category", and the low nibble contains the state or "reason". We present them below as separate tables per range for explanatory and layout reasons.

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

`0x0*` Generic

General codes. These double as bare "reasons", since 0x01 == 1.

Code	Description
`0x00`	Failure
`0x01`	Success
`0x02`	Awaiting Others
`0x03`	Accepted
`0x04`	Lower Limit or Insufficient
`0x05`	Receiver Action Requested
`0x06`	Upper Limit
`0x07`	[reserved]
`0x08`	Duplicate, Unnecessary, or Inapplicable
`0x09`	[reserved]
`0x0A`	[reserved]
`0x0B`	[reserved]
`0x0C`	[reserved]
`0x0D`	[reserved]
`0x0E`	[reserved]
`0x0F`	Informational or Metadata

`0x1*` Permission & Control

Also used for common state machine actions (ex. "stoplight" actions).

Code	Description
`0x10`	Disallowed or Stop
`0x11`	Allowed or Go
`0x12`	Awaiting Other's Permission
`0x13`	Permission Requested
`0x14`	Too Open / Insecure
`0x15`	Needs Your Permission or Request for Continuation
`0x16`	Revoked or Banned
`0x17`	[reserved]
`0x18`	Not Applicable to Current State
`0x19`	[reserved]
`0x1A`	[reserved]
`0x1B`	[reserved]
`0x1C`	[reserved]
`0x1D`	[reserved]
`0x1E`	[reserved]
`0x1F`	Permission Details or Control Conditions

`0x2*` Find, Inequalities & Range

This range is broadly intended for finding and matching. Data lookups and order matching are two common use cases.

Code	Description
`0x20`	Not Found, Unequal, or Out of Range
`0x21`	Found, Equal or In Range
`0x22`	Awaiting Match
`0x23`	Match Request Sent
`0x24`	Below Range or Underflow
`0x25`	Request for Match
`0x26`	Above Range or Overflow
`0x27`	[reserved]
`0x28`	Duplicate, Conflict, or Collision
`0x29`	[reserved]
`0x2A`	[reserved]
`0x2B`	[reserved]
`0x2C`	[reserved]
`0x2D`	[reserved]
`0x2E`	[reserved]
`0x2F`	Matching Meta or Info

`0x3*` Negotiation & Governance

Negotiation, and very broadly the flow of such transactions. Note that "other party" may be more than one actor (not necessarily the sender).

Code	Description
`0x30`	Sender Disagrees or Nay
`0x31`	Sender Agrees or Yea
`0x32`	Awaiting Ratification
`0x33`	Offer Sent or Voted
`0x34`	Quorum Not Reached
`0x35`	Receiver's Ratification Requested
`0x36`	Offer or Vote Limit Reached
`0x37`	[reserved]
`0x38`	Already Voted
`0x39`	[reserved]
`0x3A`	[reserved]
`0x3B`	[reserved]
`0x3C`	[reserved]
`0x3D`	[reserved]
`0x3E`	[reserved]
`0x3F`	Negotiation Rules or Participation Info

`0x4*` Availability & Time

Service or action availability.

Code	Description
`0x40`	Unavailable
`0x41`	Available
`0x42`	Paused
`0x43`	Queued
`0x44`	Not Available Yet
`0x45`	Awaiting Your Availability
`0x46`	Expired
`0x47`	[reserved]
`0x48`	Already Done
`0x49`	[reserved]
`0x4A`	[reserved]
`0x4B`	[reserved]
`0x4C`	[reserved]
`0x4D`	[reserved]
`0x4E`	[reserved]
`0x4F`	Availability Rules or Info (ex. time since or until)