status-im/EIPs
2
0
Fork 0
mirror of https://github.com/status-im/EIPs.git synced 2025-03-04 00:20:54 +00:00
Code Issues Projects Releases Wiki Activity

Automatically merged updates to draft EIP(s) 1066

Browse Source 
Hi, I'm a bot! This change was automatically merged because:

 - It only modifies existing Draft or Last Call EIP(s)
 - The PR was approved or written by at least one author of each modified EIP
 - The build is passing
This commit is contained in:
Brooklyn Zelenka 2018-12-07 13:33:48 -08:00 committed by EIP Automerge Bot
parent f2d42c39e9
commit 67c893bb54
1 changed files with 165 additions and 182 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

347
EIPS/eip-1066.md
View File

@ -11,64 +11,55 @@ created: 2018-05-05
## Simple Summary
Broadly applicable status codes for Ethereum smart contracts.
Broadly applicable status codes for smart contracts.
## Abstract
This standard outlines a common set of Ethereum status codes (ESC) in the same
vein as 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.
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` and require human intervention,
or return a Boolean pass/fail status. Status codes are similar-but-orthogonal
to `revert`ing with a reason, but aimed at automation and translation.
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 `revert`ing 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, and truly exceptional conditions
that require halting execution.
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
### Autonomy
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.
### 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.
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.
ESCs convey a much richer set of information than Booleans,
and are able to be reacted to autonomously unlike arbitrary strings.
Status codes convey a much richer set of information [than Booleans](https://existentialtype.wordpress.com/2011/03/15/boolean-blindness/), and are able to be reacted to autonomously unlike arbitrary strings.
### User Feedback
### User Experience (UX)
Since status codes are finite and known in advance, we can 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.
_End users get little to no feedback, and there is no translation layer._
We also see a desire for this [in transactions](http://eips.ethereum.org/EIPS/eip-658),
and there's no reason that ESCs couldn't be used by the EVM itself.
Since ERC1066 status codes are finite and known in advance, we can leverage [ERC1444](https://eips.ethereum.org/EIPS/eip-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.
### More than Pass/Fail
We also see a desire for this [in transactions](http://eips.ethereum.org/EIPS/eip-658), and there's no reason that status codes couldn't be used by the EVM itself.
While clearly related, status codes are complementary to "revert with reason".
ESCs 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.
### 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, `event`s, and `revert`s.
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.
### 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 as the first value of potentially multiple return values.
Codes are returned either on their own, or as the first value of a multiple return.
```solidity
// Status only
@ -93,17 +84,11 @@ function safeIncrement(uint8 interval) public returns (byte status, uint8 newCou
}
```
In the rare case that there are multiple codes required to express an idea,
they should be organized in ascending order.
### 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.
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.
Unspecified codes are _not_ free for arbitrary use, but rather open for further specification.
**NB: Unspecified codes are _not_ free for arbitrary use, but rather open for further specification.**
#### `0x0*` Generic
@ -117,15 +102,15 @@ General codes. These double as bare "reasons", since `0x01 == 1`.
| `0x03` | Awaiting / Before |
| `0x04` | Action Required |
| `0x05` | Expired |
| `0x06` | |
| `0x07` | |
| `0x08` | |
| `0x09` | |
| `0x0A` | |
| `0x0B` | |
| `0x0C` | |
| `0x0D` | |
| `0x0E` | |
| `0x06` | [reserved] |
| `0x07` | [reserved] |
| `0x08` | [reserved] |
| `0x09` | [reserved] |
| `0x0A` | [reserved] |
| `0x0B` | [reserved] |
| `0x0C` | [reserved] |
| `0x0D` | [reserved] |
| `0x0E` | [reserved] |
| `0x0F` | Meta or Info Only |
#### `0x1*` Permission
@ -140,21 +125,20 @@ Related to permisson, authorization, approval, and so on.
| `0x13` | Awaiting Permission |
| `0x14` | Awaiting Your Permission |
| `0x15` | No Longer Allowed |
| `0x16` | |
| `0x17` | |
| `0x18` | |
| `0x19` | |
| `0x1A` | |
| `0x1B` | |
| `0x1C` | |
| `0x1D` | |
| `0x1E` | |
| `0x16` | [reserved] |
| `0x17` | [reserved] |
| `0x18` | [reserved] |
| `0x19` | [reserved] |
| `0x1A` | [reserved] |
| `0x1B` | [reserved] |
| `0x1C` | [reserved] |
| `0x1D` | [reserved] |
| `0x1E` | [reserved] |
| `0x1F` | Permission Meta or Info |
#### `0x2*` Find, Match, &c
This range is broadly intended for finding and matching.
Data lookups and order matching are two common use cases.
This range is broadly intended for finding and matching. Data lookups and order matching are two common use cases.
| Code | Description |
|-----------------|:-------------------------|
@ -164,21 +148,20 @@ Data lookups and order matching are two common use cases.
| `0x23` | Awaiting Match |
| `0x24` | Match Request Received |
| `0x25` | Out of Range |
| `0x26` | |
| `0x27` | |
| `0x28` | |
| `0x29` | |
| `0x2A` | |
| `0x2B` | |
| `0x2C` | |
| `0x2D` | |
| `0x2E` | |
| `0x26` | [reserved] |
| `0x27` | [reserved] |
| `0x28` | [reserved] |
| `0x29` | [reserved] |
| `0x2A` | [reserved] |
| `0x2B` | [reserved] |
| `0x2C` | [reserved] |
| `0x2D` | [reserved] |
| `0x2E` | [reserved] |
| `0x2F` | Matching Meta or Info |
#### `0x3*` Negotiation, Terms, and Offers
Negotiation, and very broadly the flow of such transactions.
Note that "other party" may be more than one actor (not necessarily the sender).
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 |
|-----------------|:----------------------------|
@ -188,15 +171,15 @@ Note that "other party" may be more than one actor (not necessarily the sender).
| `0x33` | Awaiting Their Ratification |
| `0x34` | Awaiting Your Ratification |
| `0x35` | Offer Expired |
| `0x36` | |
| `0x37` | |
| `0x38` | |
| `0x39` | |
| `0x3A` | |
| `0x3B` | |
| `0x3C` | |
| `0x3D` | |
| `0x3E` | |
| `0x36` | [reserved] |
| `0x37` | [reserved] |
| `0x38` | [reserved] |
| `0x39` | [reserved] |
| `0x3A` | [reserved] |
| `0x3B` | [reserved] |
| `0x3C` | [reserved] |
| `0x3D` | [reserved] |
| `0x3E` | [reserved] |
| `0x3F` | Negotiation Meta or Info |
#### `0x4*` Availability
@ -211,42 +194,40 @@ Service or action availability.
| `0x43` | Not Yet Available |
| `0x44` | Awaiting Your Availability |
| `0x45` | No Longer Available |
| `0x46` | |
| `0x47` | |
| `0x48` | |
| `0x49` | |
| `0x4A` | |
| `0x4B` | |
| `0x4C` | |
| `0x4D` | |
| `0x4E` | |
| `0x46` | [reserved] |
| `0x47` | [reserved] |
| `0x48` | [reserved] |
| `0x49` | [reserved] |
| `0x4A` | [reserved] |
| `0x4B` | [reserved] |
| `0x4C` | [reserved] |
| `0x4D` | [reserved] |
| `0x4E` | [reserved] |
| `0x4F` | Availability Meta or Info |
#### `0x5*` TBD
Currently unspecified
Currently unspecified. (Full range reserved)
#### `0x6*` TBD
Currently unspecified
Currently unspecified. (Full range reserved)
#### `0x7*` TBD
Currently unspecified
Currently unspecifie. (Full range reserved)
#### `0x8*` TBD
Currently unspecified
Currently unspecified. (Full range reserved)
#### `0x9*` TBD
Currently unspecified
Currently unspecified. (Full range reserved)
#### `0xA*` Application-Specific Codes
Contracts may have special states that they need to signal.
This proposal only outlines the broadest meanings, but implementers may have very
specific meanings for each, as long as they are coherent with the broader definition.
Contracts may have special states that they need to signal. This proposal only outlines the broadest meanings, but implementers may have very specific meanings for each, as long as they are coherent with the broader definition.
| Code | Description |
|-----------------|:--------------------------------|
@ -256,35 +237,34 @@ specific meanings for each, as long as they are coherent with the broader defini
| `0xA3` | App-Specific Awaiting / Before |
| `0xA4` | App-Specific Action Required |
| `0xA5` | App-Specific Expiry |
| `0xA6` | |
| `0xA7` | |
| `0xA8` | |
| `0xA9` | |
| `0xAA` | |
| `0xAB` | |
| `0xAC` | |
| `0xAD` | |
| `0xAE` | |
| `0xA6` | [reserved] |
| `0xA7` | [reserved] |
| `0xA8` | [reserved] |
| `0xA9` | [reserved] |
| `0xAA` | [reserved] |
| `0xAB` | [reserved] |
| `0xAC` | [reserved] |
| `0xAD` | [reserved] |
| `0xAE` | [reserved] |
| `0xAF` | App-Specific Meta or Info |
#### `0xB*` TBD
Currently unspecified
Currently unspecified. (Full range reserved)
#### `0xC*` TBD
Currently unspecified
Currently unspecified. (Full range reserved)
#### `0xD*` TBD
Currently unspecified
Currently unspecified. (Full range reserved)
#### `0xE*` Cryptography and Authentication
Actions around signatures, cryptography, signing, and application-level authentication.
The meta code `0xEF` is often used to signal a payload descibing the algorithm
or process used.
The meta code `0xEF` is often used to signal a payload describing the algorithm or process used.
| Code | Description |
|-----------------|:----------------------------|
@ -294,21 +274,20 @@ or process used.
| `0xE3` | Their Signature Required |
| `0xE4` | Your Signature Required |
| `0xE5` | Auth Expired |
| `0xE6` | |
| `0xE7` | |
| `0xE8` | |
| `0xE9` | |
| `0xEA` | |
| `0xEB` | |
| `0xEC` | |
| `0xED` | |
| `0xEE` | |
| `0xE6` | [reserved] |
| `0xE7` | [reserved] |
| `0xE8` | [reserved] |
| `0xE9` | [reserved] |
| `0xEA` | [reserved] |
| `0xEB` | [reserved] |
| `0xEC` | [reserved] |
| `0xED` | [reserved] |
| `0xEE` | [reserved] |
| `0xEF` | Crypto Info or Meta |
#### `0xF0` Off-Chain
For off-chain actions. Much like th `0x0_: Generic` range, `0xF*` is very general,
and does little to modify the reason.
For off-chain actions. Much like th `0x0_: Generic` range, `0xF*` is very general, and does little to modify the reason.
Among other things, the meta code `0xFF` may be used to describe what the off-chain process is.
@ -320,17 +299,39 @@ Among other things, the meta code `0xFF` may be used to describe what the off-ch
| `0xF3` | Awaiting Off-Chain Completion |
| `0xF4` | Off-Chain Action Required |
| `0xF5` | Off-Chain Service Unavailable |
| `0xF6` | |
| `0xF7` | |
| `0xF8` | |
| `0xF9` | |
| `0xFA` | |
| `0xFB` | |
| `0xFC` | |
| `0xFD` | |
| `0xFE` | |
| `0xF6` | [reserved] |
| `0xF7` | [reserved] |
| `0xF8` | [reserved] |
| `0xF9` | [reserved] |
| `0xFA` | [reserved] |
| `0xFB` | [reserved] |
| `0xFC` | [reserved] |
| `0xFD` | [reserved] |
| `0xFE` | [reserved] |
| `0xFF` | Off-Chain Info or Meta |
### As a Grid
| X. Low Nibble | 0. Generic | 10. Permission | 20. Find/Match/&c | 30. Negotiation / Offers | 40. Availability | 50. [reserved] | 60. [reserved] | 70. [reserved] | 80. [reserved] | 90. [reserved] | A0. [reserved] | B0. [reserved] | C0. [reserved] | D0. [reserved] | E0. Cryptography | F0. Off Chain |
|-----------------------------------|-------------------------|-------------------------------|-------------------------|----------------------------------|----------------------------------|----------------|----------------|----------------|----------------|----------------|----------------|----------------|----------------|----------------|-------------------------------------|---------------------------------------------------|
| 0. Failure | 0x00 Failure | 0x10 Disallowed | 0x20 Not Found | 0x30 Other Party Disagreed | 0x40 Unavailable or Expired | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | 0xE0 Decrypt Failure | 0xF0 Off Chain Failure |
| 1. Success | 0x01 Success | 0x11 Allowed | 0x21 Found | 0x31 Other Party Agreed | 0x41 Available | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | 0xE1 Decrypt Success | 0xF1 Off Chain Success |
| 2. Accepted / Started | 0x02 Accepted / Started | 0x12 Requested Permission | 0x22 Match Request Sent | 0x32 Sent Offer | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | 0xE2 Signed | 0xF2 Off Chain Process Started |
| 3. Awaiting Others | 0x03 Awaiting | 0x13 Awaiting Permission | 0x23 Awaiting Match | 0x33 Awaiting Their Ratification | 0x43 Not Yet Available | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | 0xE3 Other Party Signature Required | 0xF3 Awaiting Off Chain Completion |
| 4. Action Required / Awaiting You | 0x04 Action Required | 0x14 Awaiting Your Permission | [reserved] | 0x34 Awaiting Your Ratification | 0x44 Awaiting Your Availability* | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | 0xE4 Your Signature Required | 0xF4 Off Chain Action Required |
| 5. [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] |
| 6. [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] |
| 7. [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] |
| 8. [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] |
| 9. [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] |
| A. [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] |
| B. [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] |
| C. [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] |
| D. [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] |
| E. [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] |
| F. Meta/Info | 0x0F Metadata Only | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | [reserved] | 0xFF Data Source is Off Chain (ie: no guarantees) |
### Example Function Change
```solidity
@ -457,78 +458,61 @@ AwesomeCoin DEX TraderBot
### Encoding
ESCs are encoded as a `byte`. Hex values break nicely into high and low nibbles:
`category` and `reason`. For instance, `hex"01"` stands for general success
and `hex"00"` for general failure.
Status codes are encoded as a `byte`. Hex values break nicely into high and low nibbles: `category` and `reason`. For instance, `0x01` stands for general success (ie: `true`) and `0x00` for general failure (ie: `false`).
`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.
`bytes1` is very lightweight, portable, easily interoperable with `uint8`, cast from `enum`s, and so on.
#### Alternatives
Alternate schemes include `bytes32` and `uint8`. While these work reasonably
well, they have drawbacks.
Alternate schemes include `bytes32` and `uint8`. While these work reasonably well, they have drawbacks.
`uint8` feels even more similar to HTTP status codes, and enums don't require
as much casting. However does not break as evenly as a square table
(256 doesn't look as nice in base 10).
`uint8` feels even more similar to HTTP status codes, and enums don't require as much casting. However does not break as evenly as a square table (256 doesn't look as nice in base 10).
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 256<sup>4</sup> (4.3 billion) permutations.
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 necessarily. This can lead to paradoxical results (ex `0x00` and `0x01` together), or greater resorces allocated to interpreting 256<sup>4</sup> (4.3 billion) permutations.
### Multiple Returns
While there may be cases where packing a byte array of ESCs may make sense, the simplest,
most forwards-compatible method of transmission is as the first value of a multiple return.
While there may be cases where packing a byte array of status codes may make sense, the simplest, most forwards-compatible method of transmission is as the first value of a multiple return.
Familiarity is also a motivating factor. A consistent position and encoding together
follow the principle of least surprise. It is both viewable as a "header" in the HTTP analogy,
or like the "tag" in BEAM tagged tuples.
Familiarity is also a motivating factor. A consistent position and encoding together follow the principle of least surprise. It is both viewable as a "header" in the HTTP analogy, or like the "tag" in BEAM tagged tuples.
### Human Readable
Developers should not be required to memorize 256 codes. However, they break nicely into a table.
Cognitive load is lowered by organizing the table into categories and reasons.
`0x10` and `0x11` belong to the same category, and `0x04` shares a reason with `0x24`
Developers should not be required to memorize 256 codes. However, they break nicely into a table. Cognitive load is lowered by organizing the table into categories and reasons. `0x10` and `0x11` belong to the same category, and `0x04` shares a reason with `0x24`
While this repository includes helper enums, we have found working directly in
the hex values to be quite natural. ESC `0x10` is just as comfortable as HTTP 401, for example.
While this repository includes helper enums, we have found working directly in the hex values to be quite natural. Status code `0x10` is just as comfortable as HTTP 401, for example.
#### Localizations
One commonly requested application of this spec is human-readable translations
of codes. This has been moved to its own proposal: [ERC-1444](https://github.com/ethereum/EIPs/pull/1444/),
primarily due to a desire to keep both specs focused.
One commonly requested application of this spec is human-readable translations of codes. This has been moved to its own proposal: [ERC-1444](https://github.com/ethereum/EIPs/pull/1444/), primarily due to a desire to keep both specs focused.
### Extensibility
The `0xA` category is reserved for application-specific statuses.
In the case that 256 codes become insufficient, `bytes1` may be embedded in larger byte arrays.
The `0xA` category is reserved for application-specific statuses. In the case that 256 codes become insufficient, `bytes1` may be embedded in larger byte arrays.
### EVM Codes
The EVM also returns a status code in transactions; specifically `0x00` and `0x01`.
This proposal both matches the meanings of those two codes, and could later be used
at the EVM level.
The EVM also returns a status code in transactions; specifically `0x00` and `0x01`. This proposal both matches the meanings of those two codes, and could later be used at the EVM level.
### Empty Space
Much like how HTTP status codes have large unused ranges, there are totally empty
sections in this proposal. The intent is to not impose a complete set of codes up front,
and to allow users to suggest uses for these spaces as time progresses.
Much like how HTTP status codes have large unused ranges, there are totally empty sections in this proposal. The intent is to not impose a complete set of codes up front, and to allow users to suggest uses for these spaces as time progresses.
### Beyond Errors
This spec is intended to be much more than a set of common errors. One design goal is to enable easier contract-to-contract communication, protocols built on top of status codes, and flows that cross off-chain. Many of these cases include either expected kinds of exception state (as opposed to true errors), neutral states, time logic, and various successes.
Just like how HTTP 200 has a different meaning from HTTP 201, ERC-1066 status codes can relay information between contract beyond simply pass or fail. They can be thought of as the edges in a graph that has smart contracts as nodes.
### Fully `revert`able
_This spec is fully compatible with `revert`-with-reason and does not intend to supplant it in any way._ Both by reverting with a common code, the developer can determine what went wrong from a set of known error states.
Further, by leveraging ERC-1066 and a translation table (such as in ERC-1444) in conjunction, developers and end users alike can receive fully automated human-readable error messages in the language and phrasing of their choice.
### Nibble Order
Nibble order makes no difference to the machine, and is purely mnemonic.
This design was originally in opposite order, but changed it for a few convenience factors.
Since it's a different scheme from HTTP, it may feel strange initially,
but becomes very natural after a couple hours of use.
Nibble order makes no difference to the machine, and is purely mnemonic. This design was originally in opposite order, but changed it for a few convenience factors. Since it's a different scheme from HTTP, it may feel strange initially, but becomes very natural after a couple hours of use.
#### Short Forms
@ -540,8 +524,7 @@ hex"1" == hex"01" == 1 // with casting
#### Contract Categories
Many applications will always be part of the same category.
For instance, validation will generally be in the `0x10` range.
Many applications will always be part of the same category. For instance, validation will generally be in the `0x10` range.
```solidity
contract Whitelist {
@ -585,7 +568,7 @@ function appCode(Sleep _state) returns (byte code) {
## Implementation
Reference cases and helper libraries (Solidity and JS) can be found at:
* [Source Code](https://github.com/expede/ethereum-status-codes/)
* [Source Code](https://github.com/fission-suite/fission-codes/)
* [Package on npm](https://www.npmjs.com/package/ethereum-status-codes)
## Copyright