Solana instruction indexing foundation

[JasoonS]

Summary by CodeRabbit

• New Features

  • Added Solana (SVM) instruction indexing via HyperSync for streaming and decoding program instructions with Borsh schema support.
  • Introduced Metaplex Token Metadata template for indexing NFT metadata creation and updates.

• Documentation

  • Added template guides and quick-start instructions for SVM indexing.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR implements end-to-end Solana SVM instruction indexing. It adds YAML schemas for configuring Solana programs and instructions, integrates Borsh decoding via Rust/N-API, extends HyperSync to query Solana instruction data, generates typed ReScript/TypeScript handler code with decoded instruction arguments, and provides a complete Metaplex Token Metadata demo with tests.

Changes

SVM Instruction Indexing Support

Layer / File(s)	Summary
Design decisions, SVM schema types, and CLI surface STAGE_7B_DECISIONS.md, packages/cli/Cargo.toml, packages/cli/CommandLineHelp.md, packages/cli/src/cli_args/init_config.rs, packages/cli/src/cli_args/interactive_init/mod.rs, packages/cli/src/config_parsing/human_config.rs, packages/cli/src/template_dirs.rs, packages/cli/templates/dynamic/init_templates/shared/package.json.hbs, packages/cli/templates/static/shared/pnpm-workspace.yaml	Documents schema-lookup design (opaque handles), bundled schema auto-attachment, typed codegen for args/accounts, YAML validation rules, and envio init --idl behavior. Introduces HypersyncConfig type, optional programs_experimental list, and Borsh argument grammars (ArgDef, ArgType, ArgPrimitive, ArgComposite, ArgEnumVariant, filters). Updates SVM CLI template selection to interactively choose between Metaplex and feature templates. Adds pnpm build configuration.
YAML validation and system config translation packages/cli/src/config_parsing/validation.rs, packages/cli/src/config_parsing/system_config.rs, packages/cli/src/config_parsing/public_config.rs, packages/envio/svm.schema.json	Validates SVM YAML (base58 pubkeys, hex discriminators, account filter constraints). Resolves program schemas from IDL paths, bundled entries (Metaplex Token Metadata), or inline definitions. Builds DataSource::Svm with optional HyperSync URL, derives EventKind::Svm per instruction with discriminator bytes and (accounts, args) layouts. Emits Abi::Svm(SvmAbi) with schema source and defined types. Generates public SvmConfig JSON with programs map and SvmEventItem descriptors.
Trace query support and HyperSync N-API initialization packages/cli/src/hypersync_source/mod.rs, packages/cli/src/hypersync_source/query.rs, packages/envio/src/sources/HyperSyncClient.res	Extends HyperSync client API with optional trace field selections (d1/d2/d4/d8 discriminators, a0-a9 accounts, addresses, call types, sighashes) and max_num_traces limits. Adds set_log_level N-API function and HypersyncClient::new constructor delegating to new_with_agent with auto-set user-agent.
Rust/N-API Borsh decoder, Solana queries, and client packages/cli/src/hypersync_source_svm/borsh_decoder.rs, packages/cli/src/hypersync_source_svm/config.rs, packages/cli/src/hypersync_source_svm/mod.rs, packages/cli/src/hypersync_source_svm/query.rs, packages/cli/src/hypersync_source_svm/types.rs, packages/cli/src/lib.rs, packages/envio/src/sources/HyperSyncSolanaClient.res	Implements process-global schema registry via register_program_schema (returns stable u32 handle) and decode_instruction (returns optional decoded args/named accounts/extra accounts). Defines SolanaQuery and nested InstructionSelection/TransactionSelection/LogSelection/FieldSelection with i64 slot/count inputs. Exports HypersyncSolanaClient wrapping hypersync_client_solana::Client, providing get_height and get async methods. Defines response types: Block, Transaction, Instruction (with optional d1-d8 discriminator prefixes, a0-a5 account filters, decoded payload), Log, TokenBalance, Reward, QueryResponse.
Runtime types, addon interface, and event config builders packages/envio/src/Core.res, packages/envio/src/Envio.res, packages/envio/src/Internal.res, packages/envio/src/EventConfigBuilder.res	Adds ReScript types for decoded instructions (svmDecodedInstruction), raw instructions with optional decoded data (svmInstruction), parent transactions and token balances (svmTransaction, svmTokenBalance), per-instruction logs (svmLog), and event payloads (svmInstructionEvent). Introduces svmInstructionEventConfig with program id, discriminator/byte-length, inclusion toggles, account filters, and positional args/defined types. Exposes addon methods: setLogLevel, registerProgramSchema, decodeInstruction. Implements buildSvmInstructionEventConfig builder deriving parameter schema and wiring identity/flags.
Code generation for SVM events and handler types packages/cli/src/hbs_templating/codegen_templates.rs, packages/cli/src/hbs_templating/contract_import_templates.rs, packages/envio/index.d.ts	Generates per-instruction ReScript event modules via EventTemplate::from_config_event(EventKind::Svm(_)) (minimal svmInstruction params, no-op where filter). Adds SVM indexer onInstruction registration type and onInstructionOptions callback signature. Emits TypeScript svm_programs table under Global.config.svm.programs with per-instruction typed args (recursively mapped from Solana Borsh schemas with cycle detection) and string-keyed accounts shapes. Adds public TypeScript types: SvmDecodedInstruction, SvmInstruction, SvmTokenBalance, SvmTransaction, SvmLog, SvmInstructionEvent<Decoded>, handler args/options/signatures.
Config parsing, event routing, and source wiring packages/envio/src/Config.res, packages/envio/src/sources/EventRouter.res, packages/envio/src/sources/Svm.res, packages/envio/src/ChainFetcher.res	Parses SVM program/event/ABI from public config. buildContractEvents derives single programId from chain addresses, converts account filter pubkeys, builds instruction event configs via buildSvmInstructionEventConfig. Event router adds getSvmEventId (programId + discriminator/none suffix) and fromSvmEventConfigsOrThrow (precomputes per-program discriminator byte-length descending ordering for longest-first routing). makeRPCSource now accepts configurable sourceFor parameter. ChainFetcher conditionally creates HyperSyncSolanaSource (if hypersync URL present) with fallback to RPC oracle source.
HyperSync Solana source orchestration packages/envio/src/sources/HyperSyncSolanaSource.res	Builds instruction selections with account filter grouping and discriminator byte-length ordering from event configs. Groups configs by programId, registers schemas once at startup, precomputes schema handles and whether token balances are needed. Fetches blocks/instructions/logs/transactions via HyperSync client. Indexes fetched data by (slot, txIndex) and (slot, txIndex, instructionAddress) keys. Routes each instruction using discriminator-keyed lookup (longest-first probe with program-wide fallback), decodes payload, synthesizes deterministic logIndex, attaches transaction/logs/token-balances conditionally, materializes svmInstructionEvent payloads. Exposes getBlockHashes (throws unsupported) and getHeightOrThrow with Prometheus metrics.
Handler registration, metadata reload, and UI updates packages/envio/src/Main.res, packages/envio/src/HandlerLoader.res, packages/envio/src/Hasura.res, packages/envio/src/SimulateItems.res, packages/envio/src/SvmTypes.res, packages/envio/src/tui/Tui.res, packages/envio/src/tui/components/TuiData.res	Adds onInstruction handler registration parsing SVM identity ({program, instruction} or ReScript GADT), wiring to HandlerRegister.setHandler. Replaces prior SVM error path with SVM instruction event config construction. Adds reloadHasuraMetadata REST call after schema clearing to force re-introspection. Updates patchConfig to apply startBlock/endBlock overrides even when no simulate items present. Introduces SvmTypes.Pubkey module with schema/externals for pubkey/array conversions. Updates TUI to compute per-chain blockUnit ("Slots" for SVM, "Blocks" for EVM/Fuel) and render dynamic progress labels.
Metaplex metadata indexer template and scenario packages/cli/templates/static/svm_metaplex_template/*, scenarios/svm_metaplex_demo/*, scenarios/test_codegen/test/*_test.res, packages/cli/test/configs/svm-metaplex-config.yaml	Provides Metaplex Token Metadata CLI template: .env.example (mainnet RPC), .gitignore, README (quick-start), config.yaml (TokenMetadata program, CreateMetadataAccountV3/UpdateMetadataAccountV2 with discriminators), schema.graphql (TokenMetadataAccount, ProgramStats types), handlers/TokenMetadataHandlers.ts (extract accounts, upsert metadata, bump stats). Live scenario with config (pinned slots), E2E test querying HyperSync window and asserting metadata writes/stats consistency. Router and client unit tests exercise getSvmEventId fallback, discriminator byte-length ordering precomputation. CLI test config uses same program/instructions with deterministic block range.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Possibly related PRs

• enviodev/hyperindex#890: Updates SVM interactive init flow to route through template prompting, directly overlapping the CLI template selection refactor in this PR.
• enviodev/hyperindex#1212: Adds HyperSync N-API surface (set_log_level, HypersyncClient::new) in the same addon wrapper layer as this PR's trace support extension.
• enviodev/hyperindex#1071: Modifies codegen event plumbing in codegen_templates.rs, complementary to this PR's SVM instruction event code generation.

Suggested reviewers

• DZakh
• JonoPrest

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

[JasoonS]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 12

🧹 Nitpick comments (2)

scenarios/test_codegen/test/HyperSyncSolanaClient_test.res (1)

16-16: ⚡ Quick win

Replace deprecated Pervasives.max with Int.max.

The Pervasives module is deprecated in ReScript 12. Use Int.max instead.

♻️ Proposed fix

-      fromSlot: Pervasives.max(0, height - 10_000),
+      fromSlot: Int.max(0, height - 10_000),

As per coding guidelines: Always use ReScript 12 documentation. Never suggest ReasonML syntax

🤖 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 `@scenarios/test_codegen/test/HyperSyncSolanaClient_test.res` at line 16, The
code uses the deprecated Pervasives.max when computing fromSlot; replace
Pervasives.max with Int.max (i.e., change the call used in the expression that
sets fromSlot) so the expression becomes Int.max(0, height - 10_000), ensuring
you use ReScript 12 Int module functions rather than Pervasives.

packages/envio/src/sources/HyperSyncSolanaSource.res (1)

319-336: ⚡ Quick win

Precompute instruction selections once per source instance.

buildInstructionSelections(eventConfigs) is request-invariant, but it’s rebuilt on every fetch loop. Move it to make scope to reduce hot-path overhead.

♻️ Proposed refactor

 let make = ({chain, endpointUrl, apiToken, eventConfigs, clientMaxRetries, clientTimeoutMillis}: options): t => {
@@
   let schemaHandlesByProgram = buildSchemaHandles(eventConfigs)
 
   let needsTokenBalances = eventConfigs->Belt.Array.some(cfg => cfg.includeTokenBalances)
+  let instructionSelections = buildInstructionSelections(eventConfigs)
@@
   let getItemsOrThrow = async (
@@
-    let instructionSelections = buildInstructionSelections(eventConfigs)
     let fields = if needsTokenBalances {

🤖 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 `@packages/envio/src/sources/HyperSyncSolanaSource.res` around lines 319 - 336,
buildInstructionSelections(eventConfigs) is being recomputed on every fetch;
compute it once in the source's make scope and reuse it in the fetch loop to
avoid hot-path overhead. Move the call to
buildInstructionSelections(eventConfigs) into the make function (store result in
a field/property on the source instance, e.g., instructionSelectionsOnInit),
remove the per-fetch call that defines instructionSelections in the fetch loop,
and reference that stored instructionSelections when building the
HyperSyncSolanaClient.query (the query construction that uses instructions:
instructionSelections). Ensure the stored value is used wherever the current
per-request variable instructionSelections would be used.

🤖 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 `@packages/cli/src/cli_args/interactive_init/mod.rs`:
- Around line 162-164: The InitFlow SVM CLI path currently hardcodes
FeatureBlockHandler when InitFlow::Svm { init_flow: None } is used, bypassing
the interactive template selection; update the logic that constructs
InitFlow::Svm so that when init_flow is None it calls
svm_prompts::prompt_template_init_flow (the same function used in the
interactive branch) and uses its returned TemplateArgs to populate the SVM
init_flow instead of defaulting to FeatureBlockHandler, ensuring
MetaplexTokenMetadata becomes selectable; locate the code creating InitFlow::Svm
and replace the hardcoded TemplateArgs/FeatureBlockHandler fallback with a call
to svm_prompts::prompt_template_init_flow (or propagate the TemplateArgs there)
and handle errors similarly to the interactive branch.

In `@packages/cli/src/config_parsing/system_config.rs`:
- Around line 1101-1102: The Chain struct is being created with a hardcoded id =
0 which causes collisions for multiple SVM networks; change the creation of
Chain in the block that builds SVM networks to use a unique identifier (e.g.,
use the existing network.id or a composed unique key like (network.name,
network.id) or a generated UUID) instead of 0 and ensure the same identifier is
used as the key when inserting into the chains HashMap so each SVM chain
(mainnet, devnet, etc.) is indexed uniquely.

In `@packages/cli/src/hypersync_source_svm/config.rs`:
- Around line 28-32: The current conversion for max_num_retries uses a lossy
cast (.map(|v| v as u32)) which silently truncates values > u32::MAX; change the
mapping to perform a fallible conversion and only accept values that fit into
u32 (e.g., use u32::try_from or v.try_into() and .ok() to produce an
Option<u32>), keeping the existing filter(|v| *v >= 0) and falling back to
default.max_num_retries when the conversion fails; update the expression
referencing c.max_num_retries / max_num_retries to use this safe conversion.

In
`@packages/cli/templates/static/svm_metaplex_template/typescript/src/handlers/TokenMetadataHandlers.ts`:
- Line 48: The code in TokenMetadataHandlers.ts sets const mint = accounts[1] ??
"" which allows an empty string to be persisted; instead, guard on a missing
mint by checking accounts[1] (or the enclosing handler function that processes
accounts) and return/skip persisting or throw early if it's absent—do not
fallback to "". Locate the mint assignment and replace the unconditional
empty-string fallback with a presence check (e.g., if (!accounts[1]) { /*
skip/return */ }) so downstream code does not write placeholder identity data.

