Skip to content

Commit 81a588c

Browse files
hboonhboon
authored
Tweak text formatting
1 parent 625afd3 commit 81a588c

File tree

1 file changed

+66
-51
lines changed

1 file changed

+66
-51
lines changed

‎doc/attribute-processing.md‎

Lines changed: 66 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,93 +1,106 @@
11
# Token Attributes
22

3-
A. I describe how to think of attributes and their origins and mappings as a pipeline below. A useful case to think through is a function origin which returns a GeneralisedTime (so we set as=”utf8”), but the attribute syntax is GeneralisedTime (and hence the JavaScript object is expected to be our standard JavaScript GeneralisedTime class).
3+
A. I describe how to think of attributes and their origins and mappings as a pipeline below. A useful case to think through is a function origin which returns a GeneralisedTime (so we set as="utf8"), but the attribute syntax is GeneralisedTime (and hence the JavaScript object is expected to be our standard JavaScript GeneralisedTime class).
44

5-
B. Based on this, it would be good if we add as=”address”. The matching syntax type should be IA5 String (but Directory String will work too). We can return the JavaScript object as a string or if there’s a suitable syntax that defines it as an address, we can create a simple class to wrap it (in the future?)
5+
B. Based on this, it would be good if we add as="address". The matching syntax type should be IA5 String (but Directory String will work too). We can return the JavaScript object as a string or if there's a suitable syntax that defines it as an address, we can create a simple class to wrap it (in the future?)
66

77
C. To preserve precision, Numeric Strings are stored internally as a Big Integer, but returned as a JavaScript string (unless we want to support provide or endorse a big number library. Possibly later?)
88

99
D. Note that according to https://tools.ietf.org/html/rfc4517#section-3.3.23, Numeric String is:
1010

11+
```
1112
NumericString = 1*(DIGIT / SPACE)
1213
DIGIT = %x30 / LDIGIT ; "0"-"9"
1314
LDIGIT = %x31-39 ; "1"-"9"
15+
```
1416

1517
Attribute as a pipeline:
1618

1719
One way to look at an attribute type and their origin, and (optional) mapping is as a pipeline of 2 or 3 processing stages.
1820

1921
With a mapping:
2022

21-
A. Origin output with
22-
specific type (based on
23-
Inputs with "as"). Attribute
24-
specific B. Convert to string to be value with
25-
types used as mapping's input specific
26-
─────────────▶ ┌──────────┐ ┌──────────┐ ┌──────────┐ type
27-
│ Origin │───────────▶ │ Mapping │──────────▶│ Syntax │─────────▶
28-
─────────────▶ └──────────┘ └──────────┘ └──────────┘
23+
```
24+
A. Origin output with
25+
specific type (based on
26+
Inputs with "as"). Attribute
27+
specific B. Convert to string to be value with
28+
types used as mapping's input specific
29+
─────────────▶ ┌──────────┐ ┌──────────┐ ┌──────────┐ type
30+
│ Origin │───────────▶ │ Mapping │──────────▶│ Syntax │─────────▶
31+
─────────────▶ └──────────┘ └──────────┘ └──────────┘
2932
30-
Mapping output is
31-
always a string.
33+
Mapping output is
34+
always a string.
35+
36+
37+
```
3238

3339

3440
Without mappings:
3541

36-
Inputs with Origin output with specific Attribute
37-
specific type (based on "as") value with
38-
types specific
39-
─────────────▶ ┌──────────┐ ┌──────────┐ type
40-
│ Origin │───────────▶ │ Syntax │─────────▶
41-
─────────────▶ └──────────┘ └──────────┘
42+
```
43+
Inputs with Origin output with specific Attribute
44+
specific type (based on "as") value with
45+
types specific
46+
─────────────▶ ┌──────────┐ ┌──────────┐ type
47+
│ Origin │───────────▶ │ Syntax │─────────▶
48+
─────────────▶ └──────────┘ └──────────┘
49+
50+
4251
52+
```
4353

54+
1. Each stage has 0 or 1 input (or in the case of function origins, 0 or more inputs) and 1 output
4455

45-
Each stage has 0 or 1 input (or in the case of function origins, 0 or more inputs) and 1 output
56+
2. All input and output are typed.
4657

47-
All input and output are typed.
58+
3. Ethereum function origins
4859

49-
Ethereum function origins
50-
A ethereum function origin’s input types are already specified as Solidity types, eg. <ts:address>
60+
1. A ethereum function origin's input types are already specified as Solidity types, eg. `<ts:address>`
61+
2. Ethereum function origin's output type are specified with `as`, with each possible value mapping to exactly 1 Solidity type. Specifically:
5162

