ERC-1066 Smart contract status codes (Status Codes)

Stagnant · Other · created 2018-05-05

A common status code scheme that lets smart contracts express not just success or failure but various situations such as pending, exceeded, or permission required, using a standardized one-byte code.

Why it is needed

Currently, smart contracts cannot clearly distinguish and report success and failure even when the situation is complex. When a problem occurs, they either revert the transaction, requiring human intervention, or return only a simple value such as true or false, making it hard to know exactly what happened. As a result, users cannot tell why a transaction failed and cannot receive feedback such as multilingual translations. Developers also find it hard to grasp what states a contract passed through during execution, making debugging difficult, and each contract has to build its own separate error scheme, making it hard for contracts to automatically interact with and exchange state with one another.

In depth

Code return format

The status code is of type byte (bytes1), returned either as the function's sole return value or as the first value when returning multiple values. For example, a function might return only status, or it might return (status, newCounter), combining status with an actual value. Always returning it in the first position lets the status be read from a consistent location, similar to an HTTP response header or a tagged tuple in the BEAM language.

16x16 code table structure

Codes are represented as two-digit hexadecimal values (0x00 to 0xFF), where the upper nibble denotes the 'category' and the lower nibble denotes the 'reason'. For example, 0x10 and 0x11 belong to the same category (permission/control), and 0x04 and 0x24 share the same reason (lower bound/insufficient). Codes in the 0x0 category are also compatible with integers, so they can be cast like hex"1" == hex"01" == 1.

Meaning by category

0x0* represents general-purpose codes (success, failure, pending, etc.), 0x1* represents permission/control (allowed, forbidden, suspended, etc.), 0x2* represents search/comparison/range (found, exceeded, insufficient), 0x3* represents negotiation/governance (agreement, vote, quorum), 0x4* represents availability/time (paused, expired), 0x5* represents tokens/funds (transfer success, failure, escrow), 0xA* represents application-specific codes, 0xE* represents cryptography/identity/proof (signature, decryption), and 0xF* represents off-chain actions. The ranges 0x6-0x9 and 0xB-0xD are still unassigned (TBD) and are entirely reserved.

Even codes are blocking, odd codes are non-blocking

By design convention, even codes indicate a blocking state where the receiver has no control, while odd codes indicate a non-blocking state where the receiver is free to proceed with its next action. This also aligns with the even/odd correspondence of 0x00 (failure, false) and 0x01 (success, true), so blocking status can be determined with a simple bit check.

Fully compatible with revert-with-reason

This standard is intended to complement revert-with-reason, not replace it. Passing a standard status code along with a revert makes it possible to identify which known error state caused it, and combining this with a translation table like ERC-1444 can provide automatically translated messages in the language and level of detail the user wants. Status codes can also express known error states, off-chain conditions, time delays, and more without reverting the transaction, giving them broader applicability than revert alone.

Application-specific extensions and meta codes

The 0xA* range is reserved for application-specific states, allowing implementers to assign their own specific meanings. If 256 codes are not enough, the bytes1 code can be extended by embedding it in a larger byte array. The last code in each category (e.g. 0x0F, 0x1F, 0xEF, 0xFF) is used to convey additional information or metadata about that category. Codes that have not yet been assigned are not open space to be used arbitrarily, but slots left open for future specification.

Proposal status: Stagnant

This proposal is in Stagnant status, meaning it is no longer being actively discussed or advanced.

Original ERC · ← ERCs