In `@packages/envio/index.d.ts`:
- Around line 1066-1069: The current constrained infer `accounts: infer Acc
extends Readonly<Record<string, string>>` rejects fixed-key account types (e.g.
`{ readonly authority: string }`) and can trigger the fallback to
`SvmDecodedInstruction`; to fix this, relax the constraint by inferring
`accounts: infer Acc` (remove `extends Readonly<Record<string, string>>`) and
then use a conditional check like `Acc extends Readonly<Record<keyof Acc,
string>>` (or `Acc extends Record<PropertyKey, string> ? ...`) in the
`SvmDecodedFromProgramTable` definition to preserve narrowing for fixed-key
objects and only fall back to `SvmDecodedInstruction` when the inferred `Acc`
truly does not have string-valued properties; update the branches that produce
`decoded.accounts`/`decoded.args` accordingly so they use the validated `Acc`
and avoid unintended fallback.

In `@packages/envio/src/Config.res`:
- Around line 197-219: svmEventDescriptorSchema currently parses accountFilters
as option(array(schema(...))) but downstream expects nested OR-of-AND groups
(array<array<...>>), and includeTokenBalances is not parsed here so should be
omitted; update the accountFilters matcher in svmEventDescriptorSchema to
S.option(S.array(S.array(S.schema(...)))) preserving the inner schema shape
(position:int, values:array(string)) and remove any parsing of
includeTokenBalances from this schema so the structure matches the downstream
SVM event contract used by the mapping logic elsewhere.

