docs(solana): update HyperSync query API to the v0.2.0 shape - #1022
docs(solana): update HyperSync query API to the v0.2.0 shape#1022JasoonS wants to merge 1 commit into
Conversation
Bring the Solana HyperSync docs up to the latest query/response shape: - instruction_calls (was instructions), executing_account (was program_id), field_selection.instruction_call (was instruction), account_arguments (was accounts); legacy names still accepted as aliases, documented in a new "Renamed fields and compatibility" section. - New server-side is_committed instruction filter for excluding failed transactions, plus transaction_id / transaction_index selection filters. - Unified account_activity table replacing the removed balances / token_balances tables, with the native/token merge semantics and decimal-string token amounts. - Strict envelope: unknown top-level / field_selection keys are now rejected (removed tables error instead of silently matching everything). - Refresh curl examples and the overview table model to match. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughThe Solana HyperSync documentation now uses ChangesSolana HyperSync documentation
Estimated code review effort: 2 (Simple) | ~10 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/HyperSync/Solana/solana-curl-examples.md`:
- Around line 96-100: Update the OR-filter explanation in the Solana cURL
examples to refer to instruction_calls, matching the example payload. Keep
instructions identified only as the legacy input alias.
In `@docs/HyperSync/Solana/solana-query.md`:
- Line 64: Update the wording in the is_committed documentation so “land on
chain” uses the hyphenated form “land on-chain,” leaving the surrounding
explanation unchanged.
- Line 149: Update the documentation paragraph describing pre_token_balance and
post_token_balance to remove the claim that Token-2022 amounts can exceed
u64::MAX. Keep their raw base-unit decimal-string representation and state that
consumers interpret them using token_decimals; note that Token-2022 account and
instruction amounts use u64 and values above u64::MAX require a documented wider
endpoint type.
- Around line 31-32: Remove the unsupported include_account_activity field from
both envelope examples in the Solana query documentation, while leaving the
account_activity examples and all other query fields unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 734e6cd2-d8a0-455e-a664-09a0c034155d
📒 Files selected for processing (3)
docs/HyperSync/Solana/solana-curl-examples.mddocs/HyperSync/Solana/solana-query.mddocs/HyperSync/Solana/solana.md
| "instruction_call": ["slot", "executing_account", "data", "d8"] | ||
| }, | ||
| "instructions": [ | ||
| { "program_id": ["JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"] }, | ||
| { "program_id": ["whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc"] } | ||
| "instruction_calls": [ | ||
| { "executing_account": ["JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"] }, | ||
| { "executing_account": ["whirLbMiicVdio4qvUfM5KAg6Ct8VwpYzGff3uctyCc"] } |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Use instruction_calls in the OR-filter explanation.
The example uses instruction_calls, but the description still says instructions. instructions is documented as the legacy input alias.
-Each object in `instructions` is OR-ed.
+Each object in `instruction_calls` is OR-ed.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/HyperSync/Solana/solana-curl-examples.md` around lines 96 - 100, Update
the OR-filter explanation in the Solana cURL examples to refer to
instruction_calls, matching the example payload. Keep instructions identified
only as the legacy input alias.
| "account_activity": [ ... ], | ||
| "include_account_activity": false, |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/sh
set -eu
: "${URL:?set URL}"
: "${TOKEN:?set TOKEN}"
: "${FROM_SLOT:?set FROM_SLOT}"
: "${TO_SLOT:?set TO_SLOT}"
curl -sS "$URL/query" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d "{\"from_slot\":$FROM_SLOT,\"to_slot\":$TO_SLOT,\"include_account_activity\":false,\"field_selection\":{\"account_activity\":[\"slot\"]}}" |
jq .Repository: enviodev/docs
Length of output: 178
🏁 Script executed:
#!/bin/sh
set -eu
printf '%s\n' '--- candidate files ---'
git ls-files | grep -E '(^|/)(solana-query\.md|.*hyper.*solana.*|.*net-types.*)$' | head -80
printf '%s\n' '--- document context ---'
sed -n '1,90p' docs/HyperSync/Solana/solana-query.md
printf '%s\n' '--- field references ---'
rg -n -i 'include_account_activity|account_activity|hypersync-solana-net-types|unknown.*key|validation' .Repository: enviodev/docs
Length of output: 50371
🌐 Web query:
hypersync-solana-net-types v0.2.0 include_account_activity
💡 Result:
The field include_account_activity is not a valid or currently supported field in the hypersync-solana-net-types crate. Development history of the Envio Solana HyperSync tooling indicates that per-selection include_* flags (which were previously used to gate whether specific data, such as transactions or logs, were attached to emitted items) were removed in version 0.0.7 of the hypersync-solana-net-types and hypersync-client-solana crates [1][2]. In these newer versions, the server automatically applies a default data join based on the field_selection provided in the query, rendering explicit include_* flags unnecessary and obsolete [1][2]. If you are looking for specific account-related data, Envio's HyperIndex and HyperSync documentation clarifies that there is no dedicated onAccount or "account activity" handler [3]. Instead, account state is accessed via the accounts referenced within specific instructions, or through transaction-level data such as token balance changes [3]. You should structure your queries using field_selection and appropriate instruction filters (e.g., matching by program ID and discriminator) to retrieve the relevant data [4][1][2].
Citations:
- 1: Set Solana HyperSync user agent via new_with_agent (client v0.0.7) hyperindex#1307
- 2: enviodev/hyperindex@b0021f6
- 3: https://docs.envio.dev/docs/HyperIndex/solana.md
- 4: https://docs.envio.dev/docs/HyperSync/solana
🏁 Script executed:
#!/bin/sh
set -eu
tmpdir="$(mktemp -d)"
trap 'rm -rf "$tmpdir"' EXIT
printf '%s\n' '--- crates.io metadata ---'
curl -fsSL https://crates.io/api/v1/crates/hypersync-solana-net-types/0.2.0 |
jq '{name,version,dl主: .version.dl_path, crate_size: .version.crate_size}'
printf '%s\n' '--- crate source references ---'
url="$(curl -fsSL https://crates.io/api/v1/crates/hypersync-solana-net-types/0.2.0 |
jq -r '.version.dl_path')"
curl -fsSL "https://crates.io${url}" -o "$tmpdir/crate.tgz"
tar -xzf "$tmpdir/crate.tgz" -C "$tmpdir"
rg -n -i 'include_account_activity|include_.*activity|account_activity|deny_unknown_fields|Query' "$tmpdir" || true
printf '%s\n' '--- cited upstream change ---'
curl -fsSL https://api.github.com/repos/enviodev/hyperindex/pulls/1307 |
jq '{title,state,body,merged_at,html_url}'
curl -fsSL https://api.github.com/repos/enviodev/hyperindex/commits/b0021f6ab8331146286a8348e8ea414c2d967e84 |
jq '{sha:.sha,message:.commit.message,html_url}'Repository: enviodev/docs
Length of output: 641
🏁 Script executed:
#!/bin/sh
set -eu
tmpdir="$(mktemp -d)"
trap 'rm -rf "$tmpdir"' EXIT
printf '%s\n' '--- crates.io metadata ---'
curl -fsSL -A 'Mozilla/5.0' \
https://crates.io/api/v1/crates/hypersync-solana-net-types/0.2.0 |
jq '{name, version: .version.num, download_path: .version.dl_path, crate_size: .version.crate_size}'
printf '%s\n' '--- crate source ---'
curl -fsSL -A 'Mozilla/5.0' \
https://static.crates.io/crates/hypersync-solana-net-types/hypersync-solana-net-types-0.2.0.crate \
-o "$tmpdir/crate.tgz"
tar -xzf "$tmpdir/crate.tgz" -C "$tmpdir"
rg -n -i 'include_account_activity|include_.*activity|account_activity|deny_unknown_fields|Query' "$tmpdir" || true
printf '%s\n' '--- cited upstream change ---'
curl -fsSL -A 'Mozilla/5.0' \
https://api.github.com/repos/enviodev/hyperindex/pulls/1307 |
jq '{title,state,body,merged_at,html_url}'
curl -fsSL -A 'Mozilla/5.0' \
https://api.github.com/repos/enviodev/hyperindex/commits/b0021f6ab8331146286a8348e8ea414c2d967e84 |
jq '{sha:.sha,message:.commit.message,html_url}'Repository: enviodev/docs
Length of output: 299
🏁 Script executed:
#!/bin/sh
set -eu
printf '%s\n' '--- all occurrences in the document ---'
rg -n -C8 'include_account_activity|account_activity' docs/HyperSync/Solana/solana-query.md
printf '%s\n' '--- upstream references ---'
for url in \
'https://raw.githubusercontent.com/enviodev/hyperindex/main/packages/hypersync-solana-net-types/src/lib.rs' \
'https://raw.githubusercontent.com/enviodev/hyperindex/main/packages/hypersync-solana-net-types/src/query.rs' \
'https://raw.githubusercontent.com/enviodev/hyperindex/b0021f6ab8331146286a8348e8ea414c2d967e84/packages/hypersync-solana-net-types/src/lib.rs' \
'https://raw.githubusercontent.com/enviodev/hyperindex/b0021f6ab8331146286a8348e8ea414c2d967e84/packages/hypersync-solana-net-types/src/query.rs'
do
printf '\n--- %s ---\n' "$url"
curl -fsSL "$url" 2>/dev/null | rg -n -i 'include_account_activity|include_.*activity|account_activity|query' || true
done
printf '%s\n' '--- repository tree matches from GitHub API ---'
curl -fsSL 'https://api.github.com/repos/enviodev/hyperindex/git/trees/main?recursive=1' |
jq -r '.tree[]?.path' |
grep -Ei 'solana|hypersync.*types|net-types' |
head -100Repository: enviodev/docs
Length of output: 9017
Remove include_account_activity from the envelope examples.
hypersync-solana-net-types v0.2.0 does not support this top-level field. The strict query schema rejects it. Apply this change to both examples.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/HyperSync/Solana/solana-query.md` around lines 31 - 32, Remove the
unsupported include_account_activity field from both envelope examples in the
Solana query documentation, while leaving the account_activity examples and all
other query fields unchanged.
| | `is_inner` | `true` = inner only, `false` = outer only, **omitted** = both. | | ||
| | `is_committed` | `true` = only instructions of successful transactions, `false` = only instructions of failed transactions, **omitted** = both. See the note below. | | ||
|
|
||
| **`is_committed`:** Failed transactions still land on chain, and their instructions (up to the point of failure) are served. `is_committed` is derived from the parent transaction's success, so consumers that count on-chain effects should set `"is_committed": true` to filter failed transactions **server-side** rather than dropping them after the fact. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Use the hyphenated form on-chain.
Change “land on chain” to “land on-chain”.
Proposed wording fix
-Failed transactions still land on chain
+Failed transactions still land on-chain📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| **`is_committed`:** Failed transactions still land on chain, and their instructions (up to the point of failure) are served. `is_committed` is derived from the parent transaction's success, so consumers that count on-chain effects should set `"is_committed": true` to filter failed transactions **server-side** rather than dropping them after the fact. | |
| **`is_committed`:** Failed transactions still land on-chain, and their instructions (up to the point of failure) are served. `is_committed` is derived from the parent transaction's success, so consumers that count on-chain effects should set `"is_committed": true` to filter failed transactions **server-side** rather than dropping them after the fact. |
🧰 Tools
🪛 LanguageTool
[grammar] ~64-~64: Use a hyphen to join words.
Context: ...ed`:** Failed transactions still land on chain, and their instructions (up to the...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/HyperSync/Solana/solana-query.md` at line 64, Update the wording in the
is_committed documentation so “land on chain” uses the hyphenated form “land
on-chain,” leaving the surrounding explanation unchanged.
Source: Linters/SAST tools
| - **Native side** (`pre_balance`, `post_balance`, in lamports) is populated when the account's SOL balance changed in this transaction, null otherwise. | ||
| - **Token side** (`mint`, `owner`, `token_decimals`, `pre_token_balance`, `post_token_balance`, `pre_program_id`, `post_program_id`) is populated when the account appears in the transaction's token-balance metadata, null otherwise. | ||
|
|
||
| A row commonly carries **both** sides, since a token account also holds lamports; the native and token amounts are independent axes, not two encodings of one value (for wrapped SOL, lamports equal the token amount plus the rent-exempt reserve). `pre_token_balance` / `post_token_balance` are raw base-unit **decimal strings** (scaled by `token_decimals`), not numbers, because Token-2022 amounts can exceed `u64::MAX`. `account_index` is the account's position in the transaction's resolved key list (`account_keys` ++ ALT writable ++ ALT readonly); the flags (`is_signer`, `is_writable`, `is_fee_payer`, `from_lookup_table`) are derived from the message header and are null where a source could not supply them. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -e
printf '%s\n' '--- target lines ---'
sed -n '135,160p' docs/HyperSync/Solana/solana-query.md
printf '%s\n' '--- repository references ---'
rg -n -S 'pre_token_balance|post_token_balance|token_decimals|Token-2022|u64|v0\.2\.0' . \
-g '!node_modules' -g '!dist' -g '!build' | head -250Repository: enviodev/docs
Length of output: 9410
🌐 Web query:
docs.rs spl-token-2022-interface Account amount u64 token instruction amount u64 Token-2022
💡 Result:
In the Token-2022 (SPL Token 2022) program, the amount field in the Account state structure is defined as a u64 [1][2][3][4]. This field represents the raw number of tokens held by the account [5][2][3][4]. Similarly, for instruction data involving token transfers, minting, or burning (such as Transfer, MintTo, Burn, TransferChecked, etc.), the amount parameter is also defined as a u64 [6]. Key points regarding the use of u64 for token amounts in Token-2022: 1. Account Structure: The spl_token_2022_interface::state::Account (and its counterpart in the spl_token_2022 crate) stores the balance as a u64 [1][2][3]. It is serialized and deserialized using little-endian byte ordering [5][3][4]. 2. Instruction Data: Token-2022 instructions that require an amount to be specified (e.g., to indicate how many tokens to transfer or mint) use u64 in their instruction enums [6]. 3. Pod Types: When using the Pod (Plain Old Data) traits for account structures, the amount field is represented as a U64 type (a pod-compatible 64-bit unsigned integer) [7]. 4. UI Conversion: The SPL Token-2022 library provides utility functions like ui_amount_to_amount and amount_to_ui_amount which facilitate the conversion between human-readable UI amounts (often represented as floats or strings) and the raw u64 amounts used by the on-chain program [8][9]. The use of u64 limits the maximum raw token balance to 2^64 - 1 for any individual account [1][2][3].
Citations:
- 1: https://docs.rs/spl-token-2022-interface/latest/spl_token_2022_interface/state/struct.Account.html
- 2: https://docs.rs/spl-token-2022/latest/spl_token_2022/state/struct.Account.html
- 3: https://github.com/solana-program/token-2022/blob/program%40v10.0.0/interface/src/state.rs
- 4: https://github.com/solana-program/token-2022/blob/efd0c957fefbd79882d77df5fb2dac88c001249c/program/src/state.rs
- 5: https://docs.rs/spl-token-2022-interface/latest/src/spl_token_2022_interface/state.rs.html
- 6: https://docs.rs/spl-token-2022/latest/spl_token_2022/instruction/enum.TokenInstruction.html
- 7: https://docs.rs/spl-token-2022/latest/spl_token_2022/pod/struct.PodAccount.html
- 8: https://github.com/solana-labs/solana-program-library/blob/2d795f15287f6a0907bfe68f3fa252e30ee9572b/token/program-2022/src/lib.rs
- 9: https://docs.rs/crate/spl-token-2022/latest/source/src/lib.rs
🌐 Web query:
Solana transaction token balance metadata amount string decimals u64 Token-2022
💡 Result:
In the Solana Token-2022 program, token amounts are represented as 64-bit unsigned integers (u64) in the instruction data for operations like transfer, mint, and burn [1][2][3]. These u64 values represent the atomic, base units of the token, not the human-readable UI amount [1][2]. Key technical details regarding these amounts and metadata: Atomic Amounts (u64): Instruction variants such as TransferChecked, MintToChecked, and BurnChecked use a u64 field for the amount and a u8 field for decimals [2][3]. The program uses the decimals field to verify that the client is interacting with the correct token scale [2]. For example, if a token has 6 decimals, transferring 1 unit of the token requires an amount of 1,000,000 to be specified in the u64 field [1][2]. Metadata Strings: Unlike the legacy Metaplex metadata standard, which uses fixed-size padded fields, the Token-2022 Token Metadata extension uses true Borsh-encoded strings [4]. Each string (such as name, symbol, or URI) consists of a 4-byte little-endian u32 length prefix followed by the exact number of UTF-8 encoded bytes, with no padding [4]. Utilities and Conversions: The SPL Token program library provides utilities for converting between raw amounts (u64) and UI representations (float or string). - Conversion functions (e.g., amount_to_ui_amount_string) handle the division by 10^decimals to produce human-readable strings [5][6]. - These functions often rely on floating-point arithmetic, which is noted in documentation to have potential consistency issues for complex extensions (like interest-bearing tokens), so users are advised to be cautious when performing these conversions in sensitive contexts [7]. Instruction Data Layout: Token-2022 maintains compatibility with standard SPL Token instruction layouts [1]. The instruction data typically begins with a 1-byte discriminator [2]. For "Checked" variants, the layout is: [1-byte discriminator] + [8-byte u64 amount] + [1-byte u8 decimals] [1][2].
Citations:
- 1: https://www.solana-program.com/docs/token-2022
- 2: https://bytes.solrengine.org/learn/spl-token/instructions
- 3: https://docs.rs/spl-token-2022/latest/spl_token_2022/instruction/enum.TokenInstruction.html
- 4: https://bytes.solrengine.org/learn/token-2022/token-metadata-extension
- 5: https://docs.rs/crate/spl-token-2022/latest/source/src/lib.rs
- 6: https://github.com/solana-labs/solana-program-library/blob/2d795f15287f6a0907bfe68f3fa252e30ee9572b/token/program-2022/src/lib.rs
- 7: https://github.com/solana-program/token-2022/blob/program%40v10.0.0/interface/src/instruction.rs
🏁 Script executed:
#!/bin/bash
set -e
python3 - <<'PY'
from pathlib import Path
from urllib.request import urlopen
doc = Path("docs/HyperSync/Solana/solana-query.md").read_text()
needle = "pre_token_balance` / `post_token_balance` are raw base-unit **decimal strings**"
assert needle in doc
assert "because Token-2022 amounts can exceed `u64::MAX`" in doc
url = "https://docs.rs/spl-token-2022-interface/latest/src/spl_token_2022_interface/state.rs.html"
html = urlopen(url, timeout=10).read().decode("utf-8", "replace")
assert "amount" in html and "u64" in html
print("local serialization wording: present")
print("local overflow claim: present")
print("authoritative Token-2022 state source contains amount and u64: present")
PYRepository: enviodev/docs
Length of output: 2438
Remove the Token-2022 overflow claim. Keep the decimal-string serialization, but state that the raw base-unit amounts must be interpreted with token_decimals. Token-2022 account and instruction amounts use u64, so values above u64::MAX require a documented wider endpoint type.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/HyperSync/Solana/solana-query.md` at line 149, Update the documentation
paragraph describing pre_token_balance and post_token_balance to remove the
claim that Token-2022 amounts can exceed u64::MAX. Keep their raw base-unit
decimal-string representation and state that consumers interpret them using
token_decimals; note that Token-2022 account and instruction amounts use u64 and
values above u64::MAX require a documented wider endpoint type.
1 participant
Updates the HyperSync Solana docs (
docs/HyperSync/Solana/) to the latest query/response shape fromhypersync-solana-net-typesv0.2.0. Scoped to HyperSync only - no HyperIndex docs touched (HyperIndex is still on the old client and will be updated separately).What changed
instructions->instruction_calls(top-level query)program_id->executing_account(instruction selection + field)field_selection.instruction->instruction_callaccounts->account_arguments(instruction field), plus new derivedexecuting_account_index/account_index_argumentsis_committedinstruction filter (server-side failed-transaction exclusion), derived from parent-tx success, plus newtransaction_id/transaction_indextransaction filters.account_activitytable replacing the removedbalances/token_balancestables: native SOL + SPL token merged per (transaction, account), decimal-string token amounts, header-derived position flags. Oldbalance/token_balancefield-selection tables removed.field_selectionkeys are now rejected (a removed table errors instead of silently widening the query).Do not merge yet
The public
https://solana.hypersync.xyzendpoint is still serving the old client version. These docs describe the v0.2.0 shape (account_activity, strict envelope, new response field names), so they should land when that endpoint is upgraded. Staged as a PR per request; leaving merge timing to align with the endpoint rollout.🤖 Generated with Claude Code
Summary by CodeRabbit