ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-12 07:45:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

mpt_holders documentation cleanup

Browse Source
This commit is contained in:
Maria Shodunke
2025-04-30 11:29:06 +01:00
parent 0d908bff82
commit bedda2a7c7
4 changed files with 118 additions and 103 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
@theme/markdoc/components.tsx
View File

@@ -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: { export function TryIt(props: {
method: string, method: string,
@@ -164,6 +164,10 @@ export function TryIt(props: {
use_server = "?server=wss%3A%2F%2Fs.devnet.rippletest.net%3A51233%2F" use_server = "?server=wss%3A%2F%2Fs.devnet.rippletest.net%3A51233%2F"
} else if (props.server == 'testnet') { } else if (props.server == 'testnet') {
use_server = "?server=wss%3A%2F%2Fs.altnet.rippletest.net%3A51233%2F" 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}` const to_path = `/resources/dev-tools/websocket-api-tool${use_server}#${props.method}`
return ( return (

196
docs/references/http-websocket-apis/public-api-methods/clio-methods/mpt_holders.md
View File

@@ -3,156 +3,150 @@ blurb: Get the holders for a given `MPTokenIssuanceID` and ledger sequence.
labels: labels:
- Accounts - Accounts
- XRP - XRP
- Multi Purpose Tokens, MPTs
--- ---
# mpt_holders # mpt_holders
[[Source]](https://github.com/XRPLF/clio/blob/develop/src/rpc/handlers/MPTHolders.cpp "Source")
_(Requires the [MPTokensV1 amendment][] {% not-enabled /%})_ _(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 ## Request Format
*Websocket* {% tabs %}
{% tab label="WebSocket" %}
```json ```json
{ {
"command": "mpt_holders", "command": "mpt_holders",
"mpt_issuance_id": "00070C4495F14B0E44F78A264E41713C64B5F89242540EE255534400000000000000", "mpt_issuance_id": "0024D204E07DDDFBCD83B1649C07FE27FD536A3A32E6FDD8",
"ledger_index": "validated" "ledger_index": "validated"
} }
``` ```
{% /tab %}
*JSON-RPC* {% tab label="JSON-RPC" %}
```json ```json
{ {
"method": "mpt_holders", "method": "mpt_holders",
"params": [ "params": [
{ {
"mpt_issuance_id": "00070C4495F14B0E44F78A264E41713C64B5F89242540EE255534400000000000000", "mpt_issuance_id": "0024D204E07DDDFBCD83B1649C07FE27FD536A3A32E6FDD8",
"ledger_index": "validated" "ledger_index": "validated"
} }
] ]
} }
``` ```
{% /tab %}
{% /tabs %}
{% try-it method="mpt_holders" server="devnet-clio" /%}
The request contains the following parameters: The request contains the following parameters:
| Field | Type | Required? | Description | | Field | Type | Required? | Description |
|:------------------|:---------------------|:----------|-------------| |:------------------|:---------------------------|:----------|-------------|
| `mpt_issuance_id` | string | Yes | The `MPTokenIssuance` to query. | | `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_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. | | `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` | string | No | Used to continue your query where it left off in paginating. | | `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. | | `limit` | Number (positive integer) | No | Specify a limit to the number of MPTs returned. |
## Response Format ## Response Format
{% tabs %}
{% tab label="WebSocket" %}
```json ```json
{ {
"mpt_issuance_id": "000004C463C52827307480341125DA0577DEFC38405B0E3E", "result": {
"limit":50, "mpt_issuance_id": "0024D204E07DDDFBCD83B1649C07FE27FD536A3A32E6FDD8",
"ledger_index": 2, "limit": 50,
"mptokens": [{ "ledger_index": 2414929,
"account": "rEiNkzogdHEzUxPfsri5XSMqtXUixf2Yx", "mptokens": [
{
"account": "rfyWeQpYM3vCXRHA9cMLs2ZEdZv1F1jzm9",
"flags": 0, "flags": 0,
"mpt_amount": "20", "mpt_amount": "200",
"mptoken_index": "36D91DEE5EFE4A93119A8B84C944A528F2B444329F3846E49FE921040DE17E65" "mptoken_index": "22F99DCD55BCCF3D68DC3E4D6CF12602006A7563A6BE93FC57FD63298BCCEB13"
}, }
{ ],
"account": "rrnAZCqMahreZrKMcZU3t2DZ6yUndT4ubN",
"flags": 0,
"mpt_amount": "1",
"mptoken_index": "D137F2E5A5767A06CB7A8F060ADE442A30CFF95028E1AF4B8767E3A56877205A"
}],
"validated": true "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 ### Response Fields
The response follows the [standard format][], with the result containing the following fields: The response follows the [standard format][], with the result containing the following fields:
| Field | Type | Description | | Field | Type | Description |
|:-----------------------|:--------|:------------------------------------------| |:-----------------------|:-----------------|:------------------------------------------|
| `mpt_issuance_id` | string | The `MPTokenIssuance` queried | | `mpt_issuance_id` | String | The `MPTokenIssuance` queried. |
| `mptokens` | array | An array of mptokens. Includes all relevant fields in the underlying MPToken object. | | `mptokens` | Array | An array of [MPTokens](#mptoken). 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. | | `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 specfied in the request | `limit` | Number | The limit, as specified in the request. |
| `ledger_index` | number | The index of the ledger used. | | `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 | An `MPToken` object has the following parameters:
|:-----------------------|:--------|:------------------------------------------|
| `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. |
##### Example | Field | Type | Description |
Example of a `tx` response: |:-----------------------|:------------------|:------------------------------------------|
| `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 ## Possible Errors
{
"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
}
}
```
##### Object - Any of the [universal error types][].
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`. - `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
##### 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
}
}
```
{% raw-partial file="/docs/_snippets/common-links.md" /%} {% raw-partial file="/docs/_snippets/common-links.md" /%}

17
resources/dev-tools/components/websocket-api/data/command-list.json
View File

@@ -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", "group": "NFT Methods",
"methods": [ "methods": [

2
resources/dev-tools/components/websocket-api/data/connections.json
View File

@@ -53,7 +53,7 @@
"id": "connection-devnet-clio", "id": "connection-devnet-clio",
"ws_url": "wss://clio.devnet.rippletest.net:51233/", "ws_url": "wss://clio.devnet.rippletest.net:51233/",
"jsonrpc-url": "https://clio.devnet.rippletest.net:51234/", "jsonrpc-url": "https://clio.devnet.rippletest.net:51234/",
"shortname": "devnet-clio", "shortname": "Devnet-clio",
"longname": "clio.devnet.rippletest.net (Devnet Public Cluster with Clio)" "longname": "clio.devnet.rippletest.net (Devnet Public Cluster with Clio)"
} }
] ]