PIP-0027: refactor as addressing-scheme for infinite address-space

PIP/PIP-0027.md

@@ -1,8 +1,8 @@
 <pre>
   PIP: PIP-0027
-  Title: E-PASA: Layer-2 Addresses
-  Type: Frontend
-  Impact: None
+  Title: E-PASA: Infinite Address-Space (via Layer-2)
+  Type: Protocol, Front-End
+  Impact: Hard-Fork
   Author: Herman Schoenfeld <[email protected]>
   Comments-URI: https://discord.gg/sJqcgtD  (channel #pip-0027)
   Status: Proposed
@@ -11,50 +11,63 @@
 
 ## Summary
 
-This PIP proposes a backwards compatible addressing scheme to facilitate Layer-2 addresses as well as improve current Layer-1 payments and general usage.
+This PIP proposes a backwards compatible addressing scheme that enables an infinite address-space within PascalCoin. The usage of these extension addresses can be employed within existing infrastructure such as wallets and exchanges now as well as future Layer-2 dapps.
 
 ## Motivation
 
-PascalCoin current allows users to send/receive operations between accounts using their account numbers (PASA) as a reference. These account numbers are typically post-fixed with a checksum to avoid data entry errors. 
+PascalCoin currently allows users to send/receive operations between accounts using their account numbers (PASA). 
 