In `@packages/envio/svm.schema.json`:
- Around line 337-343: The "position" property in the schema (property name
"position" under account_filters) allows up to 255 but must be constrained to
the supported range 0..=5; update the JSON Schema for the "position" field by
changing its "maximum" from 255 to 5 (keep "minimum": 0 and "format": "uint8"
as-is) so invalid configs with positions >5 fail validation.

In `@scenarios/svm_metaplex_demo/src/handlers/TokenMetadataHandlers.ts`:
- Around line 89-99: The code in the pre-existing-metadata branch incorrectly
writes a synthetic createdAtSlot (using event.slot) even though the true
creation slot is unknown; update the TokenMetadataAccount.set call (the branch
handling "Metadata account existed before our `start_block`") to omit or set
createdAtSlot to null/undefined instead of assigning event.slot, and ensure you
do not overwrite any existing createdAtSlot on the record—only update fields you
actually know (id/ updateAuthority/ lastUpdatedSlot/ updateCount/
lastTxSignature) or explicitly preserve the existing createdAtSlot if one exists
in the DB schema for TokenMetadataAccount.

In `@scenarios/svm_metaplex_demo/src/indexer.test.ts`:
- Around line 14-18: The test sets process.env.ENVIO_CONFIG after a static
import of createTestIndexer, so envio may read the env var during its module
initialization; change indexer.test.ts to assign process.env.ENVIO_CONFIG =
"config.test.yaml" before importing envio by replacing the static import of
createTestIndexer with a dynamic import (e.g., set the env var at top-level,
then await import("envio") and extract createTestIndexer), ensuring
createTestIndexer is obtained after the env var is set so envio sees the
override.

