Merge pull request #313 from xdrpp/dm/1-line-asset

update SEP-0011 to reflect new canonical asset format.

ecosystem/sep-0011.md

@@ -63,9 +63,10 @@ Disregarding *pseudoselector*, each *field* names a field in an [XDR `Transactio
 As an example, the *field* `tx.timeBounds.minTime` names the `minTime` field in the `tx` field of the `TransactionEnvelope` structure, which looks like this:
 
 ``` c
+typedef uint64 TimePoint;
 struct TimeBounds {
-    uint64 minTime;
-    uint64 maxTime; // 0 here means no maxTime
+    TimePoint minTime;
+    TimePoint maxTime; // 0 here means no maxTime
 };
 struct Transaction {
     /* ... */
@@ -114,15 +115,17 @@ Most XDR types are rendered using C syntax. Specifically:
 
   - `bool` values are `true` or `false`
 
-  - Enums are represented by the bare keyword of the value. They cannot be specified numerically (but omitting a line for a field is the same as specifying 0).
+  - Enums are represented by the bare keyword of the value.  They can also be specified numerically as "Type#Number" (e.g., `MemoType#3` is equivalent to `MEMO_HASH`).
 
   - `string` values are represented as double-quoted interpreted string literals, in which non-ASCII bytes are represented with hex escapes (`"\xff"`), the `"` and `\` characters can be escaped with another `\` (e.g., `"\\"`), and `\n` designates a newline.
 
-  - `opaque` values are represented as an unquoted hexadecimal string (using lower-case case `a`...`f`) with an even number of digits.  An exception is that the 0-length opaque vector is represented as "0" (a single digit).  Implementations are encouraged to add the comment bytes so that it reads "0 bytes" to further distinguish the 0-length vector from the vector with a single byte 0x00 (rendered "00").
+  - `opaque` values are represented as an unquoted hexadecimal string (using lower-case case `a`...`f`) with an even number of digits.  An exception is that the 0-length opaque vector is represented as "0" (a single digit).  Implementations are encouraged to add the comment "bytes" so that it reads "0 bytes" to further distinguish the 0-length vector from the vector with a single byte 0x00 (rendered "00").
 
 A few aggregate values are special-cased:
 
-  - The `AssetCode` field in `Assets` is rendered as ASCII bytes (not surrounded by double-quotes). Non-printable characters and non-ASCII bytes (including space, to avoid a space being interpreted as part of a comment) are hex escaped (`\xff`), while backslash is self-escaped (`\\`).  Note that stellar-core disallows non ASCII bytes in `AssetCode` fields, so the primary use of this feature is to construct or examine invalid transaction test cases.
+  - The `Asset` type is rendered as `NATIVE` (or any string up to 12 characters not containing an unescaped colon) for the native asset, and a string of the form "Code:IssuerAccountID" for issued assets.  "Code" must consist of printable ASCII characters (octets 0x21 through 0x7e).  The sequence `\x` introduces a hex escape sequence, e.g., `\x00` to introduce a 0-valued byte.  Otherwise, `\` escapes the next character, so `\\` is required to introduce a backslash.  Stellar disallows assets of type `ASSET_TYPE_CREDIT_ALPHANUM12` that have fewer than 5 bytes, such assets can be represented in binary XDR, and so in txrep are rendered with trailing `\x00` (escaped NUL bytes) to as to make the length 5---e.g., the 12-byte asset code `ABC` is rendered `ABC\x00\x00`.
+
+  - The `asset` field of `AllowTrustOp` is rendered the same as the Code in `Asset`, only without the trailing ":IssuerAccountID" (since the issuer is the `sourceAccount` of the operation).
 
   - `PublicKey` and `SignerKey` are rendered as unquoted strings in strkey format, described below.
 
@@ -163,6 +166,12 @@ Fields in txrep are specified in an order-independent way. If a field appears tw
 
   - Pseudo-fields must appear immediately before the values they affect. In particular, the `ptr._present: true` field must appear immediately before the value of `ptr`, and `vector.len` must appear immediately before `vector[0]`.
 
+  - Codes in `Asset` and `AllowTrustOp` should escape `\`, `:` and any byte outside the range 0x21-0x7e, but no other bytes.  Trailing `\x00` should not be shown except as needed to show an asset of type `ASSET_TYPE_CREDIT_ALPHANUM12` fewer than 5 non-zero bytes.
+
+  - Enums must be shown as their symbolic value, rather than "Type#Number", unless there is no symbolic value.
+
+  - The native asset should be rendered as `XLM` for the Stellar public network, `TestXLM` for the Stellar test network, and, in the absence of a convention for any other network, `NATIVE`.
+
 One possible use of non-normalized txrep is to allow users discover missing fields.  A tool that allows users to construct transactions in txrep format can translate the transactions to normalized format to highlight any missing fields along with their default values.  In contexts where users should not leave any fields missing, tools can refuse to accept non-normalized txrep.
 
 ## Rationale