🪙 Chapter 4: Phase 1 Data Format - Transaction Schema & UTXO Model

Phase 1 of WIA-FIN-003 defines the fundamental data structures that form the bedrock of cryptocurrency interoperability. In this chapter, we dive deep into the technical specifications for transaction schemas, the UTXO (Unspent Transaction Output) model, address formats, and validation rules.

Understanding these data formats is crucial because they enable different blockchain systems to represent information in a unified way, making cross-chain analytics, wallets, and applications possible without requiring separate implementations for each blockchain.

4.1 Universal Transaction Schema

The WIA transaction schema is designed to represent any cryptocurrency transaction—whether from Bitcoin, Ethereum, Solana, or future blockchains—in a consistent JSON format. This blockchain-agnostic approach enables developers to build tools that work across the entire cryptocurrency ecosystem.

Core Transaction Fields

Complete Transaction Example: Ethereum Transfer

{
  // WIA Standard version
  "wia_version": "1.0",

  // Transaction identification
  "transaction_id": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef1234567890abcdef1234567890",
  "blockchain": "ethereum",
  "network": "mainnet",
  "type": "transfer",

  // Timing and confirmation
  "timestamp": "2025-12-25T10:30:00.000Z",
  "block_number": 18500000,
  "block_hash": "0xabcdef...",
  "confirmations": 12,
  "status": "confirmed",

  // Sender (from)
  "from": {
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "balance_before": "10.500000000000000000",
    "balance_after": "9.498000000000000000"
  },

  // Recipient (to)
  "to": {
    "address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
    "balance_before": "5.000000000000000000",
    "balance_after": "6.000000000000000000"
  },

  // Transfer amount
  "amount": {
    "value": "1.000000000000000000",
    "currency": "ETH",
    "decimals": 18,
    "usd_value": "3500.00",
    "usd_timestamp": "2025-12-25T10:30:00Z"
  },

  // Transaction fee
  "fee": {
    "value": "0.002000000000000000",
    "currency": "ETH",
    "decimals": 18,
    "usd_value": "7.00",
    "gas_used": "21000",
    "gas_price": "100000000000"
  },

  // Ethereum-specific metadata
  "metadata": {
    "nonce": 42,
    "gas_limit": "21000",
    "chain_id": 1,
    "v": "0x1b",
    "r": "0x...",
    "s": "0x...",
    "input": "0x"
  }
}

4.2 Bitcoin Transaction Example (UTXO Model)

Bitcoin uses a fundamentally different transaction model called UTXO (Unspent Transaction Outputs). Unlike Ethereum's account-based model, Bitcoin transactions consume previous outputs and create new ones. WIA-FIN-003 represents this elegantly while maintaining format consistency.

{
  "wia_version": "1.0",

  "transaction_id": "d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5",
  "blockchain": "bitcoin",
  "network": "mainnet",
  "type": "transfer",

  "timestamp": "2025-12-25T10:30:00Z",
  "block_number": 820000,
  "block_hash": "00000000000000000001a2b3c4d5e6f7...",
  "confirmations": 6,
  "status": "confirmed",

  // Bitcoin uses inputs (spending UTXOs) instead of single "from"
  "inputs": [
    {
      "previous_output": {
        "txid": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
        "vout": 0
      },
      "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
      "amount": {
        "value": "1.50000000",
        "currency": "BTC",
        "decimals": 8,
        "usd_value": "67500.00"
      },
      "script_sig": "483045022100...",
      "sequence": 4294967295
    }
  ],

  // Bitcoin creates multiple outputs
  "outputs": [
    {
      "address": "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2",
      "amount": {
        "value": "1.00000000",
        "currency": "BTC",
        "decimals": 8,
        "usd_value": "45000.00"
      },
      "script_pubkey": "76a914...",
      "vout": 0
    },
    {
      // Change output back to sender
      "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
      "amount": {
        "value": "0.49950000",
        "currency": "BTC",
        "decimals": 8,
        "usd_value": "22477.50"
      },
      "script_pubkey": "76a914...",
      "vout": 1
    }
  ],

  "fee": {
    "value": "0.00050000",
    "currency": "BTC",
    "decimals": 8,
    "usd_value": "22.50"
  },

  "metadata": {
    "version": 2,
    "locktime": 0,
    "size": 226,
    "vsize": 226,
    "weight": 904,
    "witness": []
  }
}