In `@scenarios/test_codegen/test/HyperSyncSolanaClient_test.res`:
- Line 22: resp.data.instructions is accessed with Array.getUnsafe(0) (assigned
to first) before confirming the array is non-empty, which can panic; update the
code to check the length or use a safe getter first (e.g., verify
Array.length(resp.data.instructions) > 0 or use Array.get/Belt.Array.get to get
an option) and only assign to first after the presence check (or pattern-match
the option and assert), referencing resp.data.instructions, Array.getUnsafe, and
the first binding.

In `@scenarios/test_codegen/test/RpcSource_test.res`:
- Around line 42-55: Add an explanatory comment above the Async.it_skip test
(the one calling RpcSource.make and getHeightOrThrow) that documents why the
integration test is skipped: state whether it flakily depends on external RPC
availability, rate limits or test API token usage, mention any known
failures/PRs or environment requirements, and indicate what conditions would
allow re-enabling (e.g., stable mock RPC, recorded fixtures, or CI credentials).
Reference the test identifiers Async.it_skip, RpcSource.make, and
getHeightOrThrow so reviewers can find the test and follow the re-enable
instructions.
- Around line 140-142: Remove or resolve the temporary "DO NOT MERGE" skip
comments around the skipped integration tests: either re-enable the tests by
changing Async.it_skip("Queries transaction fields from raw JSON (with real
RPC)", ...) to Async.it(...) and remove the DO NOT MERGE note, or if they must
remain skipped, replace the comment with a clear TODO that includes a tracking
issue ID and an expected re-enable date; also apply the same fix for the other
skipped block referenced (around the getHeightOrThrow test and lines 648-650).
Ensure the updated comment or TODO references the test identifiers (e.g.,
Async.it_skip for the "Queries transaction fields..." test and the
getHeightOrThrow test) so reviewers can find and validate the change.

---

Nitpick comments:
In `@packages/envio/src/sources/HyperSyncSolanaSource.res`:
- Around line 319-336: buildInstructionSelections(eventConfigs) is being
recomputed on every fetch; compute it once in the source's make scope and reuse
it in the fetch loop to avoid hot-path overhead. Move the call to
buildInstructionSelections(eventConfigs) into the make function (store result in
a field/property on the source instance, e.g., instructionSelectionsOnInit),
remove the per-fetch call that defines instructionSelections in the fetch loop,
and reference that stored instructionSelections when building the
HyperSyncSolanaClient.query (the query construction that uses instructions:
instructionSelections). Ensure the stored value is used wherever the current
per-request variable instructionSelections would be used.

In `@scenarios/test_codegen/test/HyperSyncSolanaClient_test.res`:
- Line 16: The code uses the deprecated Pervasives.max when computing fromSlot;
replace Pervasives.max with Int.max (i.e., change the call used in the
expression that sets fromSlot) so the expression becomes Int.max(0, height -
10_000), ensuring you use ReScript 12 Int module functions rather than
Pervasives.

🪄 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: 1da67b49-1eb7-4b94-b171-b395458190ba

📥 Commits

Reviewing files that changed from the base of the PR and between 64805bc and 42c763b.