52-
Ethereum function origin’s output type are specified with as, with each possible value mapping to exactly 1 Solidity type. Specifically:
53-
as=”uint” => uint256
54-
as=”int” => int256
55-
as=”utf8” => string
56-
as=”e18” => uint256
57-
as=”bool” => bool
63+
* as="uint" => uint256
64+
* as="int" => int256
65+
* as="utf8" => string
66+
* as="e18" => uint256
67+
* as="bool" => bool
5868

59-
This type mapping is used to interpret (and validate) the smart contract function call return value.
69+
This type mapping is used to interpret (and validate) the smart contract function call return value.
6070

61-
User entry origin’s output type is specified with as, eg. as=”e18” and as=”uint8”
71+
4. User entry origin's output type is specified with `as`, eg. as="e18" and as="uint8"
6272

63-
Token ID-based origins’ output type is specified with as similarly to user entry origins
73+
5. Token ID-based origins' output type is specified with `as` similarly to user entry origins
6474

65-
Similar to ethereum function origins, user entry and token ID-based origins should use the as value to interpret the output
75+
6. Similar to ethereum function origins, user entry and token ID-based origins should use the `as` value to interpret the output
6676

67-
Mappings
68-
Mappings always have string as the input type and output type
69-
The output from the origin is converted to a string which is used as the key for the mapping
70-
The output value is obtained, as a string
77+
7. Mappings
7178

72-
Syntax
73-
The syntax stage takes the output from the mapping (which is typed string), if there is one.
74-
The syntax stage takes the output from the origin, with a specific type in the absence of a mapping, as its input
79+
1. Mappings always have string as the input type and output type
80+
2. The output from the origin is converted to a string which is used as the key for the mapping
81+
3. The output value is obtained, as a string
7582

76-
The syntax stage converts the input to the output with a type based on the syntax:
77-
Directory String, IA5 String => “string” (and JavaScript string)
78-
Generalised Time => GeneralisedTime internally (and our standard Javascript GeneralisedTime type)
79-
Integer => Big Integer internally (and JavaScript number)
80-
Boolean => bool internally (and Javascript bool)
81-
Numeric String => Big Integer internally (and JavaScript string)
83+
8. Syntax
8284

83-
This brings some consistency so we can expand the pipeline to more than 3 stages in the future
85+
1. The syntax stage takes the output from the mapping (which is typed string), if there is one.
86+
2. The syntax stage takes the output from the origin, with a specific type in the absence of a mapping, as its input
87+
3. The syntax stage converts the input to the output with a type based on the syntax:
8488

85-
This is also useful when we have multiple origins which different types within the same attribute type
89+
* Directory String, IA5 String => "string" (and JavaScript string)
90+
* Generalised Time => GeneralisedTime internally (and our standard Javascript GeneralisedTime type)
91+
* Integer => Big Integer internally (and JavaScript number)
92+
* Boolean => bool internally (and Javascript bool)
93+
* Numeric String => Big Integer internally (and JavaScript string)
8694

87-
In <ts:transaction>, I just assume the function is an origin with as=”void” (void is only used internally for internal consistency), so the output (if any) is dropped. In the future if we need to chain function calls (I don’t know if we will ever need to), then it’s just another pipeline of function origins with non-void as=””
95+
9. This brings some consistency so we can expand the pipeline to more than 3 stages in the future
8896

89-
Note while we say the input and output types are typed, TokenScript clients can still hold them internally as strings as long as it knows and can enforce the types they represent. That’s an implementation detail. But such a case (assuming getString() returns a string) should not be permitted:
97+
10. This is also useful when we have multiple origins which different types within the same attribute type
9098

99+
11. In `<ts:transaction>`, I just assume the function is an origin with as="void" (void is only used internally for consistency), so the output (if any) is dropped. In the future if we need to chain function calls (I don't know if we will ever need to), then it's just another pipeline of function origins with non-void as=""
100+
101+
12. Note while we say the input and output types are typed, TokenScript clients can still hold them internally as strings as long as it knows and can enforce the types they represent. That's an implementation detail. But such a case (assuming `getString()` returns a string) should not be permitted:
102+
103+
```
91104
<ts:origins>
92105
<ts:ethereum contract="EntryToken" function="getStreet" as="uint256"/>
93106
<ts:mapping>
@@ -96,9 +109,11 @@ Note while we say the input and output types are typed, TokenScript clients can
96109
</ts:option>
97110
</ts:mapping>
98111
</ts:origins>
112+
```
99113

100-
But this is valid:
114+
But this is valid:
101115

116+
```
102117
<ts:origins>
103118
<ts:ethereum contract="EntryToken" function="getStreet" as="utf8"/>
104119
<ts:mapping>
@@ -107,4 +122,4 @@ But this is valid:
107122
</ts:option>
108123
</ts:mapping>
109124
</ts:origins>
110-
125+
```

0 commit comments

Comments
 (0)