---
title: Explorer Compatibility
description: Publish ABIs with the root types explorer reflection expects so
  instruction, account, and event decoding works on-chain.
source_url:
  html: https://thru.org/docs/abi/explorer-compatibility/
  md: https://thru.org/docs/abi/explorer-compatibility.md
---

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

```yaml
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

```yaml
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](https://thru.org/docs/abi/validation-and-roundtrip-testing.md)
4. publish the ABI with [Publishing and Iteration](https://thru.org/docs/abi/deployment-and-program-testing.md)
5. inspect the published artifact with [Explorer MCP](https://thru.org/docs/api-ref/explorer-mcp/overview.md) if explorer reflection still looks wrong

## Open Next

- [Examples](https://thru.org/docs/abi/examples.md) for the same pattern alongside other public ABI excerpts
- [Publishing and Iteration](https://thru.org/docs/abi/deployment-and-program-testing.md) for the publish flow
- [ABI Account](https://thru.org/docs/cli-reference/abi-account.md) for the exact CLI syntax