You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: xls-0097-server-definitions-enhancements/README.md
+49-49Lines changed: 49 additions & 49 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,99 +14,99 @@
14
14
15
15
## 1\. Abstract
16
16
17
-
The [server\_definitions RPC command](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/server-info-methods/server_definitions) is an existing API endpoint that provides client applications with essential protocol information needed to properly interact with the XRPL network. Currently, it returns all the details necessary to serialize and deserialize data encoded in the custom XRPL binary format. This document proposes new additions to the `server_definitions` RPC response. Specifically, it advocates adding transaction formats, ledger object formats, transaction flags and ledger specific flags in the `server_definitions` response.
17
+
The [server_definitions RPC command](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/server-info-methods/server_definitions) is an existing API endpoint that provides client applications with essential protocol information needed to properly interact with the XRPL network. Currently, it returns all the details necessary to serialize and deserialize data encoded in the custom XRPL binary format. This document proposes new additions to the `server_definitions` RPC response. Specifically, it advocates adding transaction formats, ledger object formats, transaction flags and ledger specific flags in the `server_definitions` response.
18
18
19
19
## 2\. Motivation
20
20
21
21
This information helps client libraries understand how to serialize/deserialize XRPL data structures, construct valid transactions, and parse valid ledger entries. Essentially, the basics of an XRPL library in any programming language could be constructed just from the details of the `server_definitions` output with the additions.
22
22
23
23
Some of the envisioned benefits of this proposal:
24
24
25
-
* Import: Enables clients to import all supported transactions as well as the inputs/outputs.
26
-
* Validation: Enables client-side validation before submitting to the network. Clients do not need to resort to blind-signing the transactions i.e. clients can infer the correct structure of the transactions using the response of the `server_definitions` RPC.
27
-
* Better Error Messages: Applications can provide specific feedback about missing required fields. These error messages can be tailored to be more informative instead of the terse rippled error messages.
28
-
* Protocol Compliance: Ensures applications stay in sync with protocol changes. This can be accomplished by periodically fetching the `server_definitions` RPC response
25
+
- Import: Enables clients to import all supported transactions as well as the inputs/outputs.
26
+
- Validation: Enables client-side validation before submitting to the network. Clients do not need to resort to blind-signing the transactions i.e. clients can infer the correct structure of the transactions using the response of the `server_definitions` RPC.
27
+
- Better Error Messages: Applications can provide specific feedback about missing required fields. These error messages can be tailored to be more informative instead of the terse rippled error messages.
28
+
- Protocol Compliance: Ensures applications stay in sync with protocol changes. This can be accomplished by periodically fetching the `server_definitions` RPC response
29
29
30
30
## 3\. RPC: `server_definitions`
31
31
32
-
The `server_definitions` RPC [already exists](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/server-info-methods/server_definitions). A sample output is available [here](https://xrpl.org/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%20%20%22command%22%3A%20%22server_definitions%22%0A%7D). This spec proposes some additions.
32
+
The `server_definitions` RPC [already exists](https://xrpl.org/docs/references/http-websocket-apis/public-api-methods/server-info-methods/server_definitions). A sample output is available [here](https://xrpl.org/resources/dev-tools/websocket-api-tool?server=wss%3A%2F%2Fs1.ripple.com%2F&req=%7B%20%20%22command%22%3A%20%22server_definitions%22%0A%7D). This spec proposes some additions.
33
33
34
34
### 3.1. Request Fields
35
35
36
36
There are no changes to the request fields. The current request fields are shown below:
37
37
38
-
| Field Name | Required? | JSON Type | Description |
39
-
| :---- | :---- | :---- | :---- |
40
-
|`command`| Yes |`string`| Must be "`server_definitions`" to access this RPC |
41
-
|`hash`| No |`string`| A hash of the `server_definitions` data. If this matches the hash the rippled server has, only the hash will be returned. |
38
+
| Field Name | Required? | JSON Type | Description |
|`command`| Yes |`string`| Must be "`server_definitions`" to access this RPC|
41
+
|`hash`| No |`string`| A hash of the `server_definitions` data. If this matches the hash the rippled server has, only the hash will be returned. |
42
42
43
43
### 3.2. Response Fields
44
44
45
45
Current response fields:
46
46
47
-
| Field Name | Always Present? | JSON Type | Description |
48
-
| :---- | :---- | :---- | :---- |
49
-
|`TYPES`| No, not included if `hash` matches the server's data hash |`object`| Map of data types to their ["type code"](https://xrpl.org/docs/references/protocol/binary-format#type-codes) for constructing field IDs and sorting fields in canonical order. Codes below 1 should not appear in actual data; codes above 10000 represent special "high-level" object types such as "Transaction" that cannot be serialized inside other objects. See the Type List for details of how to serialize each type.|
50
-
|`LEDGER_ENTRY_TYPES`| No, not included if `hash` matches the server's data hash |`object`| Map of ledger objects to their data type. These appear in ledger state data, and in the "affected nodes" section of processed transactions' metadata. |
51
-
|`FIELDS`| No, not included if `hash` matches the server's data hash |`array`| A sorted array of tuples representing all fields that may appear in transactions, ledger objects, or other data. The first member of each tuple is the string name of the field and the second member is an object with that field's properties. (See the "Field properties" table below for definitions of those fields.) |
52
-
|`TRANSACTION_RESULTS`| No, not included if `hash` matches the server's data hash |`object`| Map of transaction result codes to their numeric values. Result types not included in ledgers have negative values; tesSUCCESS has numeric value 0; tec-class codes represent failures that are included in ledgers. |
53
-
|`TRANSACTION_TYPES`| No, not included if `hash` matches the server's data hash |`object`| Map of all transaction types to their numeric values. |
54
-
|`hash`| Yes |`string`| The hash of the `server_definitions` data that the rippled server has. |
47
+
| Field Name | Always Present? | JSON Type | Description|
|`TYPES`| No, not included if `hash` matches the server's data hash |`object`| Map of data types to their ["type code"](https://xrpl.org/docs/references/protocol/binary-format#type-codes) for constructing field IDs and sorting fields in canonical order. Codes below 1 should not appear in actual data; codes above 10000 represent special "high-level" object types such as "Transaction" that cannot be serialized inside other objects. See the Type List for details of how to serialize each type. |
50
+
|`LEDGER_ENTRY_TYPES`| No, not included if `hash` matches the server's data hash |`object`| Map of ledger objects to their data type. These appear in ledger state data, and in the "affected nodes" section of processed transactions' metadata.|
51
+
|`FIELDS`| No, not included if `hash` matches the server's data hash |`array`| A sorted array of tuples representing all fields that may appear in transactions, ledger objects, or other data. The first member of each tuple is the string name of the field and the second member is an object with that field's properties. (See the "Field properties" table below for definitions of those fields.)|
52
+
|`TRANSACTION_RESULTS`| No, not included if `hash` matches the server's data hash |`object`| Map of transaction result codes to their numeric values. Result types not included in ledgers have negative values; tesSUCCESS has numeric value 0; tec-class codes represent failures that are included in ledgers.|
53
+
|`TRANSACTION_TYPES`| No, not included if `hash` matches the server's data hash |`object`| Map of all transaction types to their numeric values.|
54
+
|`hash`| Yes |`string`| The hash of the `server_definitions` data that the rippled server has.|
55
55
56
56
Proposed additions:
57
57
58
-
| Field Name | Always Present? | JSON Type | Description |
59
-
| :---- | :---- | :---- | :---- |
60
-
|`LEDGER_ENTRY_FORMATS`| No, not included if `hash` matches the server's data hash |`object`| Detailed format specifications for all ledger entry types (`AccountRoot`, `RippleState`, `Offer`, etc.) \- namely, the fields and their optionality. |
61
-
|`TRANSACTION_FORMATS`| No, not included if `hash` matches the server's data hash |`object`| Detailed format specifications for all transaction types (`Payment`, `OfferCreate`, `TrustSet`, etc.) \- namely, the fields and their optionality. |
62
-
|`LEDGER_ENTRY_FLAGS`| No, not included if `hash` matches the server's data hash |`object`| Complete mapping of all ledger entry flags with their hexadecimal values. |
63
-
|`TRANSACTION_FLAGS`| No, not included if `hash` matches the server's data hash |`object`| Complete mapping of all transaction flags with their hexadecimal values. |
64
-
|`ACCOUNT_SET_FLAGS`| No, not included if `hash` matches the server's data hash |`object`| Complete mapping of all `AccountSet` flags (`asf` flags) with their hexadecimal values. |
58
+
| Field Name | Always Present? | JSON Type | Description|
|`LEDGER_ENTRY_FORMATS`| No, not included if `hash` matches the server's data hash |`object`| Detailed format specifications for all ledger entry types (`AccountRoot`, `RippleState`, `Offer`, etc.) \- namely, the fields and their optionality. |
61
+
|`TRANSACTION_FORMATS`| No, not included if `hash` matches the server's data hash |`object`| Detailed format specifications for all transaction types (`Payment`, `OfferCreate`, `TrustSet`, etc.) \- namely, the fields and their optionality.|
62
+
|`LEDGER_ENTRY_FLAGS`| No, not included if `hash` matches the server's data hash |`object`| Complete mapping of all ledger entry flags with their hexadecimal values.|
63
+
|`TRANSACTION_FLAGS`| No, not included if `hash` matches the server's data hash |`object`| Complete mapping of all transaction flags with their hexadecimal values.|
64
+
|`ACCOUNT_SET_FLAGS`| No, not included if `hash` matches the server's data hash |`object`| Complete mapping of all `AccountSet` flags (`asf` flags) with their hexadecimal values.|
65
65
66
66
#### 3.2.1. Fields
67
67
68
-
##### 3.2.1.1. LEDGER\_ENTRY\_FORMATS
68
+
##### 3.2.1.1. LEDGER_ENTRY_FORMATS
69
69
70
70
The format of this field is an `object`. The keys of the `object` are the ledger entry type name (e.g. `Offer`), or `common` (for the common fields across all ledger entries). The values of the `object` are an array of elements described as follows:
71
71
72
-
| Field Name | Always Present? | JSON Type | Description |
73
-
| :---- | :---- | :---- | :---- |
74
-
|`name`| Yes |`string`| The name of the field. |
75
-
|`optionality`| Yes |`number`| The `soeREQUIRED` value of the field \- one of the following values: [-1, 2] (both inclusive). [More details found here](#3.2.1.1.1). |
72
+
| Field Name | Always Present? | JSON Type | Description|
|`optionality`| Yes |`number`| The `soeREQUIRED` value of the field \- one of the following values: [-1, 2] (both inclusive). [More details found here](#3.2.1.1.1). |
76
76
77
77
##### 3.2.1.1.1 `optionality` number-text map
78
78
79
79
The `optionality` values are mapped to the following text <-> number combination. For the purpose of improved readability, this mapping is borrowed from the [`SOEStyle` enum definition](https://github.com/XRPLF/rippled/blob/e11f6190b74599737f9f554da3b141f269e43803/include/xrpl/protocol/SOTemplate.h#L13) in the rippled codebase.
80
80
81
-
| Number | Optionality |
82
-
| :---- | :---- |
83
-
|`-1`|`soeINVALID`|
84
-
|`0`|`soeREQUIRED`|
85
-
|`1`|`soeOPTIONAL`|
86
-
|`2`|`soeDEFAULT`|
81
+
| Number | Optionality |
82
+
| :-----| :------------ |
83
+
|`-1`|`soeINVALID`|
84
+
|`0`|`soeREQUIRED`|
85
+
|`1`|`soeOPTIONAL`|
86
+
|`2`|`soeDEFAULT`|
87
87
88
-
##### 3.2.1.2. TRANSACTION\_FORMATS
88
+
##### 3.2.1.2. TRANSACTION_FORMATS
89
89
90
90
The format of this field is an `object`. The keys of the `object` are the transaction type name (e.g. `OfferCreate`, or `common` (for the common fields across all transactions). The values of the `object` are an array of elements described as follows:
91
91
92
-
| Field Name | Always Present? | JSON Type | Description |
93
-
| :---- | :---- | :---- | :---- |
94
-
|`name`| Yes |`string`| The name of the field. |
95
-
|`optionality`| Yes |`number`| The `soeREQUIRED` value of the field \- one of the following values: [-1, 2] (both inclusive). [More details found here](#3.2.1.1.1). |
92
+
| Field Name | Always Present? | JSON Type | Description|
|`optionality`| Yes |`number`| The `soeREQUIRED` value of the field \- one of the following values: [-1, 2] (both inclusive). [More details found here](#3.2.1.1.1). |
96
96
97
-
##### 3.2.1.3. LEDGER\_ENTRY\_FLAGS
97
+
##### 3.2.1.3. LEDGER_ENTRY_FLAGS
98
98
99
99
The format of this field is an `object`, with the keys being the ledger entry type name (e.g. `Offer`) and the values being another `object`. This nested `object`'s keys are the `lsf` name (e.g. `lsfSell`), and its values are the corresponding integer values (e.g. `131072`).
100
100
101
101
Only ledger entry types that have flags are included in this.
102
102
103
-
##### 3.2.1.4. TRANSACTION\_FLAGS
103
+
##### 3.2.1.4. TRANSACTION_FLAGS
104
104
105
105
The format of this field is an `object`, with the keys being the transaction type name (e.g. `OfferCreate`) and the values being another `object`. This nested `object`'s keys are the `tf` name (e.g. `tfPassive`), and its values are the corresponding integer values (e.g. `65536`).
106
106
107
107
Only transaction types that have flags are included in this.
108
108
109
-
##### 3.2.1.5. ACCOUNT\_SET\_FLAGS
109
+
##### 3.2.1.5. ACCOUNT_SET_FLAGS
110
110
111
111
The format of this field is an `object`, with the keys being the `asf` name (e.g. `asfDefaultRipple`) and the values being the corresponding integer values (e.g. `8`).
112
112
@@ -120,7 +120,7 @@ There are no changes to the failure conditions of the `server_definitions` RPC.
120
120
121
121
```json
122
122
{
123
-
"command": "server_definitions"
123
+
"command": "server_definitions"
124
124
}
125
125
```
126
126
@@ -132,13 +132,13 @@ A sample response is available [here](https://gist.github.com/mvadari/407732fee9
132
132
133
133
Currently, clients must manually hardcode or scrape this structural information from the `rippled` source, which is brittle and creates high maintenance overhead. Centralizing these definitions on the server offers:
134
134
135
-
***Reduced Client Maintenance:** Clients fetch definitions directly, eliminating the need to update internal data with every protocol change.
-**Consistency:** Guarantees all client libraries use the single, authoritative view of the protocol.
138
138
139
139
### 4.1. Alternate Designs Rejected
140
140
141
-
***Separate RPCs:** Rejected for requiring multiple network calls; consolidation is more efficient. In addition, this is essentially the purpose of the `server_definitions` RPC.
141
+
-**Separate RPCs:** Rejected for requiring multiple network calls; consolidation is more efficient. In addition, this is essentially the purpose of the `server_definitions` RPC.
0 commit comments