⛔ Files ignored due to path filters (4)

• Cargo.lock is excluded by !**/*.lock
• packages/cli/src/hbs_templating/snapshots/envio__hbs_templating__codegen_templates__test__indexer_code_generates_correct_types_and_values.snap is excluded by !**/*.snap
• packages/cli/src/hbs_templating/snapshots/envio__hbs_templating__codegen_templates__test__indexer_code_multiple_chains.snap is excluded by !**/*.snap
• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (64)

• STAGE_7B_DECISIONS.md
• packages/cli/Cargo.toml
• packages/cli/CommandLineHelp.md
• packages/cli/src/cli_args/init_config.rs
• packages/cli/src/cli_args/interactive_init/mod.rs
• packages/cli/src/config_parsing/human_config.rs
• packages/cli/src/config_parsing/public_config.rs
• packages/cli/src/config_parsing/system_config.rs
• packages/cli/src/config_parsing/validation.rs
• packages/cli/src/hbs_templating/codegen_templates.rs
• packages/cli/src/hbs_templating/contract_import_templates.rs
• packages/cli/src/hypersync_source/mod.rs
• packages/cli/src/hypersync_source/query.rs
• packages/cli/src/hypersync_source_svm/borsh_decoder.rs
• packages/cli/src/hypersync_source_svm/config.rs
• packages/cli/src/hypersync_source_svm/mod.rs
• packages/cli/src/hypersync_source_svm/query.rs
• packages/cli/src/hypersync_source_svm/types.rs
• packages/cli/src/lib.rs
• packages/cli/src/template_dirs.rs
• packages/cli/templates/dynamic/init_templates/shared/package.json.hbs
• packages/cli/templates/static/shared/pnpm-workspace.yaml
• packages/cli/templates/static/svm_metaplex_template/typescript/.env.example
• packages/cli/templates/static/svm_metaplex_template/typescript/.gitignore
• packages/cli/templates/static/svm_metaplex_template/typescript/README.md
• packages/cli/templates/static/svm_metaplex_template/typescript/config.yaml
• packages/cli/templates/static/svm_metaplex_template/typescript/schema.graphql
• packages/cli/templates/static/svm_metaplex_template/typescript/src/handlers/TokenMetadataHandlers.ts
• packages/cli/templates/static/svm_metaplex_template/typescript/tsconfig.json
• packages/cli/test/configs/svm-metaplex-config.yaml
• packages/envio/index.d.ts
• packages/envio/src/ChainFetcher.res
• packages/envio/src/Config.res
• packages/envio/src/Core.res
• packages/envio/src/Envio.res
• packages/envio/src/EventConfigBuilder.res
• packages/envio/src/HandlerLoader.res
• packages/envio/src/Hasura.res
• packages/envio/src/Internal.res
• packages/envio/src/Main.res
• packages/envio/src/SimulateItems.res
• packages/envio/src/SvmTypes.res
• packages/envio/src/sources/EventRouter.res
• packages/envio/src/sources/HyperSyncClient.res
• packages/envio/src/sources/HyperSyncSolanaClient.res
• packages/envio/src/sources/HyperSyncSolanaSource.res
• packages/envio/src/sources/Svm.res
• packages/envio/src/tui/Tui.res
• packages/envio/src/tui/components/TuiData.res
• packages/envio/svm.schema.json
• scenarios/svm_metaplex_demo/.envio/.gitignore
• scenarios/svm_metaplex_demo/README.md
• scenarios/svm_metaplex_demo/config.test.yaml
• scenarios/svm_metaplex_demo/config.yaml
• scenarios/svm_metaplex_demo/envio-env.d.ts
• scenarios/svm_metaplex_demo/package.json
• scenarios/svm_metaplex_demo/schema.graphql
• scenarios/svm_metaplex_demo/src/handlers/TokenMetadataHandlers.ts
• scenarios/svm_metaplex_demo/src/indexer.test.ts
• scenarios/svm_metaplex_demo/tsconfig.json
• scenarios/svm_metaplex_demo/vitest.config.ts
• scenarios/test_codegen/test/EventRouter_svm_test.res
• scenarios/test_codegen/test/HyperSyncSolanaClient_test.res
• scenarios/test_codegen/test/RpcSource_test.res

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

SVM template selection is still bypassed on envio init svm (no subcommand).

This interactive branch now prompts correctly, but the CLI path with InitFlow::Svm { init_flow: None } still hardcodes FeatureBlockHandler, so users can't pick MetaplexTokenMetadata there.

Proposed fix

 fn get_svm_ecosystem(init_flow: Option<clap_definitions::svm::InitFlow>) -> Result<Ecosystem> {
     Ok(match init_flow {
         Some(clap_definitions::svm::InitFlow::Template(args)) => Ecosystem::Svm {
             init_flow: svm_prompts::prompt_template_init_flow(args)?,
         },
         None => Ecosystem::Svm {
-            init_flow: crate::init_config::svm::InitFlow::Template(
-                crate::init_config::svm::Template::FeatureBlockHandler,
-            ),
+            init_flow: svm_prompts::prompt_template_init_flow(
+                clap_definitions::svm::TemplateArgs { template: None },
+            )?,
         },
     })
 }

🤖 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 `@packages/cli/src/cli_args/interactive_init/mod.rs` around lines 162 - 164,
The InitFlow SVM CLI path currently hardcodes FeatureBlockHandler when
InitFlow::Svm { init_flow: None } is used, bypassing the interactive template
selection; update the logic that constructs InitFlow::Svm so that when init_flow
is None it calls svm_prompts::prompt_template_init_flow (the same function used
in the interactive branch) and uses its returned TemplateArgs to populate the
SVM init_flow instead of defaulting to FeatureBlockHandler, ensuring
MetaplexTokenMetadata becomes selectable; locate the code creating InitFlow::Svm
and replace the hardcoded TemplateArgs/FeatureBlockHandler fallback with a call
to svm_prompts::prompt_template_init_flow (or propagate the TemplateArgs there)
and handle errors similarly to the interactive branch.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Chain ID is hardcoded to 0 for SVM networks.

The chain ID is hardcoded to 0 with a commented-out network.id. This prevents indexing multiple SVM chains (e.g., mainnet + devnet) simultaneously since they would collide in the chains HashMap. Consider using a unique identifier for each SVM chain.

🤖 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 `@packages/cli/src/config_parsing/system_config.rs` around lines 1101 - 1102,
The Chain struct is being created with a hardcoded id = 0 which causes
collisions for multiple SVM networks; change the creation of Chain in the block
that builds SVM networks to use a unique identifier (e.g., use the existing
network.id or a composed unique key like (network.name, network.id) or a
generated UUID) instead of 0 and ensure the same identifier is used as the key
when inserting into the chains HashMap so each SVM chain (mainnet, devnet, etc.)
is indexed uniquely.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Avoid lossy i64 -> u32 cast for max_num_retries.

Line 31 uses as u32, which silently truncates values above u32::MAX and can produce an unintended retry count.

Suggested fix

             max_num_retries: c
                 .max_num_retries
                 .filter(|v| *v >= 0)
-                .map(|v| v as u32)
+                .and_then(|v| u32::try_from(v).ok())
                 .unwrap_or(default.max_num_retries),

📝 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.

Suggested change

	max_num_retries: c
	.max_num_retries
	.filter(|v| *v >= 0)
	.map(|v| v as u32)
	.unwrap_or(default.max_num_retries),
	max_num_retries: c
	.max_num_retries
	.filter(|v| *v >= 0)
	.and_then(|v| u32::try_from(v).ok())
	.unwrap_or(default.max_num_retries),

🤖 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 `@packages/cli/src/hypersync_source_svm/config.rs` around lines 28 - 32, The
current conversion for max_num_retries uses a lossy cast (.map(|v| v as u32))
which silently truncates values > u32::MAX; change the mapping to perform a
fallible conversion and only accept values that fit into u32 (e.g., use
u32::try_from or v.try_into() and .ok() to produce an Option<u32>), keeping the
existing filter(|v| *v >= 0) and falling back to default.max_num_retries when
the conversion fails; update the expression referencing c.max_num_retries /
max_num_retries to use this safe conversion.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Avoid persisting blank mint values when account data is incomplete.

Line 48 falls back to "", which writes placeholder identity data. Guard on missing mint instead of storing an empty value.

💡 Proposed fix

-    const mint = accounts[1] ?? "";
+    const mint = accounts[1];
+    if (mint === undefined) return;

📝 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.

Suggested change

	const mint = accounts[1] ?? "";
	const mint = accounts[1];
	if (mint === undefined) return;

🤖 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
`@packages/cli/templates/static/svm_metaplex_template/typescript/src/handlers/TokenMetadataHandlers.ts`
at line 48, The code in TokenMetadataHandlers.ts sets const mint = accounts[1]
?? "" which allows an empty string to be persisted; instead, guard on a missing
mint by checking accounts[1] (or the enclosing handler function that processes
accounts) and return/skip persisting or throw early if it's absent—do not
fallback to "". Locate the mint assignment and replace the unconditional
empty-string fallback with a presence check (e.g., if (!accounts[1]) { /*
skip/return */ }) so downstream code does not write placeholder identity data.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

