Skip to content

Commit cd44b8e

Browse files
maria-robobugmaria-robobug
authored
Merge pull request #3104 from XRPLF/mpt-holders-doc-cleanup
Clean up mpt_holders reference documentation + add Try It
2 parents b06f58f + bedda2a commit cd44b8e

File tree

4 files changed

+117
-102
lines changed

4 files changed

+117
-102
lines changed

‎@theme/markdoc/components.tsx

+5-1
Original file line numberDiff line numberDiff line change
@@ -145,7 +145,7 @@ export function Badge(props: {
145145
}
146146
}
147147

148-
type TryItServer = 's1' | 's2' | 'xrplcluster' | 'testnet' | 'devnet'
148+
type TryItServer = 's1' | 's2' | 'xrplcluster' | 'testnet' | 'devnet' | 'testnet-clio' | 'devnet-clio'
149149

150150
export function TryIt(props: {
151151
method: string,
@@ -164,6 +164,10 @@ export function TryIt(props: {
164164
use_server = "?server=wss%3A%2F%2Fs.devnet.rippletest.net%3A51233%2F"
165165
} else if (props.server == 'testnet') {
166166
use_server = "?server=wss%3A%2F%2Fs.altnet.rippletest.net%3A51233%2F"
167+
} else if (props.server == 'testnet-clio') {
168+
use_server = "?server=wss%3A%2F%2Fclio.altnet.rippletest.net%3A51233%2F"
169+
} else if (props.server == 'devnet-clio') {
170+
use_server = "?server=wss%3A%2F%2Fclio.devnet.rippletest.net%3A51233%2F"
167171
}
168172
const to_path = `/resources/dev-tools/websocket-api-tool${use_server}#${props.method}`
169173
return (

‎docs/references/http-websocket-apis/public-api-methods/clio-methods/mpt_holders.md

+94-100
Original file line numberDiff line numberDiff line change
@@ -3,156 +3,150 @@ blurb: Get the holders for a given `MPTokenIssuanceID` and ledger sequence.
33
labels:
44
- Accounts
55
- XRP
6+
- Multi Purpose Tokens, MPTs
67
---
78

89
# mpt_holders
910

11+
[[Source]](https://github.com/XRPLF/clio/blob/develop/src/rpc/handlers/MPTHolders.cpp "Source")
12+
1013
_(Requires the [MPTokensV1 amendment][] {% not-enabled /%})_
1114

12-
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.
15+
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 %}
1316

1417
## Request Format
1518

16-
*Websocket*
19+
{% tabs %}
1720

21+
{% tab label="WebSocket" %}
1822
```json
1923
{
2024
"command": "mpt_holders",
21-
"mpt_issuance_id": "00070C4495F14B0E44F78A264E41713C64B5F89242540EE255534400000000000000",
25+
"mpt_issuance_id": "0024D204E07DDDFBCD83B1649C07FE27FD536A3A32E6FDD8",
2226
"ledger_index": "validated"
2327
}
2428
```
29+
{% /tab %}
2530

26-
*JSON-RPC*
27-
31+
{% tab label="JSON-RPC" %}
2832
```json
2933
{
3034
"method": "mpt_holders",
3135
"params": [
3236
{
33-
"mpt_issuance_id": "00070C4495F14B0E44F78A264E41713C64B5F89242540EE255534400000000000000",
37+
"mpt_issuance_id": "0024D204E07DDDFBCD83B1649C07FE27FD536A3A32E6FDD8",
3438
"ledger_index": "validated"
3539
}
3640
]
3741
}
3842
```
43+
{% /tab %}
3944

45+
{% /tabs %}
46+
47+
{% try-it method="mpt_holders" server="devnet-clio" /%}
4048

4149
The request contains the following parameters:
4250

43-
| Field | Type | Required? | Description |
44-
|:------------------|:---------------------|:----------|-------------|
45-
| `mpt_issuance_id` | string | Yes | The `MPTokenIssuance` to query. |
46-
| `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. |
47-
| `ledger_hash` | string | No | A 32-byte hex string for the ledger version to use. You must specify either ledger_index or ledger_hash. |
48-
| `marker` | string | No | Used to continue your query where it left off in paginating. |
49-
| `limit` | number (positive integer) | No | Specify a limit to the number of MPTs returned. |
51+
| Field | Type | Required? | Description |
52+
|:------------------|:---------------------------|:----------|-------------|
53+
| `mpt_issuance_id` | String | Yes | The `MPTokenIssuance` to query. |
54+
| `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][].|
55+
| `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][]. |
56+
| `marker` | [Marker][] | No | Used to continue your query where it left off in paginating. |
57+
| `limit` | Number (positive integer) | No | Specify a limit to the number of MPTs returned. |
5058

5159
## Response Format
5260

61+
{% tabs %}
62+
{% tab label="WebSocket" %}
5363
```json
5464
{
55-
"mpt_issuance_id": "000004C463C52827307480341125DA0577DEFC38405B0E3E",
56-
"limit":50,
57-
"ledger_index": 2,
58-
"mptokens": [{
59-
"account": "rEiNkzogdHEzUxPfsri5XSMqtXUixf2Yx",
65+
"result": {
66+
"mpt_issuance_id": "0024D204E07DDDFBCD83B1649C07FE27FD536A3A32E6FDD8",
67+
"limit": 50,
68+
"ledger_index": 2414929,
69+
"mptokens": [
70+
{
71+
"account": "rfyWeQpYM3vCXRHA9cMLs2ZEdZv1F1jzm9",
6072
"flags": 0,
61-
"mpt_amount": "20",
62-
"mptoken_index": "36D91DEE5EFE4A93119A8B84C944A528F2B444329F3846E49FE921040DE17E65"
63-
},
73+
"mpt_amount": "200",
74+
"mptoken_index": "22F99DCD55BCCF3D68DC3E4D6CF12602006A7563A6BE93FC57FD63298BCCEB13"
75+
}
76+
],
77+
"validated": true
78+
},
79+
"status": "success",
80+
"type": "response",
81+
"warnings": [
6482
{
65-
"account": "rrnAZCqMahreZrKMcZU3t2DZ6yUndT4ubN",
83+
"id": 2001,
84+
"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"
85+
}
86+
]
87+
}
88+
```
89+
{% /tab %}
90+
91+
{% tab label="JSON-RPC" %}
92+
```json
93+
200 OK
94+
95+
{
96+
"result": {
97+
"mpt_issuance_id": "0024D204E07DDDFBCD83B1649C07FE27FD536A3A32E6FDD8",
98+
"limit": 50,
99+
"ledger_index": 2415033,
100+
"mptokens": [
101+
{
102+
"account": "rfyWeQpYM3vCXRHA9cMLs2ZEdZv1F1jzm9",
66103
"flags": 0,
67-
"mpt_amount": "1",
68-
"mptoken_index": "D137F2E5A5767A06CB7A8F060ADE442A30CFF95028E1AF4B8767E3A56877205A"
69-
}],
70-
"validated": true
104+
"mpt_amount": "200",
105+
"mptoken_index": "22F99DCD55BCCF3D68DC3E4D6CF12602006A7563A6BE93FC57FD63298BCCEB13"
106+
}
107+
],
108+
"validated": true,
109+
"status": "success"
110+
},
111+
"warnings": [
112+
{
113+
"id": 2001,
114+
"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"
115+
}
116+
]
71117
}
72118
```
119+
{% /tab %}
120+
121+
{% /tabs %}
73122

74123
### Response Fields
75124

76125
The response follows the [standard format][], with the result containing the following fields:
77126

78-
| Field | Type | Description |
79-
|:-----------------------|:--------|:------------------------------------------|
80-
| `mpt_issuance_id` | string | The `MPTokenIssuance` queried |
81-
| `mptokens` | array | An array of mptokens. Includes all relevant fields in the underlying MPToken object. |
82-
| `marker` | string | Used to continue querying where we left off when paginating. Omitted if there are no more entries after this result. |
83-
| `limit` | number | The limit, as specfied in the request
84-
| `ledger_index` | number | The index of the ledger used. |
127+
| Field | Type | Description |
128+
|:-----------------------|:-----------------|:------------------------------------------|
129+
| `mpt_issuance_id` | String | The `MPTokenIssuance` queried. |
130+
| `mptokens` | Array | An array of [MPTokens](#mptoken). Includes all relevant fields in the underlying `MPToken` object. |
131+
| `marker` | [Marker][] | Used to continue querying where we left off when paginating. Omitted if there are no more entries after this result. |
132+
| `limit` | Number | The limit, as specified in the request. |
133+
| `ledger_index` | [Ledger Index][] | The index of the ledger used. |
134+
| `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. |
85135

86-
An `mptoken` object has the following parameters:
136+
#### MPToken
87137

88-
| Field | Type | Description |
89-
|:-----------------------|:--------|:------------------------------------------|
90-
| `account` | string | The account address of the holder who owns the `MPToken`. |
91-
| `flags` | number | The flags assigned to the`MPToken` object. |
92-
| `mpt_amount` | string | Base 10-encoded amount of the holder's balance. |
93-
| `mptoken_index` | string | Key of the `MPToken` object. |
138+
An `MPToken` object has the following parameters:
94139

95-
##### Example
96-
Example of a `tx` response:
140+
| Field | Type | Description |
141+
|:-----------------------|:------------------|:------------------------------------------|
142+
| `account` | String | The account address of the holder who owns the `MPToken`. |
143+
| `flags` | Number | The flags assigned to the`MPToken` object. |
144+
| `mpt_amount` | [String Number][] | Specifies a positive amount of tokens currently held by the owner. |
145+
| `mptoken_index` | String | Key of the `MPToken` object. |
97146

98-
```json
99-
{
100-
"result": {
101-
"Account": "rBT9cUqK6UvpvZhPFNQ2qpUTin8rDokBeL",
102-
"AssetScale": 2,
103-
"Fee": "10",
104-
"Flags": 64,
105-
"Sequence": 303,
106-
"SigningPubKey": "ED39955DEA2D083C6CBE459951A0A84DB337925389ACA057645EE6E6BA99D4B2AE",
107-
"TransactionType": "MPTokenIssuanceCreate",
108-
"TxnSignature": "80D7B7409980BE9854F7217BB8E836C8A2A191E766F24B5EF2EA7609E1420AABE6A1FDB3038468679081A45563B4D0B49C08F4F70F64E41B578F288A208E4206",
109-
"ctid": "C000013100000000",
110-
"date": 760643692,
111-
"hash": "E563D7942E3E4A79AD73EC12E9E4C44B7C9950DF7BF5FDB75FAD0F5CE0554DB3",
112-
"inLedger": 305,
113-
"ledger_index": 305,
114-
"meta": {
115-
"AffectedNodes": [...],
116-
"TransactionIndex": 0,
117-
"TransactionResult": "tesSUCCESS",
118-
"mpt_issuance_id": "0000012F72A341F09A988CDAEA4FF5BE31F25B402C550ABE"
119-
},
120-
"status": "success",
121-
"validated": true
122-
}
123-
}
124-
```
147+
## Possible Errors
125148

126-
##### Object
127-
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`.
128-
129-
##### Example
130-
Example of an `account_objects` response:
131-
132-
```json
133-
{
134-
"result": {
135-
"account": "rBT9cUqK6UvpvZhPFNQ2qpUTin8rDokBeL",
136-
"account_objects": [
137-
{
138-
"AssetScale": 2,
139-
"Flags": 64,
140-
"Issuer": "rBT9cUqK6UvpvZhPFNQ2qpUTin8rDokBeL",
141-
"LedgerEntryType": "MPTokenIssuance",
142-
"OutstandingAmount": "100",
143-
"OwnerNode": "0",
144-
"PreviousTxnID": "BDC5ECA6B115C74BF4DA83E36325A2F55DF9E2C968A5CC15EB4D009D87D5C7CA",
145-
"PreviousTxnLgrSeq": 308,
146-
"Sequence": 303,
147-
"index": "75EC6F2939ED6C5798A5F369A0221BC4F6DDC50F8614ECF72E3B976351057A63",
148-
"mpt_issuance_id": "0000012F72A341F09A988CDAEA4FF5BE31F25B402C550ABE"
149-
}
150-
],
151-
"ledger_current_index": 309,
152-
"status": "success",
153-
"validated": false
154-
}
155-
}
156-
```
149+
- Any of the [universal error types][].
150+
- `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
157151

158152
{% raw-partial file="/docs/_snippets/common-links.md" /%}

‎resources/dev-tools/components/websocket-api/data/command-list.json

+17
Original file line numberDiff line numberDiff line change
@@ -409,6 +409,23 @@
409409
}
410410
]
411411
},
412+
{
413+
"group": "MPT Methods",
414+
"methods": [
415+
{
416+
"name": "mpt_holders",
417+
"description": "Return all holders of an MPT and their balance (Clio only).",
418+
"link": "/docs/references/http-websocket-apis/public-api-methods/clio-methods/mpt_holders",
419+
"clio_only": true,
420+
"body": {
421+
"id": "example_mpt_holders",
422+
"command": "mpt_holders",
423+
"mpt_issuance_id": "0024D204E07DDDFBCD83B1649C07FE27FD536A3A32E6FDD8",
424+
"ledger_index": "validated"
425+
}
426+
}
427+
]
428+
},
412429
{
413430
"group": "NFT Methods",
414431
"methods": [

‎resources/dev-tools/components/websocket-api/data/connections.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@
5353
"id": "connection-devnet-clio",
5454
"ws_url": "wss://clio.devnet.rippletest.net:51233/",
5555
"jsonrpc-url": "https://clio.devnet.rippletest.net:51234/",
56-
"shortname": "devnet-clio",
56+
"shortname": "Devnet-clio",
5757
"longname": "clio.devnet.rippletest.net (Devnet Public Cluster with Clio)"
5858
}
5959
]

0 commit comments

Comments
 (0)