Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix getTokenAccountsByOwner documentation: clarify required parameters #539

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 45 additions & 36 deletions docs/rpc/http/getTokenAccountsByOwner.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,18 +8,26 @@ altRoutes:

Returns all SPL Token accounts by token owner.

<DocSideBySide>
This method requires two parameters:

1. The owner's public key
2. An object specifying either the `mint` or the `programId`

<DocSideBySide>
<DocLeftSide>

### Parameters

<Parameter type={"string"} required={true}>
Pubkey of account delegate to query, as base-58 encoded string
Pubkey of account owner to query, as base-58 encoded string
</Parameter>

<Parameter type={"object"} required={true}>

A JSON object containing EITHER:
- `mint: <string>` - Pubkey of the specific token Mint to limit accounts to, as base-58 encoded string
- `programId: <string>` - Pubkey of the Token program that owns the accounts, as base-58 encoded string

A JSON object with either one of the following fields:

- `mint: <string>` - Pubkey of the specific token Mint to limit accounts to, as
Expand All @@ -30,8 +38,9 @@ A JSON object with either one of the following fields:
</Parameter>

<Parameter type={"object"} optional={true}>
Configuration object containing the following fields:

Configuration object containing the following fields:
{" "}

<Field
name="commitment"
Expand All @@ -40,49 +49,43 @@ Configuration object containing the following fields:
href="/docs/rpc/index.mdx#configuring-state-commitment"
/>

{" "}

<Field name="minContextSlot" type="number" optional={true}>
The minimum slot that the request can be evaluated at
</Field>

<Field name="dataSlice" type="object" optional={true}>
Request a slice of the account&apos;s data.

- `length: <usize>` - number of bytes to return
- `offset: <usize>` - byte offset from which to start reading

<Callout type={"info"}>
Data slicing is only available for `base58`, `base64`, or `base64+zstd`
encodings.
</Callout>

</Field>

<Field
name="encoding"
type="string"
optional={true}
href="/docs/rpc/index.mdx#parsed-responses"
>
<Field name="dataSlice" type="object" optional={true}>
Request a slice of the account's data.

Encoding format for Account data
- `length: <usize>` - number of bytes to return
- `offset: <usize>` - byte offset from which to start reading

<Values values={["base58", "base64", "base64+zstd", "jsonParsed"]} />
<Callout type={"info"}>
Data slicing is only available for `base58`, `base64`, or `base64+zstd` encodings.
</Callout>

<details>
</Field>

- `base58` is slow and limited to less than 129 bytes of Account data.
- `base64` will return base64 encoded data for Account data of any size.
- `base64+zstd` compresses the Account data using
[Zstandard](https://facebook.github.io/zstd/) and base64-encodes the result.
- `jsonParsed` encoding attempts to use program-specific state parsers to return
more human-readable and explicit account state data.
- If `jsonParsed` is requested but a parser cannot be found, the field falls
back to `base64` encoding, detectable when the `data` field is type `string`.
<Field
name="encoding"
type="string"
optional={true}
href="/docs/rpc/index.mdx#parsed-responses"
>
Encoding format for Account data

</details>
<Values values={["base58", "base64", "base64+zstd", "jsonParsed"]} />

</Field>
<details>
- `base58` is slow and limited to less than 129 bytes of Account data.
- `base64` will return base64 encoded data for Account data of any size.
- `base64+zstd` compresses the Account data using [Zstandard](https://facebook.github.io/zstd/) and base64-encodes the result.
- `jsonParsed` encoding attempts to use program-specific state parsers to return more human-readable and explicit account state data.
- If `jsonParsed` is requested but a parser cannot be found, the field falls back to `base64` encoding, detectable when the `data` field is type `string`.
</details>

</Field>
</Parameter>

### Result
Expand All @@ -98,7 +101,7 @@ JSON objects, which will contain:
- `data: <object>` - Token state data associated with the account, either as
encoded binary data or in JSON format `{<program>: <state>}`
- `executable: <bool>` - boolean indicating if the account contains a program
\(and is strictly read-only\)
(and is strictly read-only)
- `rentEpoch: <u64>` - the epoch at which this account will next owe rent, as
u64
- `size: <u64>` - the data size of the account
Expand All @@ -108,6 +111,9 @@ that of the [Token Balances Structure](/docs/rpc/json-structures#token-balances)
can be expected inside the structure, both for the `tokenAmount` and the
`delegatedAmount` - with the latter being an optional object.

> Note: The second parameter must include either `mint` or `programId`. You
> cannot omit both or include both simultaneously.

</DocLeftSide>

<DocRightSide>
Expand All @@ -123,6 +129,9 @@ curl https://api.devnet.solana.com -X POST -H "Content-Type: application/json" -
"params": [
"A1TMhSGzQxMr1TboBKtgixKz1sS6REASMxPo1qsyTSJd",
{
"mint": "3wyAj7Rt1TWVPZVteFJPLa26JmLvdb1CAKEFZm3NY75E"
// Alternatively, you can use "programId" instead of "mint":
// "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
"programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
},
{
Expand Down
Loading
Loading