❓ Verification inconclusive

🌐 Web query:

In TypeScript, is a fixed-key object type like { readonly authority: string }assignable toReadonly<Record<string, string>>, or does that require an explicit string index signature?

💡 Result:

A fixed-key object type like { readonly authority: string } is generally NOT assignable to Readonly<Record<string, string>> in TypeScript, because Readonly<Record<string, string>> implies a string index signature (i.e., any string key is valid and has a string value), and a fixed-key object type lacks that index signature. This “index signature missing” incompatibility is explicitly seen when assigning an object type without an index signature to Record<string,...>. [1][2] You only avoid the need for an index signature when the target type does not require one (e.g., using a narrower Record key type like Record<'authority','string'>) or when you use an explicit assertion/cast. Regarding readonly: TypeScript’s readonly modifier does not materially change whether an index signature is considered missing; index-signature compatibility is the main issue here. [3][4] Example (what you likely want): - If you mean “object has an authority property, and it’s readonly”, use { readonly authority: string } (or Readonly<{ authority: string }>), not Record<string, string>. [5] - If you truly need “any string key maps to string”, then your type must include a string index signature, e.g. type T = Readonly<{ [k: string]: string }>. (Record<string,string> is defined as an object type with string keys and string values.) [5]

Citations:

• 1: string: value interface not assignable to Record<string,unknown> microsoft/TypeScript#50087
• 2: https://stackoverflow.com/questions/37006008/typescript-index-signature-is-missing-in-type
• 3: https://exploringjs.com/ts/book/ch_readonly.html
• 4: New --enforceReadonly compiler option to enforce read-only semantics in type relations microsoft/TypeScript#58296
• 5: https://www.typescriptlang.org/docs/handbook/utility-types.html

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail
# Print the relevant portion with a bit of context
sed -n '1045,1095p' packages/envio/index.d.ts | nl -ba | sed -n '1,120p'

