Tools & Reference

Ingot Indexer

The Ingot Indexer is an open-source component that processes Pay2Ingot outputs and maintains artifact state off-chain.

Core Functionality

The indexer performs the following tasks:

• Transaction Processing: Extracts Pay2Ingot outputs from confirmed transactions
• Payload Parsing: Parses and validates payload data (DAG-CBOR/TLV format)
• Schema Routing: Routes to appropriate schema handlers based on Schema ID
• State Machine Execution: Executes state machines for known schemas
• oUTXO Rules Enforcement: Enforces unique active tip, spend-old-create-new, and conflict resolution
• API Services: Provides REST APIs for querying artifact state

Indexer Architecture

┌─────────────────┐
│  Tondi Chain    │
│  (L1 Blocks)   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Block Parser    │
│  (Extract P2I)   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Payload Parser │
│  (DAG-CBOR/TLV) │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Schema Router  │
│  (By Schema ID) │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  State Machine  │
│  (FSM Execution) │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  oUTXO Rules    │
│  (Tip Management)│
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  State Database │
│  (Artifact State)│
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  API Server     │
│  (REST Endpoints)│
└─────────────────┘

oUTXO Rules Enforcement

The indexer enforces three core oUTXO disciplines:

1. Unique Active Tip: Each artifact_id has at most one active tip
2. Spend Old, Create New: New tip must spend old active tip (except Mint)
3. Conflict Resolution: Concurrent conflicts resolved by (blue_score, block_id, wtxid) lexicographic ordering

Raw Data Mode

For unknown schemas:

• Indexer marks as raw_data
• Does not execute state machine
• Still participates in oUTXO arbitration
• Can be upgraded to executable state through Registry test vectors

Registry Compliance

Indexers must pass Registry test vectors to claim "executable" status:

• Test Suites: S1-S6 covering serialization, MAST, concurrency, signatures, etc.
• 100% Pass Rate: Required for executable state
• Runtime Self-Check: Must print registry version and commit hash at startup

Ingot CLI

The tondi-cli command-line interface provides a unified way to interact with Ingot.

Installation

# Install tondi-cli
cargo install tondi-cli

# Or build from source
git clone https://github.com/tondi-foundation/tondi-cli
cd tondi-cli
cargo build --release

Core Commands

Create Asset

Create a new Ingot asset using a schema template:

# Create token using BRC-20 compatible template
tondi-cli ingot create \
  --schema-template token/brc20_compatible.json \
  --params name="MyToken" ticker="MTK" supply=21000000

# Create NFT using ERC-721 compatible template
tondi-cli ingot create \
  --schema-template nft/erc721_compatible.json \
  --params name="CryptoArt #1" description="My first NFT"

# Create text inscription
tondi-cli ingot create \
  --schema-template inscription/text.json \
  --params content="Hello, Tondi!"

Transfer Asset

Transfer ownership of an Ingot asset:

tondi-cli ingot transfer \
  --instance-id <instance_id> \
  --recipient <recipient_address> \
  --fee-rate 1.0

Query Asset

Query asset state and information:

# Get artifact information
tondi-cli ingot query artifact <artifact_id>

# Get instance information
tondi-cli ingot query instance <instance_id>

# List assets by schema
tondi-cli ingot query list --schema-id <schema_id>

Build Transaction

Build a custom Ingot transaction:

tondi-cli ingot build \
  --inputs <input_utxos> \
  --outputs <output_addresses> \
  --payload <payload_file> \
  --lock <lock_type>

Schema Templates

Standard schema templates are available in the ingot_schemata/ directory:

Category	Templates	Purpose
Token	2	BRC-20 compatible tokens, TRC-721 advanced tokens
Inscription	2	Text inscriptions, image inscriptions
NFT	2	ERC-721 compatible NFTs, music NFTs
DAO	2	DAO proposals, DAO voting
Application	2	Social media posts, decentralized identity (DID)

Ingot Indexer API

The Ingot Indexer provides REST APIs for querying artifact state and interacting with the protocol.

Base URL

https://indexer.tondi.org/api/v1

