From bedda2a7c73977dade2a5e2dfc2c3da86a05cc57 Mon Sep 17 00:00:00 2001 From: Maria Shodunke Date: Wed, 30 Apr 2025 11:29:06 +0100 Subject: [PATCH] mpt_holders documentation cleanup --- @theme/markdoc/components.tsx | 6 +- .../clio-methods/mpt_holders.md | 196 +++++++++--------- .../websocket-api/data/command-list.json | 17 ++ .../websocket-api/data/connections.json | 2 +- 4 files changed, 118 insertions(+), 103 deletions(-) diff --git a/@theme/markdoc/components.tsx b/@theme/markdoc/components.tsx index 168f8752bc..ab52987844 100644 --- a/@theme/markdoc/components.tsx +++ b/@theme/markdoc/components.tsx @@ -145,7 +145,7 @@ export function Badge(props: { } } -type TryItServer = 's1' | 's2' | 'xrplcluster' | 'testnet' | 'devnet' +type TryItServer = 's1' | 's2' | 'xrplcluster' | 'testnet' | 'devnet' | 'testnet-clio' | 'devnet-clio' export function TryIt(props: { method: string, @@ -164,6 +164,10 @@ export function TryIt(props: { use_server = "?server=wss%3A%2F%2Fs.devnet.rippletest.net%3A51233%2F" } else if (props.server == 'testnet') { use_server = "?server=wss%3A%2F%2Fs.altnet.rippletest.net%3A51233%2F" + } else if (props.server == 'testnet-clio') { + use_server = "?server=wss%3A%2F%2Fclio.altnet.rippletest.net%3A51233%2F" + } else if (props.server == 'devnet-clio') { + use_server = "?server=wss%3A%2F%2Fclio.devnet.rippletest.net%3A51233%2F" } const to_path = `/resources/dev-tools/websocket-api-tool${use_server}#${props.method}` return ( diff --git a/docs/references/http-websocket-apis/public-api-methods/clio-methods/mpt_holders.md b/docs/references/http-websocket-apis/public-api-methods/clio-methods/mpt_holders.md index 63a2923f28..ef66251d7e 100644 --- a/docs/references/http-websocket-apis/public-api-methods/clio-methods/mpt_holders.md +++ b/docs/references/http-websocket-apis/public-api-methods/clio-methods/mpt_holders.md @@ -3,156 +3,150 @@ blurb: Get the holders for a given `MPTokenIssuanceID` and ledger sequence. labels: - Accounts - XRP + - Multi Purpose Tokens, MPTs --- # mpt_holders +[[Source]](https://github.com/XRPLF/clio/blob/develop/src/rpc/handlers/MPTHolders.cpp "Source") + _(Requires the [MPTokensV1 amendment][] {% not-enabled /%})_ -For a given `MPTokenIssuanceID` and ledger sequence, `mpt_holders` returns all holders of that MPT and their balance. This method likely returns very large data sets, so you should expect to implement paging via the `marker` field. This API is only available using Clio, not rippled. +For a given `MPTokenIssuanceID` and ledger sequence, `mpt_holders` returns all holders of that [MPT](../../../../concepts/tokens/fungible-tokens/multi-purpose-tokens.md) and their balance. This method likely returns very large data sets, so you should expect to implement paging via the `marker` field. This API is only available using Clio, not `rippled`. {% badge href="https://github.com/XRPLF/clio/releases/tag/2.3.0" %}New in: Clio v2.3.0{% /badge %} ## Request Format -*Websocket* +{% tabs %} +{% tab label="WebSocket" %} ```json { "command": "mpt_holders", - "mpt_issuance_id": "00070C4495F14B0E44F78A264E41713C64B5F89242540EE255534400000000000000", + "mpt_issuance_id": "0024D204E07DDDFBCD83B1649C07FE27FD536A3A32E6FDD8", "ledger_index": "validated" } ``` +{% /tab %} -*JSON-RPC* - +{% tab label="JSON-RPC" %} ```json { "method": "mpt_holders", "params": [ { - "mpt_issuance_id": "00070C4495F14B0E44F78A264E41713C64B5F89242540EE255534400000000000000", + "mpt_issuance_id": "0024D204E07DDDFBCD83B1649C07FE27FD536A3A32E6FDD8", "ledger_index": "validated" } ] } ``` +{% /tab %} +{% /tabs %} + +{% try-it method="mpt_holders" server="devnet-clio" /%} The request contains the following parameters: -| Field | Type | Required? | Description | -|:------------------|:---------------------|:----------|-------------| -| `mpt_issuance_id` | string | Yes | The `MPTokenIssuance` to query. | -| `ledger_index` | string or number (positive integer) | No | The ledger index of the max ledger to use, ora shortcut string to choose a ledger automatically. You must specify either ledger_index or ledger_hash. | -| `ledger_hash` | string | No | A 32-byte hex string for the ledger version to use. You must specify either ledger_index or ledger_hash. | -| `marker` | string | No | Used to continue your query where it left off in paginating. | -| `limit` | number (positive integer) | No | Specify a limit to the number of MPTs returned. | +| Field | Type | Required? | Description | +|:------------------|:---------------------------|:----------|-------------| +| `mpt_issuance_id` | String | Yes | The `MPTokenIssuance` to query. | +| `ledger_index` | [Ledger Index][] | No | The [Ledger Index][] of the max ledger to use, or a shortcut string to choose a ledger automatically. You must specify either `ledger_index` or `ledger_hash`. See [Specifying Ledgers][].| +| `ledger_hash` | String | No | A 32-byte hex string for the ledger version to use. You must specify either `ledger_index` or ledger_hash. See [Specifying Ledgers][]. | +| `marker` | [Marker][] | No | Used to continue your query where it left off in paginating. | +| `limit` | Number (positive integer) | No | Specify a limit to the number of MPTs returned. | ## Response Format +{% tabs %} +{% tab label="WebSocket" %} ```json { - "mpt_issuance_id": "000004C463C52827307480341125DA0577DEFC38405B0E3E", - "limit":50, - "ledger_index": 2, - "mptokens": [{ - "account": "rEiNkzogdHEzUxPfsri5XSMqtXUixf2Yx", + "result": { + "mpt_issuance_id": "0024D204E07DDDFBCD83B1649C07FE27FD536A3A32E6FDD8", + "limit": 50, + "ledger_index": 2414929, + "mptokens": [ + { + "account": "rfyWeQpYM3vCXRHA9cMLs2ZEdZv1F1jzm9", "flags": 0, - "mpt_amount": "20", - "mptoken_index": "36D91DEE5EFE4A93119A8B84C944A528F2B444329F3846E49FE921040DE17E65" - }, - { - "account": "rrnAZCqMahreZrKMcZU3t2DZ6yUndT4ubN", - "flags": 0, - "mpt_amount": "1", - "mptoken_index": "D137F2E5A5767A06CB7A8F060ADE442A30CFF95028E1AF4B8767E3A56877205A" - }], + "mpt_amount": "200", + "mptoken_index": "22F99DCD55BCCF3D68DC3E4D6CF12602006A7563A6BE93FC57FD63298BCCEB13" + } + ], "validated": true + }, + "status": "success", + "type": "response", + "warnings": [ + { + "id": 2001, + "message": "This is a clio server. clio only serves validated data. If you want to talk to rippled, include 'ledger_index':'current' in your request" + } + ] } ``` +{% /tab %} + +{% tab label="JSON-RPC" %} +```json +200 OK + +{ + "result": { + "mpt_issuance_id": "0024D204E07DDDFBCD83B1649C07FE27FD536A3A32E6FDD8", + "limit": 50, + "ledger_index": 2415033, + "mptokens": [ + { + "account": "rfyWeQpYM3vCXRHA9cMLs2ZEdZv1F1jzm9", + "flags": 0, + "mpt_amount": "200", + "mptoken_index": "22F99DCD55BCCF3D68DC3E4D6CF12602006A7563A6BE93FC57FD63298BCCEB13" + } + ], + "validated": true, + "status": "success" + }, + "warnings": [ + { + "id": 2001, + "message": "This is a clio server. clio only serves validated data. If you want to talk to rippled, include 'ledger_index':'current' in your request" + } + ] +} +``` +{% /tab %} + +{% /tabs %} ### Response Fields The response follows the [standard format][], with the result containing the following fields: -| Field | Type | Description | -|:-----------------------|:--------|:------------------------------------------| -| `mpt_issuance_id` | string | The `MPTokenIssuance` queried | -| `mptokens` | array | An array of mptokens. Includes all relevant fields in the underlying MPToken object. | -| `marker` | string | Used to continue querying where we left off when paginating. Omitted if there are no more entries after this result. | -| `limit` | number | The limit, as specfied in the request -| `ledger_index` | number | The index of the ledger used. | +| Field | Type | Description | +|:-----------------------|:-----------------|:------------------------------------------| +| `mpt_issuance_id` | String | The `MPTokenIssuance` queried. | +| `mptokens` | Array | An array of [MPTokens](#mptoken). Includes all relevant fields in the underlying `MPToken` object. | +| `marker` | [Marker][] | Used to continue querying where we left off when paginating. Omitted if there are no more entries after this result. | +| `limit` | Number | The limit, as specified in the request. | +| `ledger_index` | [Ledger Index][] | The index of the ledger used. | +| `validated` | Boolean | If `true`, the ledger has been validated by the consensus process and is immutable. Otherwise, the contents of the ledger are not final and may change. In Clio, this is _always_ true as Clio stores and returns validated ledger data. | -An `mptoken` object has the following parameters: +#### MPToken -| Field | Type | Description | -|:-----------------------|:--------|:------------------------------------------| -| `account` | string | The account address of the holder who owns the `MPToken`. | -| `flags` | number | The flags assigned to the`MPToken` object. | -| `mpt_amount` | string | Base 10-encoded amount of the holder's balance. | -| `mptoken_index` | string | Key of the `MPToken` object. | +An `MPToken` object has the following parameters: -##### Example -Example of a `tx` response: +| Field | Type | Description | +|:-----------------------|:------------------|:------------------------------------------| +| `account` | String | The account address of the holder who owns the `MPToken`. | +| `flags` | Number | The flags assigned to the`MPToken` object. | +| `mpt_amount` | [String Number][] | Specifies a positive amount of tokens currently held by the owner. | +| `mptoken_index` | String | Key of the `MPToken` object. | -```json -{ - "result": { - "Account": "rBT9cUqK6UvpvZhPFNQ2qpUTin8rDokBeL", - "AssetScale": 2, - "Fee": "10", - "Flags": 64, - "Sequence": 303, - "SigningPubKey": "ED39955DEA2D083C6CBE459951A0A84DB337925389ACA057645EE6E6BA99D4B2AE", - "TransactionType": "MPTokenIssuanceCreate", - "TxnSignature": "80D7B7409980BE9854F7217BB8E836C8A2A191E766F24B5EF2EA7609E1420AABE6A1FDB3038468679081A45563B4D0B49C08F4F70F64E41B578F288A208E4206", - "ctid": "C000013100000000", - "date": 760643692, - "hash": "E563D7942E3E4A79AD73EC12E9E4C44B7C9950DF7BF5FDB75FAD0F5CE0554DB3", - "inLedger": 305, - "ledger_index": 305, - "meta": { - "AffectedNodes": [...], - "TransactionIndex": 0, - "TransactionResult": "tesSUCCESS", - "mpt_issuance_id": "0000012F72A341F09A988CDAEA4FF5BE31F25B402C550ABE" - }, - "status": "success", - "validated": true - } -} -``` +## Possible Errors -##### Object -An `mpt_issuance_id` field is provided in JSON MPTokenIssuance objects (not available for binary). The following APIs are impacted: `ledger_data` and `account_objects`. - -##### Example -Example of an `account_objects` response: - -```json -{ - "result": { - "account": "rBT9cUqK6UvpvZhPFNQ2qpUTin8rDokBeL", - "account_objects": [ - { - "AssetScale": 2, - "Flags": 64, - "Issuer": "rBT9cUqK6UvpvZhPFNQ2qpUTin8rDokBeL", - "LedgerEntryType": "MPTokenIssuance", - "OutstandingAmount": "100", - "OwnerNode": "0", - "PreviousTxnID": "BDC5ECA6B115C74BF4DA83E36325A2F55DF9E2C968A5CC15EB4D009D87D5C7CA", - "PreviousTxnLgrSeq": 308, - "Sequence": 303, - "index": "75EC6F2939ED6C5798A5F369A0221BC4F6DDC50F8614ECF72E3B976351057A63", - "mpt_issuance_id": "0000012F72A341F09A988CDAEA4FF5BE31F25B402C550ABE" - } - ], - "ledger_current_index": 309, - "status": "success", - "validated": false - } -} -``` +- Any of the [universal error types][]. +- `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing. {% raw-partial file="/docs/_snippets/common-links.md" /%} 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 094cc95a7e..6839b323c1 100644 --- a/resources/dev-tools/components/websocket-api/data/command-list.json +++ b/resources/dev-tools/components/websocket-api/data/command-list.json @@ -409,6 +409,23 @@ } ] }, + { + "group": "MPT Methods", + "methods": [ + { + "name": "mpt_holders", + "description": "Return all holders of an MPT and their balance (Clio only).", + "link": "/docs/references/http-websocket-apis/public-api-methods/clio-methods/mpt_holders", + "clio_only": true, + "body": { + "id": "example_mpt_holders", + "command": "mpt_holders", + "mpt_issuance_id": "0024D204E07DDDFBCD83B1649C07FE27FD536A3A32E6FDD8", + "ledger_index": "validated" + } + } + ] + }, { "group": "NFT Methods", "methods": [ diff --git a/resources/dev-tools/components/websocket-api/data/connections.json b/resources/dev-tools/components/websocket-api/data/connections.json index 2802c386b3..1186fe5fab 100644 --- a/resources/dev-tools/components/websocket-api/data/connections.json +++ b/resources/dev-tools/components/websocket-api/data/connections.json @@ -53,7 +53,7 @@ "id": "connection-devnet-clio", "ws_url": "wss://clio.devnet.rippletest.net:51233/", "jsonrpc-url": "https://clio.devnet.rippletest.net:51234/", - "shortname": "devnet-clio", + "shortname": "Devnet-clio", "longname": "clio.devnet.rippletest.net (Devnet Public Cluster with Clio)" } ]