Repository: enviodev/hyperindex

Length of output: 1960

---

Relax Record<string, string> constraint in SvmDecodedFromProgramTable to preserve decoded narrowing.

• accounts: infer Acc extends Readonly<Record<string, string>> can reject fixed-key account object types (no string index signature); e.g. { readonly authority: string } is not assignable to Readonly<Record<string, string>>, so the constrained infer can fail and typed decoded.accounts/decoded.args narrowing may be lost.
• Confirm whether this infer failure triggers the SvmDecodedInstruction fallback (and/or any other branch) in the full SvmDecodedFromProgramTable definition.

🤖 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 `@packages/envio/index.d.ts` around lines 1066 - 1069, The current constrained
infer `accounts: infer Acc extends Readonly<Record<string, string>>` rejects
fixed-key account types (e.g. `{ readonly authority: string }`) and can trigger
the fallback to `SvmDecodedInstruction`; to fix this, relax the constraint by
inferring `accounts: infer Acc` (remove `extends Readonly<Record<string,
string>>`) and then use a conditional check like `Acc extends
Readonly<Record<keyof Acc, string>>` (or `Acc extends Record<PropertyKey,
string> ? ...`) in the `SvmDecodedFromProgramTable` definition to preserve
narrowing for fixed-key objects and only fall back to `SvmDecodedInstruction`
when the inferred `Acc` truly does not have string-valued properties; update the
branches that produce `decoded.accounts`/`decoded.args` accordingly so they use
the validated `Acc` and avoid unintended fallback.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift

Avoid writing a synthetic createdAtSlot for pre-existing accounts.

This branch explicitly says the real creation slot is unknown, but still persists createdAtSlot: event.slot. That makes historical data incorrect for accounts created before the indexing window.