Endpoints

Get Artifact

Get artifact information by artifact_id:

GET /artifact/{artifact_id}

Response:

{
  "artifact_id": "0x...",
  "schema_id": "0x...",
  "tip_instance_id": "0x...",
  "state": {
    "balance": {...},
    "ownership": {...}
  },
  "has_unrevealed": false
}

Get Instance

Get instance information by instance_id:

GET /instance/{instance_id}

Response:

{
  "instance_id": "0x...",
  "artifact_id": "0x...",
  "outpoint": {
    "txid": "0x...",
    "vout": 0
  },
  "tip_flag": true,
  "payload": {...},
  "lock": {...}
}

List Assets

List assets with pagination:

GET /assets?schema_id={schema_id}&page={page}&limit={limit}

Query Parameters:

• schema_id (optional): Filter by schema ID
• page (optional): Page number (default: 1)
• limit (optional): Items per page (default: 20)

Response:

{
  "items": [...],
  "total": 100,
  "page": 1,
  "limit": 20
}

Get Artifact Events

Get event history for an artifact:

GET /artifact/{artifact_id}/events?from_height={height}

Query Parameters:

• from_height (optional): Start from block height

Response:

{
  "events": [
    {
      "type": "Mint",
      "height": 12345,
      "txid": "0x...",
      "data": {...}
    },
    ...
  ]
}

Verify Asset Proof

Verify a Merkle proof for an asset:

POST /verify-asset-proof

Request Body:

{
  "leaf_bytes": "...",
  "merkle_path": [...],
  "root": "0x..."
}

Response:

{
  "valid": true,
  "verified_asset": {...}
}

Error Responses

All endpoints return standard error responses:

{
  "error": {
    "code": "INDEXER_UNKNOWN_SCHEMA",
    "message": "Schema not recognized",
    "details": {...}
  }
}

Rate Limiting

API requests are rate-limited:

• Default: 100 requests per minute per IP
• Authenticated: 1000 requests per minute per API key

Roadmap

Q4 2025 (Current)

• ✅ v1.0 launch with full features
• ✅ Standard schema templates and CLI tools
• ✅ Initial testing on Tondi devnet and testnet
• ✅ Registry test vectors published
• ✅ Genesis inscription and first token deployment

Q1 2026

• 🔄 Community integrations (wallets, explorers, dApps)
• 🔄 WASM VM support via ScriptHash
• 🔄 Light client SDKs
• 🔄 Cross-chain bridge prototypes
• 🔄 Expanded documentation and tutorials

Q2 2026

• 📅 Governance upgrades via hard forks (if needed)
• 📅 Expanded templates for new use cases
• 📅 EVM compatibility layer
• 📅 Storage rent mechanism evaluation and optional implementation
• 📅 Advanced privacy features (partial reveals, zk-proofs)

Q3 2026

• 📅 Enterprise-grade tooling and APIs
• 📅 Multi-VM runtime optimization
• 📅 Production-ready cross-chain bridges
• 📅 Expanded schema library (gaming, DeFi, enterprise)
• 📅 Performance optimizations based on real-world usage

Ongoing

• 🔄 Security audits
• 🔄 Partnerships
• 🔄 User feedback to refine the protocol
• 🔄 Community-driven template submissions
• 🔄 Performance optimizations

Future Enhancements (Post-v1.0)

• Zero-Knowledge Proofs: Optional zk-proofs for enhanced privacy in DAO voting and confidential asset transfers
• Layer 2 Scaling: Integration with Tondi Layer 2 solutions for ultra-low-cost, high-throughput asset operations
• Advanced Oracles: Native oracle integration for price feeds, random numbers, and external data validation
• Composability: Templates for complex DeFi protocols (lending, derivatives, AMMs) built on Ingot's asset model
• Formal Verification: Tools for verifying ScriptHash script correctness and asset conservation properties
• Universal Blockchain Interconnection: Full support for multiple VMs (WASM, EVM, Move, Solana VM, etc.) enabling true cross-chain interoperability

---

Previous: Locking Mechanisms | Next: Technical Specifications