4.3 UTXO Model Deep Dive

Understanding the UTXO model is crucial for working with Bitcoin and similar blockchains. In this model, a "coin" is not tracked by account balance but rather by unspent outputs from previous transactions.

UTXO Transaction Flow:

Transaction 1 (Previous):
┌──────────────────────────────────────┐
│ Outputs:                             │
│ [0] Alice → 1.5 BTC ✓ (Unspent)     │
│ [1] Bob   → 0.3 BTC   (Already spent)│
└──────────────────────────────────────┘

                ▼ (Alice spends UTXO)

Transaction 2 (Current):
┌──────────────────────────────────────┐
│ Inputs:                              │
│ • Tx1[0]: 1.5 BTC (from Alice)       │
├──────────────────────────────────────┤
│ Outputs:                             │
│ [0] Carol → 1.0 BTC ✓ (New UTXO)    │
│ [1] Alice → 0.4995 BTC ✓ (Change)   │
│                                      │
│ Fee: 0.0005 BTC (1.5 - 1.0 - 0.4995)│
└──────────────────────────────────────┘

Key UTXO Concepts

• Inputs Reference Previous Outputs: Each input points to a specific output from a previous transaction using (txid, vout) pair.
• Outputs Must Be Fully Spent: You cannot partially spend a UTXO. If you have 1.5 BTC and want to send 1.0 BTC, you must spend the entire 1.5 BTC output and create a "change" output back to yourself.
• Implicit Fees: Transaction fee is the difference between input sum and output sum. It's not explicitly stated but implied.
• Script Locking: Each output is "locked" with a script (scriptPubKey) that defines spending conditions. Input provides a script (scriptSig) to "unlock" it.

UTXO Set

The UTXO set is the collection of all unspent transaction outputs in the blockchain. This set represents the current state of who owns what in Bitcoin. Full nodes maintain this set in memory for fast transaction validation.

4.4 Address Normalization

Different blockchains use different address formats. WIA-FIN-003 normalizes these into a consistent structure while preserving blockchain-specific information.

Universal Address Format

{
  "wia_version": "1.0",
  "address": {
    "raw": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "blockchain": "ethereum",
    "network": "mainnet",
    "type": "eoa",  // Externally Owned Account (vs. contract)
    "checksummed": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "validation": {
      "is_valid": true,
      "checksum_valid": true
    }
  }
}

Address Types Across Blockchains

Bitcoin Address Types Explained

4.5 Token Metadata Schema

Beyond native blockchain currencies (BTC, ETH), most blockchains support custom tokens. WIA-FIN-003 provides a standard format for describing these tokens.

{
  "wia_version": "1.0",
  "token": {
    "contract_address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
    "blockchain": "ethereum",
    "network": "mainnet",
    "standard": "ERC-20",

    "details": {
      "name": "Tether USD",
      "symbol": "USDT",
      "decimals": 6,
      "total_supply": "95000000000.000000",
      "logo_uri": "https://assets.example.com/usdt.png"
    },

    "market_data": {
      "price_usd": "1.00",
      "market_cap_usd": "95000000000",
      "volume_24h_usd": "50000000000",
      "circulating_supply": "95000000000.000000",
      "timestamp": "2025-12-25T10:30:00Z"
    },

    "metadata": {
      "verified": true,
      "issuer": "Tether Limited",
      "website": "https://tether.to",
      "whitepaper": "https://tether.to/wp-content/uploads/2016/06/TetherWhitePaper.pdf"
    }
  }
}

Token Standards Across Blockchains

4.6 Block Structure

WIA-FIN-003 also standardizes how blocks themselves are represented, enabling blockchain explorers and analytics tools to work across different blockchains.