🤖 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 `@scenarios/svm_metaplex_demo/src/handlers/TokenMetadataHandlers.ts` around
lines 89 - 99, The code in the pre-existing-metadata branch incorrectly writes a
synthetic createdAtSlot (using event.slot) even though the true creation slot is
unknown; update the TokenMetadataAccount.set call (the branch handling "Metadata
account existed before our `start_block`") to omit or set createdAtSlot to
null/undefined instead of assigning event.slot, and ensure you do not overwrite
any existing createdAtSlot on the record—only update fields you actually know
(id/ updateAuthority/ lastUpdatedSlot/ updateCount/ lastTxSignature) or
explicitly preserve the existing createdAtSlot if one exists in the DB schema
for TokenMetadataAccount.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

❓ Verification inconclusive

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# 1) Locate ENVIO_CONFIG reads in envio runtime code.
rg -n -C3 'ENVIO_CONFIG' packages/envio

# 2) Locate createTestIndexer definition and nearby initialization behavior.
rg -n -C6 '\bcreateTestIndexer\b' packages/envio

# Expected confirmation:
# - If ENVIO_CONFIG is read at module top-level in the import path of createTestIndexer,
#   the current test ordering is incorrect.

Repository: enviodev/hyperindex

Length of output: 1979

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Show the relevant test file ordering
echo "=== scenarios/svm_metaplex_demo/src/indexer.test.ts (top) ==="
sed -n '1,120p' scenarios/svm_metaplex_demo/src/indexer.test.ts

# Find where ENVIO_CONFIG is consumed in the repo (focus on packages/envio and envio-related code)
echo "=== Searching for ENVIO_CONFIG usage ==="
rg -n -S "ENVIO_CONFIG" packages scenarios/svm_metaplex_demo || true

# Find createTestIndexer implementation and its import-time behavior
echo "=== Searching for createTestIndexer implementation ==="
rg -n -S "createTestIndexer" packages || true

# If createTestIndexer is in a TypeScript file under packages/envio, print those files' top-level sections
echo "=== Files mentioning createTestIndexer ==="
files=$(rg -l -S "createTestIndexer" packages || true)
echo "$files" | head -n 50

# For each matched file, show a small window around any ENVIO_CONFIG usage (if any) and near module-level initialization
# (Limit to first 20 files to keep output bounded)
i=0
while read -r f; do
  [ -z "$f" ] && continue
  i=$((i+1))
  if [ "$i" -gt 20 ]; then break; fi
  echo "--- $f (ENVIO_CONFIG context) ---"
  rg -n -C3 "ENVIO_CONFIG|process\\.env" "$f" || true
done < <(echo "$files" | head -n 20)

Repository: enviodev/hyperindex

Length of output: 1960

---

ENVIO_CONFIG may be read before the assignment due to ESM static imports

In scenarios/svm_metaplex_demo/src/indexer.test.ts (around lines 14-18), process.env.ENVIO_CONFIG = "config.test.yaml"; runs before static imports of createTestIndexer from envio. If envio reads process.env.ENVIO_CONFIG during module initialization, this override won’t take effect reliably (ESM static import evaluation happens before the importing module’s top-level code).

💡 Safer pattern

-process.env.ENVIO_CONFIG = "config.test.yaml";
 import { describe, it, expect } from "vitest";
-import { createTestIndexer } from "envio";
 
 ...
     async () => {
+      process.env.ENVIO_CONFIG = "config.test.yaml";
+      const { createTestIndexer } = await import("envio");
       const indexer = createTestIndexer();
       const result = await indexer.process({ chains: { 0: {} } });

🤖 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 `@scenarios/svm_metaplex_demo/src/indexer.test.ts` around lines 14 - 18, The
test sets process.env.ENVIO_CONFIG after a static import of createTestIndexer,
so envio may read the env var during its module initialization; change
indexer.test.ts to assign process.env.ENVIO_CONFIG = "config.test.yaml" before
importing envio by replacing the static import of createTestIndexer with a
dynamic import (e.g., set the env var at top-level, then await import("envio")
and extract createTestIndexer), ensuring createTestIndexer is obtained after the
env var is set so envio sees the override.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Check array length before unsafe access.

Array.getUnsafe(0) on line 22 will panic if resp.data.instructions is empty, before the assertion on line 26 can verify the array is non-empty. This produces a less helpful error message.

🛡️ Proposed fix to check length first

     let resp = await client.get(~query)
+    t.expect(resp.data.instructions->Array.length > 0).toBe(true)
     let first = resp.data.instructions->Array.getUnsafe(0)
 
     let summary = {
       "heightLooksRecent": height > 300_000_000,
-      "hasInstructions": resp.data.instructions->Array.length > 0,
       "firstProgramId": first.programId,
       "firstDataIsHex": first.data->String.startsWith("0x"),
     }
     t.expect(summary).toEqual({
       "heightLooksRecent": true,
-      "hasInstructions": true,
       "firstProgramId": tokenMetadataProgram,
       "firstDataIsHex": true,
     })

🤖 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 `@scenarios/test_codegen/test/HyperSyncSolanaClient_test.res` at line 22,
resp.data.instructions is accessed with Array.getUnsafe(0) (assigned to first)
before confirming the array is non-empty, which can panic; update the code to
check the length or use a safe getter first (e.g., verify
Array.length(resp.data.instructions) > 0 or use Array.get/Belt.Array.get to get
an option) and only assign to first after the presence check (or pattern-match
the option and assert), referencing resp.data.instructions, Array.getUnsafe, and
the first binding.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Document why getHeightOrThrow test is skipped.

Lines 141 and 649 reference "see comment on getHeightOrThrow test above" as the reason for skipping other tests, but there's no explanatory comment on this test explaining the skip rationale.

Add a comment documenting why this integration test is skipped and whether it should be re-enabled.

🤖 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 `@scenarios/test_codegen/test/RpcSource_test.res` around lines 42 - 55, Add an
explanatory comment above the Async.it_skip test (the one calling RpcSource.make
and getHeightOrThrow) that documents why the integration test is skipped: state
whether it flakily depends on external RPC availability, rate limits or test API
token usage, mention any known failures/PRs or environment requirements, and
indicate what conditions would allow re-enabling (e.g., stable mock RPC,
recorded fixtures, or CI credentials). Reference the test identifiers
Async.it_skip, RpcSource.make, and getHeightOrThrow so reviewers can find the
test and follow the re-enable instructions.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical | 🏗️ Heavy lift

Remove or address "DO NOT MERGE" comments before merging.

The explicit "DO NOT MERGE WITH THESE TESTS SKIPPED" comments on lines 140 and 648 indicate these test skips are temporary. Skipping integration tests reduces coverage for critical RPC functionality.

Either re-enable these tests or provide a tracking issue and timeline for re-enabling them.

Also applies to: 648-650

🤖 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 `@scenarios/test_codegen/test/RpcSource_test.res` around lines 140 - 142,
Remove or resolve the temporary "DO NOT MERGE" skip comments around the skipped
integration tests: either re-enable the tests by changing Async.it_skip("Queries
transaction fields from raw JSON (with real RPC)", ...) to Async.it(...) and
remove the DO NOT MERGE note, or if they must remain skipped, replace the
comment with a clear TODO that includes a tracking issue ID and an expected
re-enable date; also apply the same fix for the other skipped block referenced
(around the getHeightOrThrow test and lines 648-650). Ensure the updated comment
or TODO references the test identifiers (e.g., Async.it_skip for the "Queries
transaction fields..." test and the getHeightOrThrow test) so reviewers can find
and validate the change.

[JasoonS]

Doing this includes all of the transaction fields. In the future if you put an array, you can select specific transaction fields (but this isn't implemented yet - it is all or nothing).