Merge branch 'master' into xls-41d

Author: mvadari

.github/workflows/deploy.yml

@@ -47,7 +47,7 @@ jobs:
         uses: actions/configure-pages@v5
 
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v4
         with:
           path: "site/_site"
 

XLS-0006-visual-account-icons/README.md

@@ -0,0 +1,26 @@
+<pre>
+  xls: 6
+  title: Standard for Visual Account Icons
+  description: A standard for visually distinguishing XRPL accounts by generating unique icons for each account, regardless of address format.
+  author: Richard Holland (RichardAH)
+  discussion-from: https://github.com/XRPLF/XRPL-Standards/discussions/24
+  status: Final
+  category: Community
+  created: 2019-09-22
+</pre>
+
+Following from [XLS-5d](https://github.com/XRPLF/XLS-0005-standards-for-addressing), it has become necessary to provide XRPL users a way to identify their XRPL account, which effectively now has two different identifiers: an 'r-address' and an 'X-address'.
+
+To solve this problem XLS-6d provides for a standard way to visually identify accounts irrespective of which addressing system is used by the rest of the user interface.
+
+For a user account take the X-address of the account without destination tag and feed it into hashicon https://www.npmjs.com/package/hashicon
+
+For an exchange, take the X-address of the account with the destination tag and feed it into hashicon.
+
+It's recommended that these icons are displayed alongside addresses to help reduce user confusion. See examples in Figures 1 and 2.
+
+![image](https://user-images.githubusercontent.com/19866478/65387069-ba273a80-dd86-11e9-8680-34488e15401d.png)
+Figure 1
+
+![image](https://user-images.githubusercontent.com/19866478/65387078-dc20bd00-dd86-11e9-90af-126edf511060.png)
+Figure 2

XLS-0022-api-versioning/README.md

@@ -0,0 +1,126 @@
+<pre>
+  xls: 22
+  title: rippled API Versioning
+  description: The API version number allows for evolving the `rippled` API while maintaining backward compatibility
+  author: Elliot Lee (intelliot), Peng Wang (pwang200)
+  status: Final
+  category: Protocol
+  created: 2021-08-11
+</pre>
+
+# rippled API Versioning
+
+rippled offers an API (application programming interface) that apps use to integrate with the XRP Ledger. In order to evolve and improve this API over time, while providing consistency and ensuring backward compatibility for clients, the API shall be versioned with an `API version number`.
+
+For JSON-RPC and WebSocket (the most commonly-used interfaces), the API version number field is called `"api_version"`.
+
+### JSON-RPC
+
+```json
+{
+  "method": "...",
+  "params": [
+    {
+      "api_version": 1,
+      "...": "..."
+    }
+  ]
+}
+```
+
+Notice that "api_version" is [not a top-level field](https://github.com/ripple/rippled/issues/3065).
+
+### WebSocket
+
+```json
+{
+  "api_version": 1,
+  "id": 4,
+  "command": "...",
+  "...": "..."
+}
+```
+
+Following the [WebSocket request format](https://xrpl.org/request-formatting.html), it is placed at the top level.
+
+### rippled command line
+
+The RPC command and its parameters are parsed first. Then, a JSON-RPC request is created. rippled shall not support multiple versions of the command-parameter parsers, so the JSON-RPC requests will have one API version number. The latest API version number shall be used. Under the hood, rippled shall insert the `"api_version"` field internally.
+
+### gRPC
+
+The version number for gRPC is specified as part of the package name of the gRPC service definition (in .proto files). The .proto files of different versions shall be placed in version-specific folders.
+
+Multiple versions of the API are created by constructing multiple services, located in different namespaces. From gRPC's perspective, they are simply different services. All of the services can be registered to a single gRPC server.
+
+## Specification
+
+**The API version number shall be a single unsigned integer.** This is simpler than the major.minor.patch format, which is already used for versions of rippled itself. When it comes to API versions, there is no need for additional complexity beyond a single integer.
+
+**The API version number shall be increased if, and only if, we introduce one or more breaking changes to the API.** When the version number is increased, it is increased by one.
+
+**The lowest valid version number shall be 1.** The version number 0 is invalid.
+
+**rippled shall support a range of versions with consecutive version numbers.** At the moment, the range is [1, 1].
+
+**Client requests targeting an API version that is out of the supported version range shall be rejected.** For safety and ease of understanding, we do not allow "forward compatibility" where, if a version number in the request is higher than the supported range, we would lower its version number to the highest supported version number. Most clients know in advance which rippled servers they are connecting to (indeed, this is required for the XRPL security model). So it is unlikely that they will "mistakenly" make a request to a server that does not support the API version that they require. And if they do, it is better to respond with an error: the client can then choose to handle the error in a way that is appropriate for its use case.
+
+**Client targeting APIs with versions 2 and above shall specify the version number in their requests.** The WebSocket and JSON-RPC (HTTP) requests shall include the version number in the request payloads.
+
+**Requests without a version number shall be handled as version 1 requests.** This provides backward compatibility to the time when API version numbers did not yet exist.
+
+**Responses do not need to include the API version number.** This saves some bandwidth and encourages the "best practice" of having the client track its requests with the `id` field.
+
+**When a client sends multiple requests over a persistent connection (e.g. WebSockets), each request may use a different API version number.** This gives clients flexibility, with the ability to "progressively" update to new API versions in specific requests, without changing their entire integration.
+
+**When using the rippled command line interface, the latest API version shall be used.** The command line interface is typically used for development, debugging, and one-off requests. For simplicity and to ensure that developers always pay attention to the evolution of the API, these requests shall use the latest API version.
+
+**An API version that available in a stable release of rippled is considered "ready".** From the client's perspective, alpha/beta API versions generally should not exist.
+
+## Implementation Details
+
+There are four (4) RPC interfaces:
+
+1. JSON-RPC (HTTP)
+2. WebSocket
+3. rippled command line
+4. gRPC
+
+The API version number is a single 32-bit unsigned integer. A range of consecutive API versions are supported by rippled. The lower and upper bounds of the range shall be hardcoded. Different rippled software versions may support different API version ranges.
+
+For JSON-RPC and WebSocket, when a client requests an API version that is out of the supported range, the returned error message shall include the string "Unsupported API version", the version number targeted by the request, and the lower and upper bounds of the supported range.
+
+## What is considered a breaking change?
+
+- Deleting (removing), renaming, changing the type of, or changing the meaning of a field of a request or a response.
+- Changing the order of position-based parameters, or inserting a new field in front of existing position-based parameters.
+- Deleting or renaming an API method (function).
+- Changing the behavior of an API method in a way that is visible to existing clients.
+- Changing HTTP status codes[^1].
+
+gRPC only:
+
+- Changing a proto field number.
+- Deleting or renaming an enum or enum value.
+- Moving fields into or out of a oneof, split, or merge oneof.
+- Changing the label of a message field, i.e. optional, repeated, required.
+- Changing the stream value of a method request or response.
+- Deleting or renaming a package or service.
+
+## What is not a breaking change?
+
+- Adding a new field to a request or response message, if it is not a position-based parameter.
+- Adding a new API method (function).
+
+## References
+
+- [Documentation: API Versioning](https://xrpl.org/request-formatting.html#api-versioning)
+- [API versioning #3155 (rippled PR)](https://github.com/ripple/rippled/pull/3155): Merged and released in [rippled v1.5.0](https://github.com/ripple/rippled/releases/tag/1.5.0)
+- [Original Requirements](https://github.com/pwang200/RippledRPCDesign/blob/API_versioning/requirement/requirements.md)
+- [Original Design Document](https://github.com/pwang200/RippledRPCDesign/blob/API_versioning/design/design.md)
+
+[^1]:
+    Changes to response status codes. For example, this is a breaking change:
+    **Before:** POST /values returns 400 for missing property
+    **After:** POST /values returns 409 for missing property
+    [Reference](https://community.blackbaud.com/blogs/69/3219)

XLS-0049-multiple-signer-lists/README.md

@@ -0,0 +1,162 @@
+<pre>
+  xls: 49
+  title: Multiple Signer Lists
+  description: A proposal to enable multiple signer lists per account on the XRP Ledger, allowing different signer lists to authorize specific transaction types.
+  author: Mayukha Vadari <mvadari@ripple.com>
+  discussion-from: https://github.com/XRPLF/XRPL-Standards/discussions/144
+  status: Draft
+  category: Amendment
+  created: 2023-11-13
+</pre>
+
+# Multiple Signer Lists
+
+## Abstract
+
+The XRP Ledger currently only supports one global signer list per account. However, many users (such as token issuers) require more granularity. For example, they might want to have one signer list with the ability to mint new tokens, and another signer list with the ability to create and edit trustlines.
+
+This document describes a proposal for supporting multiple signer lists per account. The current system of global signer lists will continue to be supported, but we propose adding **per-transaction-type signer lists**. Accounts can set up signer lists that only have the power to send **transactions of one specific type** on behalf of the account.
+
+This proposal is related to [XLS-31d](https://github.com/XRPLF/XRPL-Standards/discussions/77), but broader in scope.
+
+## 1. Overview
+
+We propose modifying one ledger object and one transaction:
+
+- `SignerList` ledger object
+- `SignerListSet` transaction
+
+This change will require an amendment.
+
+The important considerations to keep in mind are:
+
+- `rippled` must be able to retrieve all possible signer lists for a transaction type quickly and easily, in order to check if a transaction has a valid multisign list.
+- Any signer list that can sign transactions can drain the account's XRP via fees.
+
+## 2. On-Ledger Object: **`SignerList`**
+
+There is no change to the shape of a [`SignerList` ledger object](https://xrpl.org/signerlist.html), only in how it's used.
+
+### 2.1. Fields
+
+As a reference, the **`SignerList`** object currently has the following fields:
+
+| Field Name          | Required? | JSON Type | Internal Type |
+| ------------------- | --------- | --------- | ------------- |
+| `LedgerIndex`       | ✔️        | `string`  | `HASH256`     |
+| `LedgerEntryType`   | ✔️        | `string`  | `UINT16`      |
+| `SignerEntries`     | ✔️        | `array`   | `STARRAY`     |
+| `SignerQuorum`      | ✔️        | `number`  | `UINT32`      |
+| `SignerListID`      | ✔️        | `number`  | `UINT32`      |
+| `OwnerNode`         | ✔️        | `string`  | `UINT64`      |
+| `PreviousTxnID`     | ✔️        | `string`  | `HASH256`     |
+| `PreviousTxnLgrSeq` | ✔️        | `number`  | `UINT32`      |
+
+The ledger index of this object is calculated by hashing together the owner's account ID with the value of `0`.
+
+The only field whose usage is changing is `SignerListID`. All other fields will be used the same as they are now.
+
+#### 2.1.1. `SignerListID`
+
+This field is currently always set to `0`. The original [`Multisign` implementation](https://xrpl.org/known-amendments.html#multisign) only allowed for one signer list per account, but left the door open for the possibility of more.
+
+We propose that this field is instead used for the transaction type that the signer is allowed to sign for, with `0` being the value for the global signer list (to ensure backwards compatibility). There is enough space in `SignerListID` for this field, because `TxType` is a `UInt16` and `SignerListID` is a `UInt32`. Since the `UInt32` is so much larger than the `UInt16`, there is extra room in the valid values for additional signer list usage proposals. The value of this field will also be used in the `index` calculation.
+
+One problem: `Payment` has transaction type `0`, which would conflict with the global signer list. To get around that, we will instead use `1+TxType` in the `SignerListID` field. It is then very easy to check whether a multisign transaction is valid: the code can check the global signer list (look at the signer list with index `account + 0`), and the transaction-type-specific signer list (look at the signer list with index `account + (1+TxType)`).
+
+Each additional `SignerList` that an account owns will, of course, cost an additional owner reserve (2 XRP at the time of writing).
+
+## 3. Transaction: **`SignerListSet`**
+
+The [`SignerListSet` transaction](https://xrpl.org/signerlistset.html) already exists on the XRPL. We propose a slight modification to support per-transaction-type signer lists.
+
+### 3.1. Fields
+
+As a reference, the **`SignerListSet`** transaction already has the following fields:
+
+| Field Name        | Required? | JSON Type | Internal Type |
+| ----------------- | --------- | --------- | ------------- |
+| `TransactionType` | ✔️        | `string`  | `UInt16`      |
+| `SignerEntries`   | ✔️        | `array`   | `STARRAY`     |
+| `SignerQuorum`    | ✔️        | `number`  | `UInt32`      |
+
+We propose adding a new optional field:
+| Field Name | Required? | JSON Type | Internal Type |
+|------------|-----------|-----------|---------------|
+|`TransactionTypeBitmask` | |`array`|`HASH256`
+
+#### 3.1.1. `TransactionTypeBitmask`
+
+This field accepts a bitmask of transaction types, much like the [`HookOn` field](https://xrpl-hooks.readme.io/docs/hookon-field). A `0` bit is "on" and a `1` bit is "off". A value of `0` changes the global signer list. All other values change the many signer lists of the transactions they apply to, so that it is easier to modify many signer lists at once. The JSON will show a list of transactions.
+
+## 4. Security
+
+One important fact to remember is that any signer list that can sign transactions can drain the account's XRP via fees. This was why multiple signer lists were never implemented originally. There is [an open issue](https://github.com/XRPLF/rippled/issues/4476) proposing potential ways to prevent accidental high fees on transactions.
+
+Also, any signer list that is added to `SignerListSet` can effectively give themselves powers over any other transaction(s) they desire.
+
+# Appendix
+
+## Appendix A: FAQ
+
+### A.1: Should global signer lists still be able to send transactions that have specific signer lists enabled?
+
+Yes, because global signer lists should be able to act exactly like master and regular keys. This proposal does not support changing that.
+
+### A.2: Why not also use a bitmask for storage?
+
+This design was strongly considered, but this spec is easier to use and understand. See Appendix B for more details.
+
+### A.3: Why not just take a transaction type in the `TransactionTypeBitmask` field?
+
+That was part of the original design, because it would be more user-friendly and easier to read. It was changed to allow accounts to modify multiple signer lists with one transaction.
+
+### A.4: Can you remove the global signer list after removing the master and regular key?
+
+No, you need to go through the standard blackhole procedure (setting the regular key to `ACCOUNT_ZERO`).
+
+Theoretically, an account could only have a specific signer list on at least one of `SignerListSet`/`SetRegularKey`/`AccountSet` so that the blackholing can be changed. However, this addition seems unnecessary since the standard blackhole procedure already exists.
+
+### A.5: Why not use crypto-conditions?
+
+This was briefly considered, but we decided to go with this design instead. See Appendix C for more details.
+
+## Appendix B: Bitmasks for `SignerListID`
+
+Another design we developed (and seriously considered) was using a bitmask to determine which transaction types a signer list could sign for. This took inspiration from the [`HookOn` field](https://xrpl-hooks.readme.io/docs/hookon-field) in the hooks proposal.
+
+The ledger modifications necessary for this design:
+
+- The ledger object hash (`index`) is now derived from the sequence of the transaction that created the signer list (similar to how escrow hashes are derived). This sequence is stored in the `SignerListID` field.
+- Modifying or deleting a signer list that isn't the global one (instead of creating a new one) requires specifying the `SignerListID` in the `SignerListSet` transaction.
+- Using a signer list that isn't the global one requires specifying the `SignerListID` in the transaction (a new global optional field).
+
+Ultimately, due to the pros and cons, we decided against this spec. If you have strong feelings about this design (positive _or_ negative), please comment, because it's still in consideration.
+
+### B.1. Pros and Cons
+
+**Existing Spec**
+
+- Pros
+  - Ease of use and understandability - same as existing processes
+  - Only one signer list can access each transaction (technically two if you include the global signer list)
+- Cons
+  - One signer list per transaction, even if the same signer list is used for multiple transactions
+  - One reserve per transaction
+  - Only one signer list can access each transaction
+
+**Bitmask**
+
+- Pros
+  - One signer list object regardless of how many transactions it controls (easier on ledger resources)
+  - One reserve per signer list
+  - Multiple signer lists can access each transaction
+- Cons
+  - More UX changes - you need to specify the `SignerListID` in the transaction. This is all less compatible with the existing UX for the global signer list.
+  - Multiple signer lists can access each transaction (this could get messy and is more difficult to keep track of)
+  - A larger change to the current usage of signer lists
+  - What happens if/when we reach 256 transactions?
+
+## Appendix C: Crypto-Conditions
+
+Using crypto-conditions for implementing per-transaction-type multisign was considered, but it seemed overly complex for the use-cases that people have. If a crypto-condition-based multisign approach is implemented, it should probably be integrated into all signatures, and apply to both multi-sign _and_ single-sign.