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.

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.

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.

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.

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.

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 to adapt it safely.
• Move to Validation and roundtrip testing before you deploy anything.