From d5e05caf2ad6aa5cc513cf20b02c26ef26070af0 Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Sun, 29 Apr 2018 18:08:39 -0700 Subject: [PATCH 01/31] Starting on EIP --- EIPS/eip-status-codes.md | 63 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 EIPS/eip-status-codes.md diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md new file mode 100644 index 00000000000000..10ea4bb5258114 --- /dev/null +++ b/EIPS/eip-status-codes.md @@ -0,0 +1,63 @@ +--- +eip: +title: Status Codes +author: Brooklyn Zelenka (@expede) , Tom Carchrae (@carchrae) , Gleb Naumenko (@naumenkogs) +discussions-to: +status: Draft +type: Standards Track +category: ERC +created: 2018-05-04 +--- + +## Simple Summary + +If you can't explain it simply, you don't understand it well enough." Provide a simplified and layman-accessible explanation of the EIP. + +## Abstract + +A short (~200 word) description of the technical issue being addressed. + +## 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. + +## Semantically Rich + +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. + +## User Feedback + +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. + +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. + +## Specification + +The technical specification should describe the syntax and semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations for any of the current Ethereum platforms (go-ethereum, parity, cpp-ethereum, ethereumj, ethereumjs, and [others](https://github.com/ethereum/wiki/wiki/Clients)). + +## Rationale + +The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other languages. The rationale may also provide evidence of consensus within the community, and should discuss important objections or concerns raised during discussion.--> + +## Test Cases + +Test cases for an implementation are mandatory for EIPs that are affecting consensus changes. Other EIPs can choose to include links to test cases if applicable. + +## Implementation + +The implementations must be completed before any EIP is given status "Final", but it need not be completed before the EIP is accepted. While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of "rough consensus and running code" is still useful when it comes to resolving many discussions of API details. + +## Copyright +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). From ba80058395f555f00a4fc7579c6859edf7cda220 Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Sun, 29 Apr 2018 18:10:32 -0700 Subject: [PATCH 02/31] Minor formatting --- EIPS/eip-status-codes.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index 10ea4bb5258114..7367d7b3040ab6 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -18,13 +18,13 @@ If you can't explain it simply, you don't understand it well enough." Provide a A short (~200 word) description of the technical issue being addressed. ## Motivation -## Autonomy +### 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. -## Semantically Rich +### Semantically 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 @@ -34,7 +34,7 @@ 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. -## User Feedback +### User Feedback 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, @@ -51,13 +51,11 @@ The technical specification should describe the syntax and semantics of any new The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other languages. The rationale may also provide evidence of consensus within the community, and should discuss important objections or concerns raised during discussion.--> -## Test Cases - -Test cases for an implementation are mandatory for EIPs that are affecting consensus changes. Other EIPs can choose to include links to test cases if applicable. - ## Implementation The implementations must be completed before any EIP is given status "Final", but it need not be completed before the EIP is accepted. While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of "rough consensus and running code" is still useful when it comes to resolving many discussions of API details. +https://github.com/Finhaven/EthereumStatusCodes + ## Copyright Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). From 1496f6c491a73c5b19f1150dcee22c827a38267b Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Sun, 29 Apr 2018 18:17:52 -0700 Subject: [PATCH 03/31] Add sequence diagrams --- EIPS/eip-status-codes.md | 133 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 127 insertions(+), 6 deletions(-) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index 7367d7b3040ab6..8de5a20f0fb904 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -2,7 +2,6 @@ eip: title: Status Codes author: Brooklyn Zelenka (@expede) , Tom Carchrae (@carchrae) , Gleb Naumenko (@naumenkogs) -discussions-to: status: Draft type: Standards Track category: ERC @@ -14,17 +13,17 @@ created: 2018-05-04 If you can't explain it simply, you don't understand it well enough." Provide a simplified and layman-accessible explanation of the EIP. ## Abstract - -A short (~200 word) description of the technical issue being addressed. +Broadly applicable status codes for Ethereum smart contracts ## 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. -### Semantically Density +### 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 @@ -44,8 +43,130 @@ We also see a desire for this [in transactions](http://eips.ethereum.org/EIPS/ei and there's no reason that ESCs couldn't be used by the EVM itself. ## Specification - -The technical specification should describe the syntax and semantics of any new feature. The specification should be detailed enough to allow competing, interoperable implementations for any of the current Ethereum platforms (go-ethereum, parity, cpp-ethereum, ethereumj, ethereumjs, and [others](https://github.com/ethereum/wiki/wiki/Clients)). + +This ERC specifies codes, but not the format of exchange. For instance, +they may be returned as a single value, apart of a data structure (ex. a call stack), +in a variadic return, or packed into a byte array. + +### Code Table + +| X. Low Nibble | 0. Generic | 10. Permission | 20. Find/Match/&c | 30. Negotiation / Offers | 40. Availability | 50. | 60. | 70. | 80. | 90. | A0. | B0. | C0. | D0. | E0. Cryptography | F0. Off Chain | +|-----------------------------------|-------------------------|-------------------------------|-------------------------|----------------------------------|----------------------------------|-----|-----|-----|-----|-----|-----|-----|-----|-----|-------------------------------------|---------------------------------------------------| +| 0. Failure | 0x00 Failure | 0x10 Disallowed | 0x20 Not Found | 0x30 Other Party Disagreed | 0x40 Unavailable or Expired | | | | | | | | | | 0xE0 Decrypt Failure | 0xF0 Off Chain Failure | +| 1. Success | 0x01 Success | 0x11 Allowed | 0x21 Found | 0x31 Other Party Agreed | 0x41 Available | | | | | | | | | | 0xE1 Decrypt Success | 0xF1 Off Chain Success | +| 2. Accepted / Started | 0x02 Accepted / Started | 0x12 Requested Permission | 0x22 Match Request Sent | 0x32 Sent Offer | | | | | | | | | | | 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 | | | | | | | | | | 0xE3 Other Party Signature Required | 0xF3 Awaiting Off Chain Completion | +| 4. Action Required / Awaiting You | 0x04 Action Required | 0x14 Awaiting Your Permission | | 0x34 Awaiting Your Ratification | 0x44 Awaiting Your Availability* | | | | | | | | | | 0xE4 Your Signature Required | 0xF4 Off Chain Action Required | +| 5. | | | | | | | | | | | | | | | | | +| 6. | | | | | | | | | | | | | | | | | +| 7. | | | | | | | | | | | | | | | | | +| 8. | | | | | | | | | | | | | | | | | +| 9. | | | | | | | | | | | | | | | | | +| A. | | | | | | | | | | | | | | | | | +| B. | | | | | | | | | | | | | | | | | +| C. | | | | | | | | | | | | | | | | | +| D. | | | | | | | | | | | | | | | | | +| E. | | | | | | | | | | | | | | | | | +| F. Meta/Info | 0x0F Metadata Only | | | | | | | | | | | | | | | 0xFF Data Source is Off Chain (ie: no guarantees) | + +* Unused regions are available for further extension or custom codes +* You may need to scroll the tables horizontally (they're pretty wide) + +### Example Sequence Diagrams + +``` +0x03 = Waiting +0x31 = Other Party (ie: not you) Agreed +0x41 = Available +0x43 = Not Yet Available + + + Exchange + + +AwesomeCoin DEX TraderBot + + + + + | | buy(AwesomeCoin) | + | | <------------------------+ + | buy() | | + | <---------------------+ | + | | | + | Status [0x43] | | + +---------------------> | Status [0x03, 0x43] | + | +------------------------> | + | | | + | | isDoneYet() | + | | <------------------------+ + | | | + | | Status [0x03, 0x43] | + | +------------------------> | + | | | + | | | + | Status [0x41] | | + +---------------------> | | + | | | + | buy() | | + | <---------------------+ | + | | | + | | | + | Status [0x31] | | + +---------------------> | Status [0x31] | + | +------------------------> | + | | | + | | | + | | | + | | | + + + + +``` + + + +``` +0x01 = Generic Success +0x10 = Disallowed +0x11 = Allowed + + Token Validation + + + Buyer RegulatedToken TokenValidator IDChecker SpendLimiter + + + + + + + | buy() | | | | + +------------------------> | check() | | | + | +-----------------------> | check() | | + | | +-----------------------> | | + | | | | | + | | | Status [0x10] | | + | | Status [0x10] | <-----------------------+ | + | throw/revert | <-----------------------+ | | + | <------------------------+ | | | + | | | | | ++---------------------------+ | | | | +| | | | | | +| Updates ID with provider | | | | | +| | | | | | ++---------------------------+ | | | | + | | | | | + | buy() | | | | + +------------------------> | check() | | | + | +-----------------------> | check() | | + | | +-----------------------> | | + | | | | | + | | | Status [0x11] | | + | | | <-----------------------+ | + | | | | | + | | | | check() | + | | +-------------------------------------------> | + | | | | | + | | | | Status [0x11] | + | | Status [0x11] | <-------------------------------------------+ + | Status [0x01] | <-----------------------+ | | + | <------------------------+ | | | + | | | | | + | | | | | + | | | | | + + + + + + +``` ## Rationale From 2a948dcdb3bcb2b906406a272fb4aa8f6804f164 Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Sun, 29 Apr 2018 21:11:00 -0700 Subject: [PATCH 04/31] Flesh out --- .eip-permissions.md.icloud | Bin 0 -> 168 bytes .eip-security-token.md.icloud | Bin 0 -> 171 bytes EIPS/.eip-3.mediawiki.icloud | Bin 0 -> 165 bytes EIPS/.eip-4 2.md.icloud | Bin 0 -> 158 bytes EIPS/.eip-4 3.md.icloud | Bin 0 -> 158 bytes EIPS/.eip-token_validation 2.md.icloud | Bin 0 -> 175 bytes EIPS/.eip-token_validation.md.icloud | Bin 0 -> 173 bytes EIPS/eip-1/.process.png.icloud | Bin 0 -> 159 bytes EIPS/eip-107/.authorization-locked.png.icloud | Bin 0 -> 174 bytes .../.authorization-password.png.icloud | Bin 0 -> 176 bytes EIPS/eip-107/.authorization.png.icloud | Bin 0 -> 167 bytes EIPS/eip-858/.calculations.md.icloud | Bin 0 -> 165 bytes EIPS/eip-EIPS/.eip-616.md.icloud | Bin 0 -> 158 bytes EIPS/eip-status-codes.md | 51 +++++++++++++++--- 14 files changed, 43 insertions(+), 8 deletions(-) create mode 100644 .eip-permissions.md.icloud create mode 100644 .eip-security-token.md.icloud create mode 100644 EIPS/.eip-3.mediawiki.icloud create mode 100644 EIPS/.eip-4 2.md.icloud create mode 100644 EIPS/.eip-4 3.md.icloud create mode 100644 EIPS/.eip-token_validation 2.md.icloud create mode 100644 EIPS/.eip-token_validation.md.icloud create mode 100644 EIPS/eip-1/.process.png.icloud create mode 100644 EIPS/eip-107/.authorization-locked.png.icloud create mode 100644 EIPS/eip-107/.authorization-password.png.icloud create mode 100644 EIPS/eip-107/.authorization.png.icloud create mode 100644 EIPS/eip-858/.calculations.md.icloud create mode 100644 EIPS/eip-EIPS/.eip-616.md.icloud diff --git a/.eip-permissions.md.icloud b/.eip-permissions.md.icloud new file mode 100644 index 0000000000000000000000000000000000000000..bf5acfb6085f7343252c5bb109889c78eaa2d28c GIT binary patch literal 168 zcmYc)$jK}&F)+By$i&RT$`<1n92(@~mzbOComv?$AOPmNW#*&?XI4RkB;Z0psm1xF zMaiill?4zfq14O*-GbDj+|1(Q%>2A!z1$Q*Uj29h8LV1@QqxOw5{o$aW%Rw`lNi8& Okr6^OutRAW)d&E8mMy#h literal 0 HcmV?d00001 diff --git a/.eip-security-token.md.icloud b/.eip-security-token.md.icloud new file mode 100644 index 0000000000000000000000000000000000000000..7105ec5c52ea661f309c68983402f3f01598602e GIT binary patch literal 171 zcmYc)$jK}&F)+By$i&RT$`<1n92(@~mzbOComv?$AOPmNW#*&?XI4RkB;Z0psm1xF zMaiill?4zf(bUWW-Qv{b(xS|gO5KwD?9@EH+!R6Xt?>dfSak)ZrkCa<7IE;)=zArl RGJpXiBZOvPhte>r1prgKFIE5m literal 0 HcmV?d00001 diff --git a/EIPS/.eip-3.mediawiki.icloud b/EIPS/.eip-3.mediawiki.icloud new file mode 100644 index 0000000000000000000000000000000000000000..71a2a8f0a44650d50d974df7562a22cc13fb2854 GIT binary patch literal 165 zcmYc)$jK}&F)+By$i&RT$`<1n92(@~mzbOComv?$AOPmNW#*&?XI4RkB;Z0psm1xF zMaiill?4zf{?yC@U1Po6)RfG`^33c^LC&r50y0?D2c@Q$<|Gzz@XP3X#l$m!0V5-X LW?+ZXFscp!#BD5$ literal 0 HcmV?d00001 diff --git a/EIPS/.eip-4 2.md.icloud b/EIPS/.eip-4 2.md.icloud new file mode 100644 index 0000000000000000000000000000000000000000..88bb6cc2d770a6edf3e96dba4378e9de8461d470 GIT binary patch literal 158 zcmYc)$jK}&F)+By$i&RT$`<1n92(@~mzbOComv?$AOPmNW#*&?XI4RkB;Z0psm1xF zMaiill?5QFsMO2?T@wW(z1$Q*p7MAB8LSF}QqxOw5{o$aW%Rv5BN)Jdkr6^OutRAW GRSp0nv?+)H literal 0 HcmV?d00001 diff --git a/EIPS/.eip-4 3.md.icloud b/EIPS/.eip-4 3.md.icloud new file mode 100644 index 0000000000000000000000000000000000000000..8598690b5447e33c652648b5f3d9da2aaad2d271 GIT binary patch literal 158 zcmYc)$jK}&F)+By$i&RT$`<1n92(@~mzbOComv?$AOPmNW#*&?XI4RkB;Z0psm1xF zMaiill?5QFsMO2?T@wXkz1$Q*p7MAB8LSF}QqxOw5{o$aW%Rv5BN)Jdkr6^OutRAW GRSp0o0V#<9 literal 0 HcmV?d00001 diff --git a/EIPS/.eip-token_validation 2.md.icloud b/EIPS/.eip-token_validation 2.md.icloud new file mode 100644 index 0000000000000000000000000000000000000000..1ebce2b54de269ca2b55902d9bbc9b50e8813998 GIT binary patch literal 175 zcmYc)$jK}&F)+By$i&RT$`<1n92(@~mzbOComv?$AOPmNW#*&?XI4RkB;Z0psm1xF zMaiill?4zf$<)jO-IDz5)V%nz#GK5O#FEVXJOv}Y+!R3xn|J{ktU7~I(@S#_i#YgY V^u5wD8Nh&%5kfPtLunY*0RS0KFfjlC literal 0 HcmV?d00001 diff --git a/EIPS/.eip-token_validation.md.icloud b/EIPS/.eip-token_validation.md.icloud new file mode 100644 index 0000000000000000000000000000000000000000..262b11b4d8f509f982f1580ae1bfcc8a45cd1a8c GIT binary patch literal 173 zcmYc)$jK}&F)+By$i&RT$`<1n92(@~mzbOComv?$AOPmNW#*&?XI4RkB;Z0psm1xF zMaiill?4zf@zl%$-IDz5)V%nz#GK5O#FEVXJiXi$K?%Kh0U50Nf>P5KfRPbGGq6Kx H7*zoPx3nu1 literal 0 HcmV?d00001 diff --git a/EIPS/eip-107/.authorization-locked.png.icloud b/EIPS/eip-107/.authorization-locked.png.icloud new file mode 100644 index 0000000000000000000000000000000000000000..33dda5c43ca3b2922c4dd95ed9947d9991abf32c GIT binary patch literal 174 zcmYc)$jK}&F)+By$i&RT$`<1n92(@~mzbOComv?$AOPmNW#*&?XI4RkB;Z0psm1xF zMaiill?70##L|+C{G!aN#FEVXJl&l9G7a{5;))#Ny)e{Gt@Sg1mIWu;6$B8LV1^QqxOw5{o$a WW%Rw$vlzgDkr6^OutRAW)d>K&Suw`| literal 0 HcmV?d00001 diff --git a/EIPS/eip-107/.authorization.png.icloud b/EIPS/eip-107/.authorization.png.icloud new file mode 100644 index 0000000000000000000000000000000000000000..0f78ff1c6effd8986d72d6cb4ef1d79c906880b9 GIT binary patch literal 167 zcmYc)$jK}&F)+By$i&RT$`<1n92(@~mzbOComv?$AOPmNW#*&?XI4RkB;Z0psm1xF zMaiill?4zf!Nk&%jQpa^s>G7a{5-vaymUeTt?>dfSak%YrkCa<7IE;)=zGN_GJpXi NBZOvPhte>r0RWJUE?xit literal 0 HcmV?d00001 diff --git a/EIPS/eip-858/.calculations.md.icloud b/EIPS/eip-858/.calculations.md.icloud new file mode 100644 index 0000000000000000000000000000000000000000..61fbc653d21d7f228acb260cd7d92074837013ed GIT binary patch literal 165 zcmYc)$jK}&F)+By$i&RT$`<1n92(@~mzbOComv?$AOPmNW#*&?XI4RkB;Z0psm1xF zMaiill?4zf{^Z1*#4~^aBO`=n KV29E$sty3}H!TVP literal 0 HcmV?d00001 diff --git a/EIPS/eip-EIPS/.eip-616.md.icloud b/EIPS/eip-EIPS/.eip-616.md.icloud new file mode 100644 index 0000000000000000000000000000000000000000..d32046ec0a817237cc890b63cfb862d54001bea8 GIT binary patch literal 158 zcmYc)$jK}&F)+By$i&RT$`<1n92(@~mzbOComv?$AOPmNW#*&?XI4RkB;Z0psm1xF zMaiill?5QFsMO2?T{A;7z1$Q*m8 -If you can't explain it simply, you don't understand it well enough." Provide a simplified and layman-accessible explanation of the EIP. + +Broadly applicable status codes for Ethereum smart contracts. ## Abstract -Broadly applicable status codes for Ethereum smart contracts + +This standard provides a common set of Ethereum status codes (ESC) +in the same vein as HTTP statuses. This provides a shared contextual language +to allow smart contracts to react to situations autonomously, +expose localized error messages to users, and so on. ## Motivation @@ -169,14 +173,45 @@ AwesomeCoin DEX TraderBot ``` ## Rationale - -The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other languages. The rationale may also provide evidence of consensus within the community, and should discuss important objections or concerns raised during discussion.--> + +### 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. + +`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. + +Other schemes have been explored, including `bytes32` and `uint8`. They worked reasonably +well, but not as cleanly. `uint8` feels much closer to HTTP status codes, +does not break as cleanly as a square table (256 doesn't look as nice in base 10). + +### 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` + +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. + +### Extensiblilty + +The `0xA` category is reserved for application-specific statuses. +In the case that 256 codes become insufficient, `bytes1` my 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. ## Implementation - -The implementations must be completed before any EIP is given status "Final", but it need not be completed before the EIP is accepted. While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of "rough consensus and running code" is still useful when it comes to resolving many discussions of API details. -https://github.com/Finhaven/EthereumStatusCodes +Reference cases and helper library can be found [here](https://github.com/Finhaven/EthereumStatusCodes) ## Copyright + Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). From f176a4fc317881c69652b6c78ba65b7dc08749f1 Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Sun, 29 Apr 2018 21:13:10 -0700 Subject: [PATCH 05/31] Remove iCloud backups :wat: --- .eip-permissions.md.icloud | Bin 168 -> 0 bytes .eip-security-token.md.icloud | Bin 171 -> 0 bytes EIPS/.eip-3.mediawiki.icloud | Bin 165 -> 0 bytes EIPS/.eip-4 2.md.icloud | Bin 158 -> 0 bytes EIPS/.eip-4 3.md.icloud | Bin 158 -> 0 bytes EIPS/.eip-token_validation 2.md.icloud | Bin 175 -> 0 bytes EIPS/.eip-token_validation.md.icloud | Bin 173 -> 0 bytes EIPS/eip-1/.process.png.icloud | Bin 159 -> 0 bytes EIPS/eip-107/.authorization-locked.png.icloud | Bin 174 -> 0 bytes EIPS/eip-107/.authorization-password.png.icloud | Bin 176 -> 0 bytes EIPS/eip-107/.authorization.png.icloud | Bin 167 -> 0 bytes EIPS/eip-858/.calculations.md.icloud | Bin 165 -> 0 bytes EIPS/eip-EIPS/.eip-616.md.icloud | Bin 158 -> 0 bytes 13 files changed, 0 insertions(+), 0 deletions(-) delete mode 100644 .eip-permissions.md.icloud delete mode 100644 .eip-security-token.md.icloud delete mode 100644 EIPS/.eip-3.mediawiki.icloud delete mode 100644 EIPS/.eip-4 2.md.icloud delete mode 100644 EIPS/.eip-4 3.md.icloud delete mode 100644 EIPS/.eip-token_validation 2.md.icloud delete mode 100644 EIPS/.eip-token_validation.md.icloud delete mode 100644 EIPS/eip-1/.process.png.icloud delete mode 100644 EIPS/eip-107/.authorization-locked.png.icloud delete mode 100644 EIPS/eip-107/.authorization-password.png.icloud delete mode 100644 EIPS/eip-107/.authorization.png.icloud delete mode 100644 EIPS/eip-858/.calculations.md.icloud delete mode 100644 EIPS/eip-EIPS/.eip-616.md.icloud diff --git a/.eip-permissions.md.icloud b/.eip-permissions.md.icloud deleted file mode 100644 index bf5acfb6085f7343252c5bb109889c78eaa2d28c..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 168 zcmYc)$jK}&F)+By$i&RT$`<1n92(@~mzbOComv?$AOPmNW#*&?XI4RkB;Z0psm1xF zMaiill?4zfq14O*-GbDj+|1(Q%>2A!z1$Q*Uj29h8LV1@QqxOw5{o$aW%Rw`lNi8& Okr6^OutRAW)d&E8mMy#h diff --git a/.eip-security-token.md.icloud b/.eip-security-token.md.icloud deleted file mode 100644 index 7105ec5c52ea661f309c68983402f3f01598602e..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 171 zcmYc)$jK}&F)+By$i&RT$`<1n92(@~mzbOComv?$AOPmNW#*&?XI4RkB;Z0psm1xF zMaiill?4zf(bUWW-Qv{b(xS|gO5KwD?9@EH+!R6Xt?>dfSak)ZrkCa<7IE;)=zArl RGJpXiBZOvPhte>r1prgKFIE5m diff --git a/EIPS/.eip-3.mediawiki.icloud b/EIPS/.eip-3.mediawiki.icloud deleted file mode 100644 index 71a2a8f0a44650d50d974df7562a22cc13fb2854..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 165 zcmYc)$jK}&F)+By$i&RT$`<1n92(@~mzbOComv?$AOPmNW#*&?XI4RkB;Z0psm1xF zMaiill?4zf{?yC@U1Po6)RfG`^33c^LC&r50y0?D2c@Q$<|Gzz@XP3X#l$m!0V5-X LW?+ZXFscp!#BD5$ diff --git a/EIPS/.eip-4 2.md.icloud b/EIPS/.eip-4 2.md.icloud deleted file mode 100644 index 88bb6cc2d770a6edf3e96dba4378e9de8461d470..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 158 zcmYc)$jK}&F)+By$i&RT$`<1n92(@~mzbOComv?$AOPmNW#*&?XI4RkB;Z0psm1xF zMaiill?5QFsMO2?T@wW(z1$Q*p7MAB8LSF}QqxOw5{o$aW%Rv5BN)Jdkr6^OutRAW GRSp0nv?+)H diff --git a/EIPS/.eip-4 3.md.icloud b/EIPS/.eip-4 3.md.icloud deleted file mode 100644 index 8598690b5447e33c652648b5f3d9da2aaad2d271..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 158 zcmYc)$jK}&F)+By$i&RT$`<1n92(@~mzbOComv?$AOPmNW#*&?XI4RkB;Z0psm1xF zMaiill?5QFsMO2?T@wXkz1$Q*p7MAB8LSF}QqxOw5{o$aW%Rv5BN)Jdkr6^OutRAW GRSp0o0V#<9 diff --git a/EIPS/.eip-token_validation 2.md.icloud b/EIPS/.eip-token_validation 2.md.icloud deleted file mode 100644 index 1ebce2b54de269ca2b55902d9bbc9b50e8813998..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 175 zcmYc)$jK}&F)+By$i&RT$`<1n92(@~mzbOComv?$AOPmNW#*&?XI4RkB;Z0psm1xF zMaiill?4zf$<)jO-IDz5)V%nz#GK5O#FEVXJOv}Y+!R3xn|J{ktU7~I(@S#_i#YgY V^u5wD8Nh&%5kfPtLunY*0RS0KFfjlC diff --git a/EIPS/.eip-token_validation.md.icloud b/EIPS/.eip-token_validation.md.icloud deleted file mode 100644 index 262b11b4d8f509f982f1580ae1bfcc8a45cd1a8c..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 173 zcmYc)$jK}&F)+By$i&RT$`<1n92(@~mzbOComv?$AOPmNW#*&?XI4RkB;Z0psm1xF zMaiill?4zf@zl%$-IDz5)V%nz#GK5O#FEVXJiXi$K?%Kh0U50Nf>P5KfRPbGGq6Kx H7*zoPx3nu1 diff --git a/EIPS/eip-107/.authorization-locked.png.icloud b/EIPS/eip-107/.authorization-locked.png.icloud deleted file mode 100644 index 33dda5c43ca3b2922c4dd95ed9947d9991abf32c..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 174 zcmYc)$jK}&F)+By$i&RT$`<1n92(@~mzbOComv?$AOPmNW#*&?XI4RkB;Z0psm1xF zMaiill?70##L|+C{G!aN#FEVXJl&l9G7a{5;))#Ny)e{Gt@Sg1mIWu;6$B8LV1^QqxOw5{o$a WW%Rw$vlzgDkr6^OutRAW)d>K&Suw`| diff --git a/EIPS/eip-107/.authorization.png.icloud b/EIPS/eip-107/.authorization.png.icloud deleted file mode 100644 index 0f78ff1c6effd8986d72d6cb4ef1d79c906880b9..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 167 zcmYc)$jK}&F)+By$i&RT$`<1n92(@~mzbOComv?$AOPmNW#*&?XI4RkB;Z0psm1xF zMaiill?4zf!Nk&%jQpa^s>G7a{5-vaymUeTt?>dfSak%YrkCa<7IE;)=zGN_GJpXi NBZOvPhte>r0RWJUE?xit diff --git a/EIPS/eip-858/.calculations.md.icloud b/EIPS/eip-858/.calculations.md.icloud deleted file mode 100644 index 61fbc653d21d7f228acb260cd7d92074837013ed..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 165 zcmYc)$jK}&F)+By$i&RT$`<1n92(@~mzbOComv?$AOPmNW#*&?XI4RkB;Z0psm1xF zMaiill?4zf{^Z1*#4~^aBO`=n KV29E$sty3}H!TVP diff --git a/EIPS/eip-EIPS/.eip-616.md.icloud b/EIPS/eip-EIPS/.eip-616.md.icloud deleted file mode 100644 index d32046ec0a817237cc890b63cfb862d54001bea8..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 158 zcmYc)$jK}&F)+By$i&RT$`<1n92(@~mzbOComv?$AOPmNW#*&?XI4RkB;Z0psm1xF zMaiill?5QFsMO2?T{A;7z1$Q*m8 Date: Sun, 29 Apr 2018 21:17:55 -0700 Subject: [PATCH 06/31] Make Jekyll happy? --- EIPS/eip-status-codes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index 8f144ddaf004c5..432578197980ff 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -1,5 +1,5 @@ --- -eip: +eip: 000 title: Status Codes author: Brooklyn Zelenka (@expede) , Tom Carchrae (@carchrae) , Gleb Naumenko (@naumenkogs) status: Draft From 26507697e3ce5299e20bee492771c44769e05c71 Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Sun, 29 Apr 2018 22:35:16 -0700 Subject: [PATCH 07/31] Tweak one word --- EIPS/eip-status-codes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index 432578197980ff..0b0db9354dc1e5 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -48,7 +48,7 @@ and there's no reason that ESCs couldn't be used by the EVM itself. ## Specification -This ERC specifies codes, but not the format of exchange. For instance, +This ERC specifies codes, but not the specific format of exchange. For instance, they may be returned as a single value, apart of a data structure (ex. a call stack), in a variadic return, or packed into a byte array. From 55580936015542a7c38b3d44d2da72ec7cbde3a0 Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Sun, 29 Apr 2018 23:01:25 -0700 Subject: [PATCH 08/31] Specify multiple returns --- EIPS/eip-status-codes.md | 41 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 38 insertions(+), 3 deletions(-) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index 0b0db9354dc1e5..983820f9a39904 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -48,9 +48,35 @@ and there's no reason that ESCs couldn't be used by the EVM itself. ## Specification -This ERC specifies codes, but not the specific format of exchange. For instance, -they may be returned as a single value, apart of a data structure (ex. a call stack), -in a variadic return, or packed into a byte array. +### Format + +Codes are returned as the first value of potentially multiple return values. + +```solidity +// Code only + +function isInt(uint num) public pure returns (byte status) { + return hex"01"; +} + +// Code and value + +uint8 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); + } +} +``` + +In the rare case that there a multiple codes required to express an idea, +they should be organized in asending order. ### Code Table @@ -188,6 +214,15 @@ Other schemes have been explored, including `bytes32` and `uint8`. They worked r well, but not as cleanly. `uint8` feels much closer to HTTP status codes, does not break as cleanly as a square table (256 doesn't look as nice in base 10). +### 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 variadic 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 tupples. + ### Human Readable Developers should not be required to memorize 256 codes. However, they break nicely into a table. From b832133ab497a4a1dda40631b3ec1ed1137939e4 Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Sun, 29 Apr 2018 23:06:41 -0700 Subject: [PATCH 09/31] typo --- EIPS/eip-status-codes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index 983820f9a39904..3d15739d9e29ce 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -1,7 +1,7 @@ --- eip: 000 title: Status Codes -author: Brooklyn Zelenka (@expede) , Tom Carchrae (@carchrae) , Gleb Naumenko (@naumenkogs) +author: Brooklyn Zelenka (@expede) , Tom Carchrae (@carchrae) , Gleb Naumenko (@naumenkogs) status: Draft type: Standards Track category: ERC From c3608790e5c3993ca4a2a646a4dac1dde4ac0470 Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Sun, 29 Apr 2018 23:34:12 -0700 Subject: [PATCH 10/31] 0x24 and typo --- EIPS/eip-status-codes.md | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index 3d15739d9e29ce..4c75bf0f833da3 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -80,24 +80,24 @@ they should be organized in asending order. ### Code Table -| X. Low Nibble | 0. Generic | 10. Permission | 20. Find/Match/&c | 30. Negotiation / Offers | 40. Availability | 50. | 60. | 70. | 80. | 90. | A0. | B0. | C0. | D0. | E0. Cryptography | F0. Off Chain | -|-----------------------------------|-------------------------|-------------------------------|-------------------------|----------------------------------|----------------------------------|-----|-----|-----|-----|-----|-----|-----|-----|-----|-------------------------------------|---------------------------------------------------| -| 0. Failure | 0x00 Failure | 0x10 Disallowed | 0x20 Not Found | 0x30 Other Party Disagreed | 0x40 Unavailable or Expired | | | | | | | | | | 0xE0 Decrypt Failure | 0xF0 Off Chain Failure | -| 1. Success | 0x01 Success | 0x11 Allowed | 0x21 Found | 0x31 Other Party Agreed | 0x41 Available | | | | | | | | | | 0xE1 Decrypt Success | 0xF1 Off Chain Success | -| 2. Accepted / Started | 0x02 Accepted / Started | 0x12 Requested Permission | 0x22 Match Request Sent | 0x32 Sent Offer | | | | | | | | | | | 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 | | | | | | | | | | 0xE3 Other Party Signature Required | 0xF3 Awaiting Off Chain Completion | -| 4. Action Required / Awaiting You | 0x04 Action Required | 0x14 Awaiting Your Permission | | 0x34 Awaiting Your Ratification | 0x44 Awaiting Your Availability* | | | | | | | | | | 0xE4 Your Signature Required | 0xF4 Off Chain Action Required | -| 5. | | | | | | | | | | | | | | | | | -| 6. | | | | | | | | | | | | | | | | | -| 7. | | | | | | | | | | | | | | | | | -| 8. | | | | | | | | | | | | | | | | | -| 9. | | | | | | | | | | | | | | | | | -| A. | | | | | | | | | | | | | | | | | -| B. | | | | | | | | | | | | | | | | | -| C. | | | | | | | | | | | | | | | | | -| D. | | | | | | | | | | | | | | | | | -| E. | | | | | | | | | | | | | | | | | -| F. Meta/Info | 0x0F Metadata Only | | | | | | | | | | | | | | | 0xFF Data Source is Off Chain (ie: no guarantees) | +| X. Low Nibble | 0. Generic | 10. Permission | 20. Find/Match/&c | 30. Negotiation / Offers | 40. Availability | 50. | 60. | 70. | 80. | 90. | A0. | B0. | C0. | D0. | E0. Cryptography | F0. Off Chain | +|-----------------------------------|-------------------------|-------------------------------|-----------------------------|----------------------------------|----------------------------------|-----|-----|-----|-----|-----|-----|-----|-----|-----|-------------------------------------|---------------------------------------------------| +| 0. Failure | 0x00 Failure | 0x10 Disallowed | 0x20 Not Found | 0x30 Other Party Disagreed | 0x40 Unavailable or Expired | | | | | | | | | | 0xE0 Decrypt Failure | 0xF0 Off Chain Failure | +| 1. Success | 0x01 Success | 0x11 Allowed | 0x21 Found | 0x31 Other Party Agreed | 0x41 Available | | | | | | | | | | 0xE1 Decrypt Success | 0xF1 Off Chain Success | +| 2. Accepted / Started | 0x02 Accepted / Started | 0x12 Requested Permission | 0x22 Match Request Sent | 0x32 Sent Offer | | | | | | | | | | | 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 | | | | | | | | | | 0xE3 Other Party Signature Required | 0xF3 Awaiting Off Chain Completion | +| 4. Action Required / Awaiting You | 0x04 Action Required | 0x14 Awaiting Your Permission | 0x22 Match Request Received | 0x34 Awaiting Your Ratification | 0x44 Awaiting Your Availability* | | | | | | | | | | 0xE4 Your Signature Required | 0xF4 Off Chain Action Required | +| 5. | | | | | | | | | | | | | | | | | +| 6. | | | | | | | | | | | | | | | | | +| 7. | | | | | | | | | | | | | | | | | +| 8. | | | | | | | | | | | | | | | | | +| 9. | | | | | | | | | | | | | | | | | +| A. | | | | | | | | | | | | | | | | | +| B. | | | | | | | | | | | | | | | | | +| C. | | | | | | | | | | | | | | | | | +| D. | | | | | | | | | | | | | | | | | +| E. | | | | | | | | | | | | | | | | | +| F. Meta/Info | 0x0F Metadata Only | | | | | | | | | | | | | | | 0xFF Data Source is Off Chain (ie: no guarantees) | * Unused regions are available for further extension or custom codes * You may need to scroll the tables horizontally (they're pretty wide) @@ -212,7 +212,7 @@ cast from `enum`s, and so on. Other schemes have been explored, including `bytes32` and `uint8`. They worked reasonably well, but not as cleanly. `uint8` feels much closer to HTTP status codes, -does not break as cleanly as a square table (256 doesn't look as nice in base 10). +does not break as evenly as a square table (256 doesn't look as nice in base 10). ### Multiple Returns From 6c62add80c262e2bfde8bdf3707557de44cb7a9f Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Sun, 29 Apr 2018 23:36:04 -0700 Subject: [PATCH 11/31] Typo --- EIPS/eip-status-codes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index 4c75bf0f833da3..5121be77459efb 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -61,7 +61,7 @@ function isInt(uint num) public pure returns (byte status) { // Code and value -uint8 counter; +uint8 private counter; function safeIncrement(uint8 interval) public returns (byte status, uint8 newCounter) { uint8 updated = counter + interval; From 897c1b29600d9a3fb6b46cde5e85c2f1c64f5b60 Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Sun, 29 Apr 2018 23:47:55 -0700 Subject: [PATCH 12/31] Flesh out why not bytes32 --- EIPS/eip-status-codes.md | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index 5121be77459efb..29eacc943efed7 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -210,9 +210,22 @@ and `hex"00"` for general failure. a `bytes32` (or similar) if desired. It is also easily interoperable with `uint8`, cast from `enum`s, and so on. -Other schemes have been explored, including `bytes32` and `uint8`. They worked reasonably -well, but not as cleanly. `uint8` feels much closer to HTTP status codes, -does not break as evenly as a square table (256 doesn't look as nice in base 10). +#### Alternatives + +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). + +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^4 (4.2 billion) permutations. ### Multiple Returns From aaab4d37ca1dce57b0b216136d0246e50c10b800 Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Mon, 30 Apr 2018 00:01:18 -0700 Subject: [PATCH 13/31] Better phrasing --- EIPS/eip-status-codes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index 29eacc943efed7..619ca9c6636441 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -230,7 +230,7 @@ or greater resorces allocated to interpreting 256^4 (4.2 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 variadic return. +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, From 3165d52acdc289c964ec17ffc35b753d274f827f Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Mon, 30 Apr 2018 19:58:11 -0700 Subject: [PATCH 14/31] Empty space section --- EIPS/eip-status-codes.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index 619ca9c6636441..0a23ca087956c7 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -256,6 +256,12 @@ The EVM also returns a status code in transactions; specifically `0x00` and `0x0 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. + ## Implementation Reference cases and helper library can be found [here](https://github.com/Finhaven/EthereumStatusCodes) From 1b1b3f16f79e4dce969d578d4c1e2cdf3737179d Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Thu, 3 May 2018 22:38:27 -0700 Subject: [PATCH 15/31] Add simple example --- EIPS/eip-status-codes.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index 0a23ca087956c7..21cd689825f932 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -19,6 +19,31 @@ in the same vein as HTTP statuses. This provides a shared contextual language to allow smart contracts to react to situations autonomously, expose localized error messages to users, and so on. +```solidity +uint256 private startTime; +mapping(address => uint) private counters; + +// Before +function increase() public returns (bool _available) { + if (now < startTime && counters[msg.sender] == 0) { + return false; + }; + + counters[msg.sender] += 1; + return true; +} + +// After +function increase() pubilic returns (byte _status) { + if (now < start) { return hex"43"; } // Not yet available + if (counters[msg.sender] == 0) { return hex"10"; } // Not authorized + + counters[msg.sender] += 1; + return hex"01"; // Success +} + +``` + ## Motivation ### Autonomy From 7a116cbf0961100407c8e24d91138d41c662e8c0 Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Thu, 3 May 2018 23:11:29 -0700 Subject: [PATCH 16/31] Minor rename --- EIPS/eip-status-codes.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index 21cd689825f932..7b14b67399440e 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -107,12 +107,12 @@ they should be organized in asending order. | X. Low Nibble | 0. Generic | 10. Permission | 20. Find/Match/&c | 30. Negotiation / Offers | 40. Availability | 50. | 60. | 70. | 80. | 90. | A0. | B0. | C0. | D0. | E0. Cryptography | F0. Off Chain | |-----------------------------------|-------------------------|-------------------------------|-----------------------------|----------------------------------|----------------------------------|-----|-----|-----|-----|-----|-----|-----|-----|-----|-------------------------------------|---------------------------------------------------| -| 0. Failure | 0x00 Failure | 0x10 Disallowed | 0x20 Not Found | 0x30 Other Party Disagreed | 0x40 Unavailable or Expired | | | | | | | | | | 0xE0 Decrypt Failure | 0xF0 Off Chain Failure | +| 0. Failure | 0x00 Failure | 0x10 Disallowed | 0x20 Not Found | 0x30 Other Party Disagreed | 0x40 Unavailable | | | | | | | | | | 0xE0 Decrypt Failure | 0xF0 Off Chain Failure | | 1. Success | 0x01 Success | 0x11 Allowed | 0x21 Found | 0x31 Other Party Agreed | 0x41 Available | | | | | | | | | | 0xE1 Decrypt Success | 0xF1 Off Chain Success | -| 2. Accepted / Started | 0x02 Accepted / Started | 0x12 Requested Permission | 0x22 Match Request Sent | 0x32 Sent Offer | | | | | | | | | | | 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 | | | | | | | | | | 0xE3 Other Party Signature Required | 0xF3 Awaiting Off Chain Completion | -| 4. Action Required / Awaiting You | 0x04 Action Required | 0x14 Awaiting Your Permission | 0x22 Match Request Received | 0x34 Awaiting Your Ratification | 0x44 Awaiting Your Availability* | | | | | | | | | | 0xE4 Your Signature Required | 0xF4 Off Chain Action Required | -| 5. | | | | | | | | | | | | | | | | | +| 2. Accepted / Started | 0x02 Accepted / Started | 0x12 Requested Permission | 0x22 Match Request Sent | 0x32 Sent Offer | 0x42 You May Begin | | | | | | | | | | 0xE2 Signed | 0xF2 Off Chain Process Started | +| 3. Awaiting / Before | 0x03 Awaiting / Before | 0x13 Awaiting Permission | 0x23 Awaiting Match | 0x33 Awaiting Their Ratification | 0x43 Not Yet Available | | | | | | | | | | 0xE3 Other Party Signature Required | 0xF3 Awaiting Off Chain Completion | +| 4. Action Required | 0x04 Action Required | 0x14 Awaiting Your Permission | 0x24 Match Request Received | 0x34 Awaiting Your Ratification | 0x44 Awaiting Your Availability* | | | | | | | | | | 0xE4 Your Signature Required | 0xF4 Off Chain Action Required | +| 5. Expired | 0x05 Expired | 0x15 No Longer Allowed | 0x25 Out of Range | 0x35 Offer Expired | 0x45 No Longer Available | | | | | | | | | | | | | 6. | | | | | | | | | | | | | | | | | | 7. | | | | | | | | | | | | | | | | | | 8. | | | | | | | | | | | | | | | | | From 3585e9633bcb45ef49e351774f1a250bd75cdc90 Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Fri, 4 May 2018 15:15:59 -0700 Subject: [PATCH 17/31] Typo --- EIPS/eip-status-codes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index 7b14b67399440e..9ef2ae577e7523 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -105,14 +105,14 @@ they should be organized in asending order. ### Code Table -| X. Low Nibble | 0. Generic | 10. Permission | 20. Find/Match/&c | 30. Negotiation / Offers | 40. Availability | 50. | 60. | 70. | 80. | 90. | A0. | B0. | C0. | D0. | E0. Cryptography | F0. Off Chain | +| X. Low Nibble | 0. Generic | 10. Permission | 20. Find/Match/&c | 30. Negotiation / Offers | 40. Availability | 50. | 60. | 70. | 80. | 90. | A0. | B0. | C0. | D0. | E0. Cryptography & Tokens | F0. Off Chain | |-----------------------------------|-------------------------|-------------------------------|-----------------------------|----------------------------------|----------------------------------|-----|-----|-----|-----|-----|-----|-----|-----|-----|-------------------------------------|---------------------------------------------------| | 0. Failure | 0x00 Failure | 0x10 Disallowed | 0x20 Not Found | 0x30 Other Party Disagreed | 0x40 Unavailable | | | | | | | | | | 0xE0 Decrypt Failure | 0xF0 Off Chain Failure | | 1. Success | 0x01 Success | 0x11 Allowed | 0x21 Found | 0x31 Other Party Agreed | 0x41 Available | | | | | | | | | | 0xE1 Decrypt Success | 0xF1 Off Chain Success | | 2. Accepted / Started | 0x02 Accepted / Started | 0x12 Requested Permission | 0x22 Match Request Sent | 0x32 Sent Offer | 0x42 You May Begin | | | | | | | | | | 0xE2 Signed | 0xF2 Off Chain Process Started | | 3. Awaiting / Before | 0x03 Awaiting / Before | 0x13 Awaiting Permission | 0x23 Awaiting Match | 0x33 Awaiting Their Ratification | 0x43 Not Yet Available | | | | | | | | | | 0xE3 Other Party Signature Required | 0xF3 Awaiting Off Chain Completion | | 4. Action Required | 0x04 Action Required | 0x14 Awaiting Your Permission | 0x24 Match Request Received | 0x34 Awaiting Your Ratification | 0x44 Awaiting Your Availability* | | | | | | | | | | 0xE4 Your Signature Required | 0xF4 Off Chain Action Required | -| 5. Expired | 0x05 Expired | 0x15 No Longer Allowed | 0x25 Out of Range | 0x35 Offer Expired | 0x45 No Longer Available | | | | | | | | | | | | +| 5. Expired | 0x05 Expired | 0x15 No Longer Allowed | 0x25 Out of Range | 0x35 Offer Expired | 0x45 No Longer Available | | | | | | | | | | 0xE5 Token Expired | 0xF5 Off Chain Service Unavailable | | 6. | | | | | | | | | | | | | | | | | | 7. | | | | | | | | | | | | | | | | | | 8. | | | | | | | | | | | | | | | | | From cf25108762f3da703ee98df72a76cd52883931e3 Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Fri, 4 May 2018 15:17:59 -0700 Subject: [PATCH 18/31] Fancier --- EIPS/eip-status-codes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index 9ef2ae577e7523..7622c6662136f0 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -250,7 +250,7 @@ pack four codes at once, and there is a challenge in ensuring that code combinat 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^4 (4.2 billion) permutations. +or greater resorces allocated to interpreting 2564 (4.2 billion) permutations. ### Multiple Returns From b102de61fb52a05f64b73ae1924ac63767ccf2d5 Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Fri, 4 May 2018 15:18:45 -0700 Subject: [PATCH 19/31] Typo --- EIPS/eip-status-codes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index 7622c6662136f0..e482b7f875356f 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -250,7 +250,7 @@ pack four codes at once, and there is a challenge in ensuring that code combinat 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.2 billion) permutations. +or greater resorces allocated to interpreting 2564 (4.3 billion) permutations. ### Multiple Returns From c299c9615b69a569e52ef98983bcb24eea0559d0 Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Fri, 4 May 2018 16:04:57 -0700 Subject: [PATCH 20/31] Move code example, add expolanitory abstract text --- EIPS/eip-status-codes.md | 57 ++++++++++++++++++++++------------------ 1 file changed, 31 insertions(+), 26 deletions(-) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index e482b7f875356f..89c290fdd17d28 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -16,33 +16,12 @@ Broadly applicable status codes for Ethereum smart contracts. This standard provides a common set of Ethereum status codes (ESC) in the same vein as HTTP statuses. This provides a shared contextual language -to allow smart contracts to react to situations autonomously, -expose localized error messages to users, and so on. +to allow smart contracts to react to situations autonomously, expose localized +error messages to users, and so on. -```solidity -uint256 private startTime; -mapping(address => uint) private counters; - -// Before -function increase() public returns (bool _available) { - if (now < startTime && counters[msg.sender] == 0) { - return false; - }; - - counters[msg.sender] += 1; - return true; -} - -// After -function increase() pubilic returns (byte _status) { - if (now < start) { return hex"43"; } // Not yet available - if (counters[msg.sender] == 0) { return hex"10"; } // Not authorized - - counters[msg.sender] += 1; - return hex"01"; // Success -} - -``` +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 to reverting with a reason, +but aimed at automation and translation. ## Motivation @@ -127,6 +106,32 @@ they should be organized in asending order. * Unused regions are available for further extension or custom codes * You may need to scroll the tables horizontally (they're pretty wide) +### Example Function Change + +```solidity +uint256 private startTime; +mapping(address => uint) private counters; + +// Before +function increase() public returns (bool _available) { + if (now < startTime && counters[msg.sender] == 0) { + return false; + }; + + counters[msg.sender] += 1; + return true; +} + +// After +function increase() pubilic returns (byte _status) { + if (now < start) { return hex"43"; } // Not yet available + if (counters[msg.sender] == 0) { return hex"10"; } // Not authorized + + counters[msg.sender] += 1; + return hex"01"; // Success +} +``` + ### Example Sequence Diagrams ``` From f39e657bd7d2110a6e6dd20781ed16e4057bf9ed Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Fri, 4 May 2018 16:16:14 -0700 Subject: [PATCH 21/31] Tweak naming --- EIPS/eip-status-codes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index 89c290fdd17d28..3a654970d0d957 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -57,13 +57,13 @@ and there's no reason that ESCs couldn't be used by the EVM itself. Codes are returned as the first value of potentially multiple return values. ```solidity -// Code only +// Status only function isInt(uint num) public pure returns (byte status) { return hex"01"; } -// Code and value +// Status and value uint8 private counter; From a74b8c60f674f415bff60596c165d267518d2c93 Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Fri, 4 May 2018 20:36:12 -0700 Subject: [PATCH 22/31] Feels awkward, may Tom can rephrase? --- EIPS/eip-status-codes.md | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index 3a654970d0d957..9fab6501ccae44 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -14,14 +14,25 @@ Broadly applicable status codes for Ethereum smart contracts. ## Abstract -This standard provides a common set of Ethereum status codes (ESC) -in the same vein as HTTP statuses. This provides a shared contextual language -to allow smart contracts to react to situations autonomously, expose localized -error messages to users, and so on. +This standard outlines a set of Ethereum status codes (ESC) in the same vein +as HTTP statuses. This provides a shared contextual language 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 to reverting with a reason, -but aimed at automation and translation. +or return a Boolean pass/fail status. Status codes are similar to reverting with a reason, +and events, but are aimed at on-chain automation and translation. + +While clearly related, status codes are orthogonal 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 represt off-chain conditions, +supply a string to `revert`, signal time delays, and more. + +Much like HTTP codes, 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 and rolling back state. ## Motivation @@ -38,7 +49,7 @@ 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, +ESCs convey a much richer set of information than Booleans, and are able to be reacted to autonomously unlike arbitrary strings. ### User Feedback From ecf19dff4a08257bfea7ddd8333f858d6067ad5e Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Fri, 4 May 2018 20:36:52 -0700 Subject: [PATCH 23/31] Shorten --- EIPS/eip-status-codes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index 9fab6501ccae44..e6b83fe48aa4ae 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -32,7 +32,7 @@ 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 and rolling back state. +halting execution. ## Motivation From 645c95c9b692c183cbfa472e04a8c97d52710009 Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Fri, 4 May 2018 20:47:17 -0700 Subject: [PATCH 24/31] Oooh typo --- EIPS/eip-status-codes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index e6b83fe48aa4ae..7069663ed2d47f 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -24,7 +24,7 @@ and events, but are aimed at on-chain automation and translation. While clearly related, status codes are orthogonal 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 represt off-chain conditions, +known error states without halting execution. They may also represent off-chain conditions, supply a string to `revert`, signal time delays, and more. Much like HTTP codes, having a standard set of known codes has many benefits for developers. From 90cc2fac0fb3f7ca3021754ac582c20984000bdb Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Fri, 4 May 2018 20:49:58 -0700 Subject: [PATCH 25/31] Moar typo --- EIPS/eip-status-codes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index 7069663ed2d47f..7ed5b42a5f7384 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -134,7 +134,7 @@ function increase() public returns (bool _available) { } // After -function increase() pubilic returns (byte _status) { +function increase() public returns (byte _status) { if (now < start) { return hex"43"; } // Not yet available if (counters[msg.sender] == 0) { return hex"10"; } // Not authorized From 6232fe779fb1696a7dc6133849cb18bac0e21b81 Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Fri, 4 May 2018 21:01:37 -0700 Subject: [PATCH 26/31] Shorten --- EIPS/eip-status-codes.md | 33 ++++++++++++++++++--------------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index 7ed5b42a5f7384..693dc348234176 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -14,25 +14,21 @@ Broadly applicable status codes for Ethereum smart contracts. ## Abstract -This standard outlines a set of Ethereum status codes (ESC) in the same vein -as HTTP statuses. This provides a shared contextual language 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 Ethereum status codes (ESC) +in the same vein as HTTP statuses. This provides a shared contextual language +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 to reverting with a reason, -and events, but are aimed at on-chain automation and translation. - -While clearly related, status codes are orthogonal 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. +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 to reverting with a reason, +but aimed at automation and translation. Much like HTTP codes, 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. +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. ## Motivation @@ -61,6 +57,13 @@ differing levels of technical detail, added as `revert` messages, natspecs, and 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. +### More than Exceptions + +While clearly related, status codes are orthogonal 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. + ## Specification ### Format From 851075da017490a0a8e6ce38a2f158aca7fecb4b Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Fri, 4 May 2018 21:04:02 -0700 Subject: [PATCH 27/31] Tighen up --- EIPS/eip-status-codes.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index 693dc348234176..0a04aaa031acd0 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -14,13 +14,13 @@ Broadly applicable status codes for Ethereum 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 contextual language +This standard outlines a common set of Ethereum status codes (ESC) in the same +vein as HTTP statuses. This provides a shared sety of contextual 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 to reverting with a reason, +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 to `revert`ing with a reason, but aimed at automation and translation. Much like HTTP codes, having a standard set of known codes has many benefits for developers. From a5ec5deeae8936a27253bf69abb918659bfb341b Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Fri, 4 May 2018 21:14:33 -0700 Subject: [PATCH 28/31] Typo --- EIPS/eip-status-codes.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index 0a04aaa031acd0..e00e5683a97876 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -15,9 +15,8 @@ Broadly applicable status codes for Ethereum 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 sety of contextual signals -to allow smart contracts to react to situations autonomously, -expose localized error messages to users, and so on. +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. 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 to `revert`ing with a reason, From bf38a94bd9ea45e992130ae105cb8f5ee2b2149c Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Fri, 4 May 2018 21:16:50 -0700 Subject: [PATCH 29/31] Stop repeating words --- EIPS/eip-status-codes.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index e00e5683a97876..0b14691cff7311 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -19,8 +19,8 @@ vein as HTTP statuses. This provides a shared set of signals to allow smart cont 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 to `revert`ing with a reason, -but aimed at automation and translation. +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. Much like HTTP codes, 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, @@ -56,9 +56,9 @@ differing levels of technical detail, added as `revert` messages, natspecs, and 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. -### More than Exceptions +### More than Pass/Fail -While clearly related, status codes are orthogonal to "revert with reason". +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. From da5c8a64e1b545ed35ac20d7cdd6c053d493dca7 Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Sat, 5 May 2018 10:24:41 -0700 Subject: [PATCH 30/31] Small rephrase --- EIPS/eip-status-codes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index 0b14691cff7311..0cfef6369ec725 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -22,7 +22,7 @@ The current state of the art is to either `revert` and require human interventio 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. -Much like HTTP codes, having a standard set of known codes has many benefits for developers. +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 From e913abe2f7034050fbca34f1d9d0ce046fdba565 Mon Sep 17 00:00:00 2001 From: Brooklyn Zelenka Date: Sat, 5 May 2018 13:36:04 -0700 Subject: [PATCH 31/31] captialization --- EIPS/eip-status-codes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EIPS/eip-status-codes.md b/EIPS/eip-status-codes.md index 0cfef6369ec725..23dfe38eb1c1ed 100644 --- a/EIPS/eip-status-codes.md +++ b/EIPS/eip-status-codes.md @@ -19,7 +19,7 @@ vein as HTTP statuses. This provides a shared set of signals to allow smart cont 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 +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. As is the case with HTTP, having a standard set of known codes has many benefits for developers.