{
  "wia_version": "1.0",
  "block": {
    "blockchain": "ethereum",
    "network": "mainnet",
    "number": 18500000,
    "hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "parent_hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "timestamp": "2025-12-25T10:30:00Z",

    "miner": {
      "address": "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed",
      "reward": {
        "value": "2.5",
        "currency": "ETH",
        "usd_value": "8750.00"
      }
    },

    "transactions": {
      "count": 150,
      "transaction_ids": [
        "0x1a2b3c4d...",
        "0x5e6f7g8h...",
        // ... (truncated for brevity)
      ]
    },

    "statistics": {
      "size_bytes": 125000,
      "gas_used": "15000000",
      "gas_limit": "30000000",
      "difficulty": "58750000000000000",
      "total_difficulty": "58750000000000000000000"
    },

    "metadata": {
      "extra_data": "0x...",
      "nonce": "0x1234567890abcdef",
      "mix_hash": "0x..."
    }
  }
}

4.7 Validation Rules

All WIA-FIN-003 data must pass rigorous validation. The standard provides JSON Schema definitions for automated validation.

Transaction Validation Checklist

Example Validation Code (TypeScript)

import Ajv from 'ajv';
import { wiaTransactionSchema } from '@wia/schemas';

const ajv = new Ajv();
const validate = ajv.compile(wiaTransactionSchema);

function validateWIATransaction(data: any): boolean {
  const valid = validate(data);

  if (!valid) {
    console.error('Validation errors:', validate.errors);
    return false;
  }

  // Additional business logic validation
  if (data.blockchain === 'bitcoin') {
    return validateBitcoinUTXO(data);
  } else if (data.blockchain === 'ethereum') {
    return validateEthereumAddress(data);
  }

  return true;
}

4.8 Implementation Examples

Converting blockchain-specific data to WIA format is straightforward. Here are examples for major blockchains.

Bitcoin to WIA Conversion

async function convertBitcoinToWIA(bitcoinTx: BitcoinTransaction): Promise {
  return {
    wia_version: "1.0",
    transaction_id: bitcoinTx.txid,
    blockchain: "bitcoin",
    network: "mainnet",
    type: "transfer",
    timestamp: new Date(bitcoinTx.blocktime * 1000).toISOString(),
    block_number: bitcoinTx.blockheight,
    confirmations: bitcoinTx.confirmations,
    status: bitcoinTx.confirmations > 0 ? "confirmed" : "pending",

    inputs: bitcoinTx.vin.map(input => ({
      previous_output: {
        txid: input.txid,
        vout: input.vout
      },
      address: input.address,
      amount: {
        value: input.value.toFixed(8),
        currency: "BTC",
        decimals: 8,
        usd_value: (input.value * btcPrice).toFixed(2)
      },
      script_sig: input.scriptSig.hex,
      sequence: input.sequence
    })),

    outputs: bitcoinTx.vout.map(output => ({
      address: output.scriptPubKey.addresses[0],
      amount: {
        value: output.value.toFixed(8),
        currency: "BTC",
        decimals: 8,
        usd_value: (output.value * btcPrice).toFixed(2)
      },
      script_pubkey: output.scriptPubKey.hex,
      vout: output.n
    })),

    fee: {
      value: calculateFee(bitcoinTx).toFixed(8),
      currency: "BTC",
      decimals: 8
    }
  };
}

4.9 Benefits of Standardized Data Formats

The practical benefits of Phase 1 implementation are substantial and immediate:

4.10 Getting Started with Phase 1

Ready to implement WIA-FIN-003 Phase 1 in your project? Follow these steps:

npm install @wia/cryptocurrency-standard
# or
pip install wia-cryptocurrency-standard
# or
go get github.com/wia-official/cryptocurrency-standard

import {
  WIATransaction,
  validateTransaction,
  convertBitcoinToWIA,
  convertEthereumToWIA
} from '@wia/cryptocurrency-standard';

const ethTx = await web3.eth.getTransaction(txHash);
const wiaFormat = convertEthereumToWIA(ethTx);

if (validateTransaction(wiaFormat)) {
  // Store, display, or process the standardized data
  await database.transactions.insert(wiaFormat);
}

npm run wia:test
# Runs validation against official test vectors