Explorer Compatibility

Use this page when an ABI works locally for analyze or codegen, but explorer reflection still fails or returns incomplete results.

Why Explorer Compatibility Matters

Explorer-side reflection uses the published ABI plus the configured root types to decide how to decode instruction, account, and event bytes.

The reflector APIs used by explorer tooling expect:

• instruction-root for instruction payloads
• account-root for account data
• events for emitted event payloads

If those root types are missing, local authoring may still feel fine while explorer decoding fails later.

Required Metadata

Set abi.options.program-metadata.root-types on the published ABI.

options:
  program-metadata:
    root-types:
      instruction-root: "CounterInstruction"
      account-root: "CounterAccount"
      errors: "CounterError"
      events: "CounterEvent"

What Each Root Type Does

Root type	What explorer uses it for	What happens if it is missing
instruction-root	Decode transaction instruction bytes	Instruction reflection fails
account-root	Decode account data views	Account reflection fails
events	Decode emitted events	Event reflection fails

Prefer A Single Discriminated Instruction Root

Explorer instruction reflection works best when the ABI exposes one discriminated instruction envelope such as CounterInstruction, instead of only a set of unrelated per-instruction structs.

That root type should:

• include a tag or discriminator field
• point the payload enum at the correct tag field
• contain every published instruction variant

Minimal Canonical Example

abi:
  package: thru.example.counter
  name: "Counter Program"
  abi-version: 1
  package-version: 1.0.0
  description: Minimal explorer-compatible counter ABI
  imports: []
  options:
    program-metadata:
      root-types:
        instruction-root: "CounterInstruction"
        account-root: "CounterAccount"
        errors: "CounterError"
        events: "CounterEvent"

types:
  - name: InitializeArgs
    kind:
      struct:
        packed: true
        fields:
          - name: seed
            field-type:
              primitive: u64

  - name: IncrementArgs
    kind:
      struct:
        packed: true
        fields:
          - name: amount
            field-type:
              primitive: u64

  - name: CounterInstruction
    kind:
      struct:
        packed: true
        fields:
          - name: tag
            field-type:
              primitive: u8
          - name: payload
            field-type:
              enum:
                packed: true
                tag-ref:
                  field-ref:
                    path:
                      - tag
                variants:
                  - name: initialize
                    tag-value: 0
                    variant-type:
                      type-ref:
                        name: InitializeArgs
                  - name: increment
                    tag-value: 1
                    variant-type:
                      type-ref:
                        name: IncrementArgs

  - name: CounterAccount
    kind:
      struct:
        packed: true
        fields:
          - name: value
            field-type:
              primitive: u64

  - name: CounterEvent
    kind:
      struct:
        packed: true
        fields:
          - name: value
            field-type:
              primitive: u64

  - name: CounterError
    kind:
      enum:
        packed: true
        variants:
          - name: overflow
            tag-value: 0

Publishing Checklist

1. add program-metadata.root-types
2. make the instruction root a single discriminated envelope
3. validate locally with Validation and roundtrip testing
4. publish the ABI with Publishing and Iteration
5. inspect the published artifact with Explorer MCP if explorer reflection still looks wrong

Open Next

• Examples for the same pattern alongside other public ABI excerpts
• Publishing and Iteration for the publish flow
• ABI Account for the exact CLI syntax