From 6f4a89f116aeba877545f78a324feab82abfa1cc Mon Sep 17 00:00:00 2001 From: Maria Shodunke Date: Thu, 20 Mar 2025 15:18:03 +0000 Subject: [PATCH 1/7] Add non-admin feature RPC --- .../server-info-methods/feature.md | 165 ++++++++++++++++++ sidebars.yaml | 1 + 2 files changed, 166 insertions(+) create mode 100644 docs/references/http-websocket-apis/public-api-methods/server-info-methods/feature.md diff --git a/docs/references/http-websocket-apis/public-api-methods/server-info-methods/feature.md b/docs/references/http-websocket-apis/public-api-methods/server-info-methods/feature.md new file mode 100644 index 0000000000..f57ea3794d --- /dev/null +++ b/docs/references/http-websocket-apis/public-api-methods/server-info-methods/feature.md @@ -0,0 +1,165 @@ +--- +html: feature.html +parent: server-info-methods.html +seo: + description: Get information about protocol amendments. +labels: + - Blockchain + - Core Server +--- + +# feature + +[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/rpc/handlers/Feature1.cpp "Source")
+ +The `feature` command returns information about [amendments](../../../../concepts/networks-and-servers/amendments.md) this server knows about, including whether they are enabled and if the server knows how to apply the amendments. + +This is the non-admin version of the [`feature` admin command](../../admin-api-methods/status-and-debugging-methods/feature.md). It follows the same formatting as the _admin_ command, but hides potentially sensitive data. + +{% badge href="https://github.com/XRPLF/rippled/releases/tag/2.2.0" %}New in: rippled 2.2.0{% /badge %} + +## Request Format + +An example of the request format: + +{% tabs %} + +{% tab label="WebSocket" %} +```json +{ + "id": "list_all_features", + "command": "feature" +} +``` +{% /tab %} + +{% tab label="JSON-RPC" %} +```json +{ + "method": "feature", + "params": [ + { + "feature": "4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373" + } + ] +} +``` +{% /tab %} + +{% tab label="Commandline" %} +```sh +#Syntax: feature [] +rippled feature 4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373 +``` +{% /tab %} + +{% /tabs %} + +{% try-it method="feature" /%} + +The request includes the following parameters: + +| `Field` | Type | Description | +|:----------|:--------|:-------------------------------------------------------| +| `feature` | String | _(Optional)_ The unique ID of an amendment, as hexadecimal; or the short name of the amendment. If provided, limits the response to one amendment. Otherwise, the response lists all amendments. | + +## Response Format + +An example of a successful response: + +{% tabs %} + +{% tab label="WebSocket" %} +```json +{ + "id": "list_all_features", + "result": { + "features": { + "00C1FC4A53E60AB02C864641002B3172F38677E29C26C5406685179B37E1EDAC": { + "enabled": true, + "name": "RequireFullyCanonicalSig", + "supported": true + }, + "0285B7E5E08E1A8E4C15636F0591D87F73CB6A7B6452A932AD72BBC8E5D1CBE3": { + "enabled": false, + "name": "fixNFTokenDirV1", + "supported": true + }, + "03BDC0099C4E14163ADA272C1B6F6FABB448CC3E51F522F978041E4B57D9158C": { + "enabled": true, + "name": "fixNFTokenReserve", + "supported": true + }, + "07D43DCE529B15A10827E5E04943B496762F9A88E3268269D69C44BE49E21104": { + "enabled": false, + "name": "Escrow", + "supported": true + }, + "08DE7D96082187F6E6578530258C77FAABABE4C20474BDB82F04B021F1A68647": { + "enabled": false, + "name": "PayChan", + "supported": true + } + } + }, + "status": "success", + "type": "response" +} +``` +{% /tab %} + +{% tab label="JSON-RPC" %} +```json +200 OK + +{ + "result": { + "4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373": { + "enabled": false, + "name": "MultiSign", + "supported": true + }, + "status": "success" + } +} +``` +{% /tab %} + +{% tab label="Commandline" %} +```json +Loading: "/etc/rippled.cfg" +Connecting to 127.0.0.1:5005 + +{ + "result": { + "4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373": { + "enabled": false, + "name": "MultiSign", + "supported": true + }, + "status": "success" + } +} +``` +{% /tab %} + +{% /tabs %} + +The response follows the [standard format][], with a successful result containing **a map of amendments** as a JSON object. The keys of the object are amendment IDs. The values for each key are _amendment objects_ that describe the status of the amendment with that ID. If the request specified a `feature`, the map contains only the requested amendment object, after applying any changes from the request. Each amendment object has the following fields: + +| `Field` | Type | Description | +|:------------|:--------|:-----------------------------------------------------| +| `enabled` | Boolean | Whether this amendment is currently enabled in the latest ledger. | +| `name` | String | (May be omitted) The human-readable name for this amendment, if known. | +| `supported` | Boolean | Whether the server knows how to apply this amendment. If this field is set to `false` (the server does not know how to apply this amendment) and `enabled` is set to `true` (this amendment is enabled in the latest ledger), this amendment may cause your server to be [amendment blocked](../../../../concepts/networks-and-servers/amendments.md#amendment-blocked-servers). | + +{% admonition type="warning" name="Caution" %}The `name` for an amendment does not strictly indicate what that amendment does. The name is not guaranteed to be unique or consistent across servers.{% /admonition %} + +## Possible Errors + +- Any of the [universal error types][]. +- `badFeature` - The `feature` specified was invalidly formatted, or the server does not know an amendment with that name. +- `noPermission` - The user does not have permission to run the specified command (i.e., `vetoed`). +- `reportingUnsupported` - ([Reporting Mode][] servers only) This method is not available in Reporting Mode. + +{% raw-partial file="/docs/_snippets/common-links.md" /%} diff --git a/sidebars.yaml b/sidebars.yaml index ee066c18ab..0919b9bcda 100644 --- a/sidebars.yaml +++ b/sidebars.yaml @@ -527,6 +527,7 @@ - page: docs/references/http-websocket-apis/public-api-methods/server-info-methods/server_info.md - page: docs/references/http-websocket-apis/public-api-methods/server-info-methods/server_state.md - page: docs/references/http-websocket-apis/public-api-methods/server-info-methods/version.md + - page: docs/references/http-websocket-apis/public-api-methods/server-info-methods/feature.md - page: docs/references/http-websocket-apis/public-api-methods/clio-methods/index.md expanded: false From 24f97c6f5de182797f0021cec5fa44b05db42225 Mon Sep 17 00:00:00 2001 From: Maria Shodunke Date: Fri, 21 Mar 2025 10:44:00 +0000 Subject: [PATCH 2/7] Update with feedback --- .../server-info-methods/feature.md | 35 ++++--------------- 1 file changed, 6 insertions(+), 29 deletions(-) diff --git a/docs/references/http-websocket-apis/public-api-methods/server-info-methods/feature.md b/docs/references/http-websocket-apis/public-api-methods/server-info-methods/feature.md index f57ea3794d..9bc54d4631 100644 --- a/docs/references/http-websocket-apis/public-api-methods/server-info-methods/feature.md +++ b/docs/references/http-websocket-apis/public-api-methods/server-info-methods/feature.md @@ -27,8 +27,8 @@ An example of the request format: {% tab label="WebSocket" %} ```json { - "id": "list_all_features", - "command": "feature" + "command": "feature", + "feature": "4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373" } ``` {% /tab %} @@ -72,34 +72,11 @@ An example of a successful response: {% tab label="WebSocket" %} ```json { - "id": "list_all_features", "result": { - "features": { - "00C1FC4A53E60AB02C864641002B3172F38677E29C26C5406685179B37E1EDAC": { - "enabled": true, - "name": "RequireFullyCanonicalSig", - "supported": true - }, - "0285B7E5E08E1A8E4C15636F0591D87F73CB6A7B6452A932AD72BBC8E5D1CBE3": { - "enabled": false, - "name": "fixNFTokenDirV1", - "supported": true - }, - "03BDC0099C4E14163ADA272C1B6F6FABB448CC3E51F522F978041E4B57D9158C": { - "enabled": true, - "name": "fixNFTokenReserve", - "supported": true - }, - "07D43DCE529B15A10827E5E04943B496762F9A88E3268269D69C44BE49E21104": { - "enabled": false, - "name": "Escrow", - "supported": true - }, - "08DE7D96082187F6E6578530258C77FAABABE4C20474BDB82F04B021F1A68647": { - "enabled": false, - "name": "PayChan", - "supported": true - } + "4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373": { + "enabled": false, + "name": "MultiSign", + "supported": true } }, "status": "success", From a225150b39a8cdff05f68a826de4bf19d8dbf70c Mon Sep 17 00:00:00 2001 From: Maria Shodunke Date: Fri, 21 Mar 2025 11:24:45 +0000 Subject: [PATCH 3/7] Fix source code link --- .../public-api-methods/server-info-methods/feature.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/references/http-websocket-apis/public-api-methods/server-info-methods/feature.md b/docs/references/http-websocket-apis/public-api-methods/server-info-methods/feature.md index 9bc54d4631..a4b2abb688 100644 --- a/docs/references/http-websocket-apis/public-api-methods/server-info-methods/feature.md +++ b/docs/references/http-websocket-apis/public-api-methods/server-info-methods/feature.md @@ -10,7 +10,7 @@ labels: # feature -[[Source]](https://github.com/XRPLF/rippled/blob/master/src/ripple/rpc/handlers/Feature1.cpp "Source")
+[[Source]](https://github.com/XRPLF/rippled/blob/master/src/xrpld/rpc/handlers/Feature1.cpp "Source")
The `feature` command returns information about [amendments](../../../../concepts/networks-and-servers/amendments.md) this server knows about, including whether they are enabled and if the server knows how to apply the amendments. From dccc5aa65c76e13cdad180a032b5f3df9d054156 Mon Sep 17 00:00:00 2001 From: Maria Shodunke Date: Mon, 24 Mar 2025 11:28:02 +0000 Subject: [PATCH 4/7] Fix missing Try-it now configuration --- .../components/websocket-api/data/command-list.json | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/resources/dev-tools/components/websocket-api/data/command-list.json b/resources/dev-tools/components/websocket-api/data/command-list.json index 5336bff3c1..094cc95a7e 100644 --- a/resources/dev-tools/components/websocket-api/data/command-list.json +++ b/resources/dev-tools/components/websocket-api/data/command-list.json @@ -565,6 +565,15 @@ "body": { "command": "version" } + }, + { + "name": "feature", + "description": "Returns information about amendments this server knows about. When you connect to a cluster that includes a Clio server, the Clio method is used.", + "link": "/docs/references/http-websocket-apis/public-api-methods/server-info-methods/feature", + "body": { + "command": "feature", + "feature": "4C97EBA926031A7CF7D7B36FDE3ED66DDA5421192D63DE53FFB46E43B9DC8373" + } } ] }, From b5e63a1eab6cca231d80b2409abf2589b0a0836a Mon Sep 17 00:00:00 2001 From: Maria Shodunke Date: Mon, 24 Mar 2025 11:52:44 +0000 Subject: [PATCH 5/7] Add feature to Public API methods index page --- docs/references/http-websocket-apis/public-api-methods/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/references/http-websocket-apis/public-api-methods/index.md b/docs/references/http-websocket-apis/public-api-methods/index.md index fe8e4fc6c4..4e2997bfa6 100644 --- a/docs/references/http-websocket-apis/public-api-methods/index.md +++ b/docs/references/http-websocket-apis/public-api-methods/index.md @@ -93,6 +93,7 @@ Use these methods to retrieve information about the current state of the `ripple * **[`server_state`](server-info-methods/server_state.md)** - Retrieve status of the server in machine-readable format. * **[`server_definitions`](server-info-methods/server_definitions.md)** - Retrieve a list of types and fields used for the XRPL's canonical binary format. * **[`manifest`](server-info-methods/manifest.md)** - Retrieve the latest ephemeral public key information about a known validator. +* **[`feature`](server-info-methods/feature.md)** - Returns information about amendments this server knows about. ## [Clio Methods](clio-methods/index.md) From f78647b23b4659a68c1ffb8554acdaa355f940e2 Mon Sep 17 00:00:00 2001 From: Maria Shodunke Date: Mon, 24 Mar 2025 13:32:11 +0000 Subject: [PATCH 6/7] Update admin doc intro with reference to non-admin version --- .../admin-api-methods/status-and-debugging-methods/feature.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/references/http-websocket-apis/admin-api-methods/status-and-debugging-methods/feature.md b/docs/references/http-websocket-apis/admin-api-methods/status-and-debugging-methods/feature.md index a3b34e54d1..c36708c43a 100644 --- a/docs/references/http-websocket-apis/admin-api-methods/status-and-debugging-methods/feature.md +++ b/docs/references/http-websocket-apis/admin-api-methods/status-and-debugging-methods/feature.md @@ -14,7 +14,7 @@ The `feature` command returns information about [amendments](../../../../concept You can use the `feature` command to configure the server to vote against or in favor of an amendment. This change persists even if you restart the server. {% badge href="https://github.com/XRPLF/rippled/releases/tag/1.7.0" %}Updated in: rippled 1.7.0{% /badge %} -_The `feature` method is an [admin method](../index.md) that cannot be run by unprivileged users._ +_The `feature` method documented on this page is an [admin method](../index.md). For the non-admin version, see the [`feature` public API method](../../public-api-methods/server-info-methods/feature.md)._ ### Request Format An example of the request format: From d905b9c68d6bc5191856640159872afcc91f5986 Mon Sep 17 00:00:00 2001 From: Maria Shodunke Date: Mon, 24 Mar 2025 18:06:23 +0000 Subject: [PATCH 7/7] Update with review comments for docs --- docs/references/http-websocket-apis/public-api-methods/index.md | 2 +- .../public-api-methods/server-info-methods/feature.md | 2 +- sidebars.yaml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/references/http-websocket-apis/public-api-methods/index.md b/docs/references/http-websocket-apis/public-api-methods/index.md index 4e2997bfa6..b9e58c3563 100644 --- a/docs/references/http-websocket-apis/public-api-methods/index.md +++ b/docs/references/http-websocket-apis/public-api-methods/index.md @@ -89,11 +89,11 @@ Use these methods to enable the server to push updates to your client when vario Use these methods to retrieve information about the current state of the `rippled` server. * **[`fee`](server-info-methods/fee.md)** - Get information about transaction cost. +* **[`feature`](server-info-methods/feature.md)** - Returns information about amendments this server knows about. * **[`server_info`](server-info-methods/server_info.md)** - Retrieve status of the server in human-readable format. * **[`server_state`](server-info-methods/server_state.md)** - Retrieve status of the server in machine-readable format. * **[`server_definitions`](server-info-methods/server_definitions.md)** - Retrieve a list of types and fields used for the XRPL's canonical binary format. * **[`manifest`](server-info-methods/manifest.md)** - Retrieve the latest ephemeral public key information about a known validator. -* **[`feature`](server-info-methods/feature.md)** - Returns information about amendments this server knows about. ## [Clio Methods](clio-methods/index.md) diff --git a/docs/references/http-websocket-apis/public-api-methods/server-info-methods/feature.md b/docs/references/http-websocket-apis/public-api-methods/server-info-methods/feature.md index a4b2abb688..f38ff976cb 100644 --- a/docs/references/http-websocket-apis/public-api-methods/server-info-methods/feature.md +++ b/docs/references/http-websocket-apis/public-api-methods/server-info-methods/feature.md @@ -136,7 +136,7 @@ The response follows the [standard format][], with a successful result containin - Any of the [universal error types][]. - `badFeature` - The `feature` specified was invalidly formatted, or the server does not know an amendment with that name. -- `noPermission` - The user does not have permission to run the specified command (i.e., `vetoed`). +- `noPermission` - The server does not have permission to run the specified command. For example, this can occur if the request includes admin-only fields that are not allowed, such as the `vetoed` request parameter. - `reportingUnsupported` - ([Reporting Mode][] servers only) This method is not available in Reporting Mode. {% raw-partial file="/docs/_snippets/common-links.md" /%} diff --git a/sidebars.yaml b/sidebars.yaml index 0919b9bcda..cf21a806d6 100644 --- a/sidebars.yaml +++ b/sidebars.yaml @@ -522,12 +522,12 @@ expanded: false items: - page: docs/references/http-websocket-apis/public-api-methods/server-info-methods/fee.md + - page: docs/references/http-websocket-apis/public-api-methods/server-info-methods/feature.md - page: docs/references/http-websocket-apis/public-api-methods/server-info-methods/manifest.md - page: docs/references/http-websocket-apis/public-api-methods/server-info-methods/server_definitions.md - page: docs/references/http-websocket-apis/public-api-methods/server-info-methods/server_info.md - page: docs/references/http-websocket-apis/public-api-methods/server-info-methods/server_state.md - page: docs/references/http-websocket-apis/public-api-methods/server-info-methods/version.md - - page: docs/references/http-websocket-apis/public-api-methods/server-info-methods/feature.md - page: docs/references/http-websocket-apis/public-api-methods/clio-methods/index.md expanded: false