PIP-0027: improvements for E-PASA readability, conciseness and cosmetic appeal

PIP/PIP-0027.md

@@ -29,81 +29,97 @@ Layer-2 addresses will be herein referred to as Extended PASA, or E-PASA for sho
 
 An Extended PASA is defined by the below EBNF grammar:
 
-    EPASA          = PASA [ExtensionSpec]  
-    PASA            = Integer-Checksum
-    Checksum        = Integer
-    ExtensionSpec   = "[" Payload "]" [PayloadChecksum] 
-    Payload         = PayloadType EncryptionType "-" PayloadContent
-    PayloadType     = "H" | "B" | "A"
-    EncryptionType  = "N" | "S" | "R" | "P" Password
-    Password        = "!"" ASCII-String "!"
-    PayloadContent  = HexPayload | Base58Payload | ASCIIPayload
-    PayloadChecksum = ":" Integer
-    HexPayload      = "0" "x" HEXADECIMAL-String
-    Base58Payload   = BASE58-String
-    ASCIIPayload    = "'" ASCII-String "'"
-
-The above rules are explained as follows:
-
-| Rule            | Explanation                                                                                              |
-| --------------: | :------------------------------------------------------------------------------------------------------- |
-| EPASA           | This is a layer-2 address, fully backwards compatible as Layer-1 address                                 |
-| PASA            | This is the standard layer-1 address of an account                                                       |
-| Checksum        | This is the standard layer-1 address checksum                                                            |
-| ExtensionSpec   | The specification of the extended PASA portion (payload, how to encrypt, etc)                            |
-| Payload         | The fully qualified payload                                                                              |
-| PayloadType     | The format the payload will be specified in (H = Hex, B = Base58, A = ASCII)                             |
-| EncryptionType  | The type of encryption used on the payload (N = None, S = Senders Key, R = Recipients Key, P = password) |
-| Password        | The password used for AES256 encrypted payloads                                                          |
-| PayloadContent  | The actual payload data, specified it it's correct form                                                  |
-| PayloadChecksum | An optional 32bit MurMur3 hash of the Payload                                                            |
-| HexPayload      | A hexadecimal-encoded string used when specifying a payload in hexadecimal, prefixed with 0x             |
-| Base58Payload   | A base58 encoded string used when specifying a payload in base58                                         |
-| ASCIIPayload    | An ASCII-encoded string used when specifying a payload in ASCII                                          |
+    EPASA              = PASA, [ ExtendedAddress ] ;
+    PASA               = Integer, "-", Checksum ;
+    Checksum           = Digit, Digit ;
+    ExtendedAddress    = ( PublicPayload | ReceiverEncPayload | SenderEncPayload | PasswordEncPayload ), [ ":", PayloadChecksum ] ;
+    PublicPayload      = "[", Payload, "]" ;
+    ReceiverEncPayload = "(", Payload, ")" ;
+    SenderEncPayload   = "{", Payload, "}" ;
+    PasswordEncPayload = "<", Payload, ":", Password, ">" ;
+    Payload            = [ Pascal64String | HexString | Base58String ] ;      (* allows empty payload *)
+    PayloadChecksum    = HexDigit, HexDigit, HexDigit, HexDigit
+    Password           = HexString                                             (* force passwords to be specified in hex *)
+    Pascal64String     = Pascal64StartChar, { Pascal64Char } ;
+    Pascal64StartChar  ??= TODO
+    Pascal64Char       ??=  TODO
+    HexString          = "0", "x", HexByte { HexByte } ;
+    HexByte            = HexDigit, HexDigit
+    HexDigit           = ( 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 *)
+    Digit              = ( "0" | NaturalDigit ) ;
+    NaturalDigit       = ( "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ) ;
+
+
+| Rule               | Explanation                                                                                                   |
+| -----------------: | :------------------------------------------------------------------------------------------------------------ |
+| EPASA              | This is a layer-2 address, fully backwards compatible as Layer-1 address                                      |
+| PASA               | This is the standard layer-1 address of the receiver account                                                  |
+| Checksum           | This is the standard layer-1 address checksum                                                                 |
+| ExtendedAddress    | The optional extra text that forms part of layer-2 address (payload specification)                            |
+| PublicPayload      | A payload which is not encrypted and publically visible                                                       |
+| ReceiverEncPayload | A payload which is ICIES encrypted using receivers public key (the PASA portion specifies receiver)           |
+| SenderEncPayload   | A payload which is ICIES encrypted using the senders public key (only sender can decrypt EPASA)               |
+| PasswordEncPayload | A payload which is AES256 encrypted using the specified password                                              |
+| Payload            | The actual payload data, specified it an well-defined encoding                                                |
+| PayloadChecksum    | An UINT16 specified by two hexbytes (4 hexdigits) that denotes a checksum of payload, used to ensure payload consistency (prevents typo/copy-paste errors)  |
+| Password           | The password used in PasswordEndPayload. Must be specified as a hexadecimal string                            |
+| Pascal64String     | A Pascal64-encoded string. This encoding also used for specifying Account Names.                              |
+| Base58String       | A Base58-encoded string. This is used for specifying public keys, and hashes of public keys                   |
+| HexString          | A hexadecimal-encoded string prefixed with a 0x. Every byte specified by two hexdigits, lower-case            |
 
 #### Payload Checksumming
 
 In order to avoid data entry errors, the payload portion is **optionally** checksummed. The payload checksum is calculated as follows:
 
 ```
-    PayloadChecksum = Format-As-4-Digit-Number(  MurMur3( Payload.ToString  ) MOD 10000 )
+    PayloadChecksum = ToHexString( MurMur3( PayloadEncType ++ Payload ) MOD 65536 )
+
+    PayloadEncType  = "0" for PublicPayload
+                    = "1" for ReceiverEncPayload
+                    = "2" for SenderEncPayload
+                    = "3" for PasswordEncPayload
+       
 ```
 
-The MurMur3 used here is the 32bit version. The hash digest is **Payload** portion of the E-PASA inASCII form (i.e. the text between square brackets). The Checksum by convention is padded to 4 digits and it's range constrained to 0000 - 9999.
+The MurMur3 used here is the 32bit version. The hash digest is **Payload** portion of the E-PASA in it's ASCII form, not it's binary form. The Checksum will always be 4 hexadecimal digits and numerically ranged to 0 - 65535.
 
 ## Examples
 
 ### Example 1 
 
 ```
-123456-77[HN0x12ab3f] 
+123456-77[0x12ab3f]:10cb 
 ```
 
-- Address is '123456-77'
+- Receiver address is '123456-77'
 - Payload is the hexadecimal string 0x12ab3f
-- Payload is not encrypted (public)
-- No payload checksum included
+- Payload is public (not encrypted)
+- Payload checksum is 10cb
 
 **Note**
- - To encrypt using senders key, address would be ```123456-77[HS0x12ab3f]```.
- - To encrypt using recipients key, address would be ```123456-77[HR0x12ab3f]```.
- - To encrypt using password "Alpha$", address would be ```123456-77[HP!Alpha$!0x12ab3f]```.
- - To add a checksum, address would be ```123456-77[HN0x12ab3f]:9876```
+ - To encrypt using senders key, address would be ```123456-77{0x12ab3f}:19de```.
+ - To encrypt using recipients key, address would be ```123456-77(0x12ab3f):bf91```.
+ - To encrypt using password "Alpha$", address would be ```123456-77<0x12ab3f:0x416c70686124>:dd32``` noting password converted into hex encoding.
 
+ 
 
 ### Example 2: 
 
 ```
-77-44[AN'[email protected]']:1234 
+77-44["[email protected]"]:1234 
 ```
 
-- Layer-1 address is '77-44'
-- Payload is the ASCII string "[email protected]"
+- Recipient address is '77-44'
+- Payload is the Pascal64 string "[email protected]"
 - Payload is not encrypted (public)
 - Payload checksum is "1234"
 
 **NOTE**
-- By using recipients key, ```77-44[AR'[email protected]']:5678``` exchanges could use such addresses to accept users deposits easily, via a single address per user.
+- By using recipients key, ```77-44("[email protected]"):5bd8``` exchanges could use such addresses to accept users deposits easily, via a single address per user.
 
 ## Rationale