-This proposal extends this specification to allow the embedding of a payload to an address. This allows a recipient to specify the payload the sender must enter when sending an operation. This is useful in many current use-cases such as a merchant specifying the payload code in the buyers transaction so that he can recognize it. Also, for exchanges to specify the payload for users to deposit. By using these addresses, a single PASA can be represented in many forms. 
+These account numbers are a limited (and commoditized) resource which form a finite address-space (note: this is fundamental to SafeBox design and it's infinite-scaling capability).
 
-Most importantly, Layer-2 applications require this as an addressing scheme for Layer-2 applications. As a result, this PIP proposes a formal specification for these addresses.
+PascalCoin will provide an infinite address-space (similar toother other crypto-currencies) via "decentralized custodial accounts" which are Layer-2 dapps governed via a Layer-2 Proof-of-Stake overlay network.
+
+Before rolling out this Layer-2 infrastructure, PascalCoin first needs to establish an addressing-scheme for this infinite address-space.
+
+This PIP provides one such scheme. Additionally, this scheme can also be immediately employed at the presention-layer to greatly simplify exchange integrations and payload-based payments.
 
 ## Specification
 
 Layer-2 addresses will be herein referred to as Extended PASA, or E-PASA for short.
 
+An E-PASA has the following unique characteristics:
+* Each E-PASA is a **unique** identifier.
+* An E-PASA is encoded into the raw network payload of operations.
+* There is a 1-1 mapping between E-PASA and their raw payload form.
+  * They are deterministically dehydrated to into raw payloads.
+  * They are deterministically hydrated from raw payloads (**note**: requires V5 protocol).
+* No two fully checksummed E-PASA's can refer to the same logical address.
+
 ### Extended PASA format (E-PASA)
 
 An Extended PASA is defined by the below EBNF grammar:
 
 ```
-    EPASA              = PASA, [ ExtendedAddress ] ;
+    EPASA              = PASA, [ ExtendedAddress ], [ ':', EPASAChecksum ] ;
     PASA               = ( AccountName | AccountNumber ) ;
-    AccountName        = Pascal64String 
+    AccountName        = Pascal64String ;
     AccountNumber      = Integer, "-", Checksum ;
     Checksum           = Digit, Digit ;
-    ExtendedAddress    = ( PublicPayload | ReceiverEncPayload | SenderEncPayload | PasswordEncPayload ), [ ":", PayloadChecksum ] ;
-    PublicPayload      = "[", Payload, "]" ;
-    ReceiverEncPayload = "(", Payload, ")" ;
-    SenderEncPayload   = "<", Payload, ">" ;
-    PasswordEncPayload = "{", Payload, ":", Password, "}" ;
-    Payload            = [ """, SafeAnsiString, """ | HexString | Base58String ] ;      (* allows empty payload *)
-    PayloadChecksum    = HexByte, HexByte
+    EPASAChecksum      = HexByte, HexByte ;
+    ExtendedAddress    = ( PublicPayload | ReceiverEncPayload | SenderEncPayload | PasswordEncPayload ) ;
+    PublicPayload      = "[", [ Payload ], "]" ; 
+    ReceiverEncPayload = "(", [ Payload ], ")" ;
+    SenderEncPayload   = "<", [ Payload ], ">" ;
+    PasswordEncPayload = "{", [ Payload ], ":", [ Password ], "}" ;
+    Payload            = ( """, SafeAnsiString, """ | "0", "x", HexString | Base58String ) ;
     Password           = SafeAnsiString
     SafeAnsiString     = SafeAnsiChar, { SafeAnsiChar } ;
     SafeAnsiChar       = (" " | "!" | EscapeChar """ | "#" | "$" | "%" | "&" | "'" | "(" | ")" | "*" | "+" | "," | "-" | "." | "/" | "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | ":" | ";" | "<" | "=" | ">" | "?" | "@" | "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z" | "[" | EscapeChar "\" | "]" | "^" | "_" | "`" | "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" | "{" | "|" | EscapeChar "}" | "~") ;
-    Pascal64String     = SafePascal64Char, {Pascal64Char}
+    Pascal64String     = SafePascal64Char, { Pascal64Char } ;
     Pascal64Char       = (Digit | SafePascal64Char)
     SafePascal64Char   = ( "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z", "!", "@", "#", "$", "%", "^", "&", "*", "(", ")", "-", "+", "{", "}", "[", "]", "_", ":", "`", "|", "<", ">", ",", ".", "?", "/", "~", ")" "-", "+", "{", "}", "[", "]", "_", ":", "`", "|", "<", ">", ",", ".", "?", "/", "~" ) ; 
-    HexString          = "0", "x", HexByte { HexByte } ;
+    HexString          = HexByte { HexByte } ;
     HexByte            = HexNibble, HexNibble ;
     HexNibble          = ( Digit | "a" | "b" | "c" | "d" | "e" | "f" ) ;       (* no uppercase hex allowed *)
     Base58String       = Base58Char, { Base58Char } ;
     Base58Char         = ( NaturalDigit | Base58UpperChar | Base58LowerChar ) ; 
     Base58UpperChar    = ( "A", "B", "C", "D", "E", "F", "G", "H", "J", "K", "L", "M", "N", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z" ) ;     (* missing I, O *)
     Base58LowerChar    = ( "a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k", "m", "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "y", "z" ) ; (* missing l *)
+    Integer            = NaturalDigit, { Digit } ;
     Digit              = ( "0" | NaturalDigit ) ;
     NaturalDigit       = ( "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ) ;
     EscapeChar         = "\" ;
@@ -82,6 +95,7 @@ An Extended PASA is defined by the below EBNF grammar:
 **NOTES**: 
  * Text payload and passwords are restricted to ANSI charset subset range 32..126
  * The following characters **\\**, **"**, and **}** must be escaped in ASCII payloads/AES passwords via preceding **\\**
+ * Payload content is 
 
 #### Validation Rules
 
@@ -95,30 +109,32 @@ Layer-1 account checkum must be the following number:
 
 **NOTE** AccountNumber above denotes the integer portion of the string.
 
+**IMPORTANT**: Whilst the E-PASA grammar allows optional PASA checksum, this is purely for convenience. Implementations are expected to automatically fill-in the checksum if not specified in the input.
+
 #### Pascal64String 
 
 These strings are used to denote an account names and conform to the following rules.
 - By definition, they must **not** start with a digit. 
 - String length must between 3..64 inclusive.
 
-#### Payload Checksum
+#### E-PASA Checksum
+
+In order to avoid data entry errors, the EPASA is checksummed. In short, the E-PASA checksum is simply the 16-bit MurMur3 hash of all preceding text. 
 
-In order to avoid data entry errors, the payload portion is **optionally** checksummed. The payload checksum is calculated as follows:
+Formally, the EPASA checksum is defined as follows:
 
 ```
-    PayloadChecksum = ToHexStringLE ( CastToUINT16( MurMur3( ToAsciiBytes ( PayloadEncType ++ Payload ) ) MOD 65536 ) )
+    PayloadChecksum = ToHexStringLE ( CastToUINT16( MurMur3( ToAsciiBytes ( PASA ++ ExtendedAddress ) ) MOD 65536 ) )
 
     where
-       PayloadEncType  = "1" for PublicPayload
-                       = "2" for ReceiverEncPayload
-                       = "3" for SenderEncPayload
-                       = "4" for PasswordEncPayload
        ToAsciiBytes    = converts ASCII string argument into raw byte form, character by character (no endianness concerns here)                
        MurMur3         = performs 32bit MurMur3 hash of the byte array argument                
        CastToUINT16    = casts the integer argument into to a 16bit unsigned integer (should never overflow due to modulo 65536)
        ToHexStringLE   = converts the 16bit unsigned integer argument into 4 hexadecimal characters in little-endian
 ```
 
+**IMPORTANT**: Whilst the E-PASA grammar allows optional E-PASA checksums, this is purely for convenience. Implementations are expected to automatically fill-in the checksum if not specified in the input.
+
 #### Payload Lengths
 
 The following validation rules must be applied to Payload lengths
@@ -136,14 +152,64 @@ The following validation rules must be applied to Payload lengths
 | Base58               | AES              | 223                 | 304                        |
 
 **NOTE:** +2 accounts for "0x" prefix for hexadecimal strings
- 
+
+#### Payload Type
+
+In order for an operation receiver to **automatically decode** an E-PASA from the raw network payload in the **exact same form** that it was entered by the sender, an additional *PayloadType* field is required for all operations that carry a Payload.
+
+The PayloadType indicates how the raw network payload was encrypted and has general-purposes usage beyond this PIP.
+
+For E-PASA, the PayloadType allows the receiver to deterministically and unambiguously derive the E-PASA used by the sender, including the encryption type and payload type (i.e. ascii/hex/base58) as well as if an account name was used instead of an account number.
+
+This capability is fundamental for using E-PASA as an *address-space* in Layer-2 applications. Without this, a Layer-2 application could decode a single raw network payload in a multitude of E-PASA forms breaking the 1-1 relationship necessary to establish uniqueness.
+
+#### Payload Type Specification:
+
+| Value    | Interpretation                                                                  |
+| -------: | :------------------------------------------------------------------------------ |
+| 00000000 | Non-deterministic (requires manual decoding by receiver and **not** an E-PASA)  |
+| 00000001 | Public payload (E-PASA shows empty payload)                                     |
+| 00000010 | ECIES-Sender encrypted payload (E-PASA shows empty payload)                     |
+| 00000100 | ECIES-Receiver encrypted payload (E-PASA shows empty payload)                   |
+| 00001000 | AES encrypted payload (E-PASA shows empty payload)                              |
+| 00010001 | Public payload in ASCII encoding                                                |
+| 00010010 | ECIES-Sender encrypted payload in ASCII encoding                                |
+| 00010100 | ECIES-Receiver encrypted payload in ASCII encoding                              |
+| 00011000 | AES encrypted payload in ASCII encoding                                         |
+| 00100001 | Public payload in hexadecimal encoding                                          |
+| 00100010 | ECIES-Sender encrypted payload in hexadecimal encoding                          |
+| 00100100 | ECIES-Receiver encrypted payload in hexadecimal encoding                        |
+| 00101000 | AES encrypted payload in hexadecimal encoding                                   |
+| 01000001 | Public payload in Base58 encoding                                               |
+| 01000010 | ECIES-Sender encrypted payload in Base58 encoding                               |
+| 01000100 | ECIES-Receiver encrypted payload in Base58 encoding                             |
+| 01001000 | AES encrypted payload in Base58 encoding                                        |
+| 10000000 | Non-deterministic (E-PASA shows Account Name)                                   |
+| 10000001 | Public payload (E-PASA shows Account Name and empty payload)                    |
+| 10000010 | ECIES-Sender encrypted payload (E-PASA shows AccountName and empty payload)     |
+| 10000100 | ECIES-Receiver encrypted payload (E-PASA shows AccountName and empty payload)   |
+| 10001000 | AES encrypted payload (E-PASA uses AccountName and empty payload)               |
+| 10010001 | Public payload in ASCII encoding (E-PASA shows Account Name)                    |
+| 10010010 | ECIES-Sender encrypted payload in ASCII encoding (E-PASA shows Account Name)    |
+| 10010100 | ECIES-Receiver encrypted payload in ASCII encoding (E-PASA shows Account Name)  |
+| 10011000 | AES encrypted payload in ASCII encoding (E-PASA shows AccountName)              |
+| 10100001 | Public payload in hexadecimal encoding (E-PASA shows AccountName)               |
+| 10100010 | ECIES-Sender encrypted payload in hexadecimal encoding (E-PASA shows AccountName)|
+| 10100100 | ECIES-Receiver encrypted payload in hexadecimal encoding (E-PASA shows AccountName)|
+| 10101000 | AES encrypted payload in hexadecimal encoding (E-PASA shows AccountName)        |
+| 11000001 | Public payload in Base58 encoding (E-PASA shows AccountName)                    |
+| 11000010 | ECIES-Sender encrypted payload in Base58 encoding (E-PASA shows AccountName)    |
+| 11000100 | ECIES-Receiver encrypted payload in Base58 encoding (E-PASA shows AccountName)  |
+| 11001000 | AES encrypted payload in Base58 encoding (E-PASA shows AccountName)             |
+
+
 ## E-PASA Examples
 
 ### Base Cases 
 
 <table>
 <thread>
-    <th width="350">E-PASA</th>
+    <th width="370">E-PASA</th>
     <th>Description</th>
 </thead>
 <tbody>
@@ -214,11 +280,18 @@ The following validation rules must be applied to Payload lengths
 </thead>
 <tbody>
     <tr><td>999-72["Message with all escaped chars \\\"\} here"]</td><td>Public ANSI string <b>Message with all escaped chars \"} here</b></td></tr>
-    <tr><td>999-72[]</td><td>Empty public payload (all zeros)</td></tr>
-    <tr><td>999-72[]:10cb</td><td>Empty public payload with checksum protection</td></tr>
-    <tr><td>999-72():7ba2</td><td>ECIES encrypted empty payload using <b>recipients</b> public key</td></tr>
-    <tr><td>999-72<>:b51f</td><td>ECIES encrypted empty payload using <b>senders</b> public key</td></tr>
-    <tr><td>999-72{:Alpha1%}</td><td>AES encrypted empty payload using password <b>Alpha1%</b></td></tr> 
+    <tr><td>999-72</td><td>Non-deterministic, raw network-level payload bytes ignored</td></tr>
+    <tr><td>999-72[]</td><td>Empty Public payload, raw network-level payload bytes ignored</td></tr>
+    <tr><td>999-72()</td><td>Empty ECIES payload, raw network-level payload bytes encrypted with receivers key but ignored</td></tr>
+    <tr><td>999-72<></td><td>Empty ECIES payload, raw network-level payload bytes encrypted with senders key but ignored</td></tr>
+    <tr><td>999-72{:}</td><td>Empty AES payload, raw network-level payload bytes AES encryped but ignored</td></tr>
+    <tr><td>999-72{:pwd}</td><td>Empty AES payload, raw network-level payload bytes AES encryped with password <b>pwd</b> but ignored<b>pwd</b> but ignored</td></tr>
+    <tr><td>my-account-name</td><td>Non-deterministic, raw network-level payload bytes ignored</td></tr>
+    <tr><td>my-account-name[]</td><td>Empty public payload, raw network-level payload bytes ignored</td></tr>
+    <tr><td>my-account-name()</td><td>Empty ECIES payload, raw network-level payload bytes encrypted with receivers key but ignored</td></tr>
+    <tr><td>my-account-name<></td><td>Empty ECIES payload, raw network-level payload bytes encrypted with senders key but ignored</td></tr>
+    <tr><td>my-account-name{:}</td><td>Empty AES payload, raw network-level payload bytes encrypted with empty password but ignored</td></tr>
+    <tr><td>my-account-name{:pwd}</td><td>Empty AES payload, raw network-level payload bytes encrypted with password <b>pwd</b> but ignored</td></tr>
     <tr><td>999-72{"Hello":Funny\"Pwd}</td><td>AES encrypted using escaped password <b>Funny"Pwd</b></td></tr> 
     <tr><td>999-72{"Hello":\\\"\}}</td><td>AES encrypted using escaped password <b>\"}</b></td></tr>
 </tbody>
@@ -231,7 +304,9 @@ The design approach was to remain backwards compatible so that EPASA can replace
 
 ## Backwards Compatibility
 
-This PIP is backwards compatible and does not require a hard-fork activation, only an implementation change.
+This PIP is generally backwards compatible and does not require a hard-fork activation for using E-PASA as a convention.
+
+For Layer-2 applications the ability for a receiver to auto-decode the E-PASA via PayloadType **does require a hard-fork**  **except** although this does not prevent usage of E-PASA for other purposes.
 
 ## Acknowledgements
 * Ugochukwu Mmaduekwe for assistance developing payload length validation rules

PIP/README.md

@@ -32,6 +32,6 @@ If they wish to continue, copy [this template](PIP-template.md) and ensure your
 | [23](PIP-0023.md)     | JSON RPC PASCURRENCY format                 | Benjamin Ansbach     | Backend, Documentation | Draft |
 | [24](PIP-0024.md)     | Account Data                                | Herman Schoenfeld            | Protocol       | Draft |
 | [26](PIP-0026.md)     | URI Scheme Proposal                                | Ugochukwu Mmaduekwe            | Front-End       | Draft |
-| [27](PIP-0027.md)     | E-PASA: Layer-2 Addresses                   | Herman Schoenfeld            | Front-End       | Draft |
+| [27](PIP-0027.md)     | E-PASA: Infinite Address-Space (via Layer-2)  | Herman Schoenfeld            | Protocol, Front-End    | Draft |
 | [28](PIP-0028.md)     | E-OP: Layer-2 operation encoding standard for smart-contracts | Herman Schoenfeld            | Front-End       | Draft |