---
title: Examples
description: Use real ABI excerpts for core primitives, token instructions,
  flattened program ABIs, and advanced proof structures.
source_url:
  html: https://thru.org/docs/abi/examples/
  md: https://thru.org/docs/abi/examples.md
---

# Examples

Use this page when you want real ABI shapes to copy from instead of inventing a schema from scratch.

> **Tip:**
>
> These are verbatim excerpts from public ABI examples shipped with Thru. Start here, then trim or adapt them for your own package.

## Core Primitives

Use this pattern for fixed-size binary primitives and a simple variable-size payload wrapper.

```yaml
abi:
  package: "thru.common.primitives"
  abi-version: 1
  package-version: "1.0.0"
  description: "Basic primitive types for Thru blockchain (signatures, hashes, pubkeys)"
  imports: []

types:
  - name: "Hash"
    kind:
      struct:
        packed: true
        fields:
          - name: "bytes"
            field-type:
              array:
                size:
                  literal:
                    u64: 32
                element-type:
                  primitive: u8

  - name: "Pubkey"
    kind:
      struct:
        packed: true
        fields:
          - name: "bytes"
            field-type:
              array:
                size:
                  literal:
                    u64: 32
                element-type:
                  primitive: u8

  - name: "InstructionData"
    kind:
      struct:
        packed: true
        fields:
          - name: "program_idx"
            field-type:
              primitive: u16
          - name: "data_size"
            field-type:
              primitive: u64
          - name: "data"
            field-type:
              array:
                size:
                  field-ref:
                    path: ["data_size"]
                element-type:
                  primitive: u8
```

## Token Program Pattern

Use this pattern when you need program metadata, shared imports, and a tagged instruction root.

```yaml
abi:
  package: thru.program.token
  name: "Token Program"
  abi-version: 1
  package-version: 0.1.0
  description: Ideal ABI for the Thru token program instruction envelopes and account
    state
  imports:
    - type: onchain
      address: ta1blxgaYR0dei5aldWJe1vbUtt-LkVEBOzNJtSRhHQcTG
      target: abi
      network: mainnet
      revision: latest
    - type: onchain
      address: ta1l4yBjT6a7PQ4Wu_sJPQwb8jJiJ8Ei71gOuE5Dnotfrl
      target: abi
      network: mainnet
      revision: latest
  options:
    program-metadata:
      root-types:
        instruction-root: "TokenInstruction"
        account-root: "TokenProgramAccount"
        errors: "TokenError"
        events: "TokenEvent"
types:
- name: TransferInstruction
  kind:
    struct:
      packed: true
      fields:
      - name: source_account_index
        field-type:
          primitive: u16
      - name: dest_account_index
        field-type:
          primitive: u16
      - name: amount
        field-type:
          primitive: u64
- name: TokenInstruction
  kind:
    struct:
      packed: true
      fields:
      - name: tag
        field-type:
          primitive: u8
      - name: payload
        field-type:
          enum:
            packed: true
```

## Explorer-Compatible Publishing Pattern

Use this pattern when the ABI must decode correctly in explorer after publication, not just during local analyze or codegen.

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

This is the smallest useful shape for explorer reflection:

- a configured `instruction-root`
- a configured `account-root`
- a configured `events` type
- one discriminated instruction envelope instead of only separate instruction structs

## Flattened Program ABI Pattern

Use a flattened style like this when you want a publish-ready artifact with no external imports left to resolve.

```yaml
abi:
  package: thru.program.nft_token
  name: "NFT Token Program"
  abi-version: 1
  package-version: '1.0.0'
  description: NFT token program for minting, transferring, and managing NFTs on Thru blockchain
  imports: []
  options:
    program-metadata:
      root-types:
        instruction-root: NftInstruction
        account-root: NftProgramAccount
        errors: null
        events: null
types:
- name: Hash
  kind:
    struct:
      packed: true
      aligned: 0
      comment: null
      fields:
      - name: bytes
        field-type:
          array:
            packed: false
            aligned: 0
            comment: null
            size:
              literal:
                u64: 32
            element-type:
              primitive: u8
            jagged: false
```

## Advanced Dynamic Proof Pattern

Use this pattern when the ABI needs nested field references, expressions, and variable-size proof bodies.

```yaml
abi:
  package: "thru.blockchain.state_proof"
  abi-version: 1
  package-version: "1.0.0"
  description: "State proof structures for Merkle tree verification"
  imports:
    - type: onchain
      address: ta1blxgaYR0dei5aldWJe1vbUtt-LkVEBOzNJtSRhHQcTG
      target: abi
      network: mainnet
      revision: latest

types:
  - name: "StateProofHeader"
    kind:
      struct:
        packed: true
        fields:
          - name: "type_slot"
            field-type:
              primitive: u64
          - name: "path_bitset"
            field-type:
              type-ref:
                name: "Hash"
                package: "thru.common.primitives"
  - name: "StateProof"
    kind:
      struct:
        packed: true
        fields:
          - name: "hdr"
            field-type:
              type-ref:
                name: "StateProofHeader"
          - name: "proof_body"
            field-type:
              enum:
                packed: true
                tag-ref:
                  bit-and:
                    left:
                      right-shift:
                        left:
                          field-ref:
                            path: ["hdr", "type_slot"]
                        right:
                          literal:
                            u8: 62
                    right:
                      literal:
                        u8: 3
```

## How To Use These Examples

- Start from the smallest example that matches your need.
- Move to [ABI Authoring Guide](https://thru.org/docs/abi/authoring-guide.md) to adapt it safely.
- Move to [Validation and roundtrip testing](https://thru.org/docs/abi/validation-and-roundtrip-testing.md) before you deploy anything.