On-Chain Validation

Prerequisites: Complete the Quickstart guide to set up authentication and subscriptions. The snippets assume jwt is the guest JWT from /auth/guest/start and apiToken is the value returned by /api/token/activate.

API Endpoints: Use https://txline.txodds.com/api/ for mainnet or https://txline-dev.txodds.com/api/ for devnet

Program setup: Use generated types that match your selected network, and use Program Addresses, Program Reference (Mainnet), or Program Reference (Devnet) for program IDs and PDA derivation.

Overview

This guide demonstrates how to validate scores data against on-chain Merkle roots using cryptographic proofs. You’ll learn how to fetch validation data and perform single-stat, two-stat, and V2 multi-stat validations. The public /api/scores/stat-validation endpoint supports both validation shapes:

Query shape	On-chain method	Notes
`statKey=...` and optional `statKey2=...`	`validateStat`	Legacy single-stat and two-stat validation.
`statKeys=1,2,...`	`validateStatV2`	Current multi-stat validation with indexed strategy predicates.

Use the same network for the API request, IDL/types, program ID, and on-chain root PDA.

The repository now includes runnable devnet examples for both paths in examples/devnet/scripts. See Runnable Devnet Examples for setup and script mapping.

Validation Checklist

Before calling validateStat, confirm:

The proof came from the same API host as your activated subscription.
The program ID matches the network used for the proof.
daily_scores_roots is derived from the same timestamp you pass into validateStat.
The epoch day is encoded as u16 little-endian.
Every proof hash is decoded to exactly 32 bytes.
The fixture ID and sequence number refer to the score update you intend to validate.
For V2, each strategy index refers to the same position in the requested statKeys array.

Setup

import * as anchor from "@coral-xyz/anchor";
import { PublicKey, ComputeBudgetProgram } from "@solana/web3.js";
import { BN } from "@coral-xyz/anchor";
import axios from "axios";

const provider = anchor.AnchorProvider.env();
anchor.setProvider(provider);
const program = anchor.workspace.Txoracle as anchor.Program<Txoracle>;

// Create HTTP client with authentication
const httpClient = axios.create({
  timeout: 30000,
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${jwt}`,
    "X-Api-Token": apiToken
  },
  baseURL: "https://txline.txodds.com",
});

// For devnet, use baseURL: "https://txline-dev.txodds.com".

function toBytes32(value: string | number[] | Uint8Array): number[] {
  const bytes = Array.isArray(value)
    ? Uint8Array.from(value)
    : value instanceof Uint8Array
      ? value
      : value.startsWith("0x")
        ? Buffer.from(value.slice(2), "hex")
        : Buffer.from(value, "base64");

  if (bytes.length !== 32) {
    throw new Error(`Expected 32 bytes, received ${bytes.length}`);
  }

  return Array.from(bytes);
}

function toProofNodes(nodes: Array<{ hash: string | number[] | Uint8Array; isRightSibling: boolean }>) {
  return nodes.map((node) => ({
    hash: toBytes32(node.hash),
    isRightSibling: node.isRightSibling,
  }));
}

Fetching Scores Data

Retrieve a snapshot of scores for a specific fixture:

const fixtureId = 17952170;
const response = await httpClient.get(`/api/scores/snapshot/${fixtureId}?asOf=${Date.now()}`);
console.log(`Snapshot for fixture ${fixtureId}:`, response.data);

Search for recent score updates:

const now = new Date();
const targetTime = new Date(now.getTime() - (5 * 300000)); // 25 minutes ago
const epochDay = Math.floor(targetTime.getTime() / 86400000);
const hourOfDay = targetTime.getUTCHours();
const interval = Math.floor(targetTime.getUTCMinutes() / 5);

const updates = await httpClient.get(`/api/scores/updates/${epochDay}/${hourOfDay}/${interval}`);
console.log(`Updates found:`, updates.data);

Choosing the Score Sequence

The seq parameter is not a placeholder. Use the sequence value from a real score record observed through one of the scores data endpoints:

/api/scores/snapshot/{fixtureId}
/api/scores/updates/{epochDay}/{hourOfDay}/{interval}
/api/scores/historical/{fixtureId}
/api/scores/stream

Do not call /api/scores/stat-validation with seq=0. Score sequences start at 1 for a fixture and increment as new score records are produced. Depending on your client and response mapper, the payload field may appear as Seq or seq; use that observed value when requesting the validation proof.

const scoreRecord = updates.data[0];
const seq = scoreRecord.Seq ?? scoreRecord.seq;

if (!Number.isInteger(seq) || seq < 1) {
  throw new Error("Use a real score record sequence; seq=0 is not valid");
}

const validation = await httpClient.get("/api/scores/stat-validation", {
  params: {
    fixtureId: scoreRecord.FixtureId ?? scoreRecord.fixtureId,
    seq,
    statKey: 1002
  }
});

Phase and Status Semantics

Pick the score record whose game phase matches the condition you want to prove. For example, “final score of the first half” should use the record for the completed first-half phase or halftime/rest state, not an arbitrary in-running first-half update. If you validate an in-running first-half record, the predicate means the condition was true at that observed moment. That is different from proving the final first-half result. Check the sport-specific phase tables, such as Soccer Feed, and use the score record’s statusId, StatusId, gameState, or equivalent phase field when deciding whether a record is suitable for settlement. For final match outcome settlement on the current devnet and mainnet releases, use a scores record with action=game_finalised. These finalisation records set statusId and period to 100, so the same final-outcome validation path covers regulation-time wins, extra-time wins, penalty wins, and abandoned matches.

Single-Stat Validation

Validate a single statistic against on-chain Merkle roots:

// Fetch validation data from API
const response = await httpClient.get("/api/scores/stat-validation", {
  params: {
    fixtureId: 17952170,
    seq: 941,
    statKey: 1002
  }
});
const validation = response.data;

// Prepare fixture summary
const fixtureSummary = {
  fixtureId: new BN(validation.summary.fixtureId),
  updateStats: {
    updateCount: validation.summary.updateStats.updateCount,
    minTimestamp: new BN(validation.summary.updateStats.minTimestamp),
    maxTimestamp: new BN(validation.summary.updateStats.maxTimestamp),
  },
  eventsSubTreeRoot: toBytes32(validation.summary.eventStatsSubTreeRoot),
};

// Prepare Merkle proofs
const fixtureProof = toProofNodes(validation.subTreeProof);
const mainTreeProof = toProofNodes(validation.mainTreeProof);

// Prepare stat to validate
const stat1 = {
  statToProve: validation.statToProve,
  eventStatRoot: toBytes32(validation.eventStatRoot),
  statProof: toProofNodes(validation.statProof),
};

// Define validation predicate
const predicate = {
  threshold: 0,
  comparison: { greaterThan: {} },
};

// For a first sanity check, use exact equality if the response exposes
// validation.statToProve.value:
// const predicate = {
//   threshold: validation.statToProve.value,
//   comparison: { equalTo: {} },
// };

// Find the daily scores PDA
const targetTs = validation.summary.updateStats.minTimestamp;
const epochDay = Math.floor(targetTs / (24 * 60 * 60 * 1000));

const [dailyScoresPda] = PublicKey.findProgramAddressSync(
  [
    Buffer.from("daily_scores_roots"),
    new BN(epochDay).toArrayLike(Buffer, "le", 2),
  ],
  program.programId
);

// Execute validation using view (read-only simulation)
const computeBudgetIx = ComputeBudgetProgram.setComputeUnitLimit({
  units: 1_400_000
});

try {
  const isValid = await program.methods
    .validateStat(
      new BN(targetTs),
      fixtureSummary,
      fixtureProof,
      mainTreeProof,
      predicate,
      stat1,
      null,  // No second stat
      null   // No operator
    )
    .accounts({
      dailyScoresMerkleRoots: dailyScoresPda
    })
    .preInstructions([computeBudgetIx])
    .view();

  if (isValid) {
    console.log("On-chain stat validation passed");
  } else {
    console.log("On-chain stat validation rejected the predicate");
  }
} catch (err) {
  console.error("Validation simulation failed:", err);
}

Two-Stat Validation

Validate a comparison between two stats (e.g., score difference). This example builds on the single-stat validation above:

// Fetch validation data including a second stat
const response2 = await httpClient.get("/api/scores/stat-validation", {
  params: {
    fixtureId: 17952170,
    seq: 941,
    statKey: 1002,
    statKey2: 1003
  }
});
const validation2 = response2.data;

// Prepare second stat (stat1 is already defined above)
const stat2 = {
  statToProve: validation2.statToProve2,
  eventStatRoot: toBytes32(validation2.eventStatRoot),
  statProof: toProofNodes(validation2.statProof2),
};

// Define operation and predicate
const op = { subtract: {} };
const predicate2 = {
  threshold: 5,
  comparison: { lessThan: {} },
};

// Execute two-stat validation (reuses variables from single-stat example)
const isValid2 = await program.methods
  .validateStat(
    new BN(targetTs),
    fixtureSummary,
    fixtureProof,
    mainTreeProof,
    predicate2,
    stat1,
    stat2,
    op
  )
  .accounts({
    dailyScoresMerkleRoots: dailyScoresPda,
  })
  .preInstructions([computeBudgetIx])
  .view();

console.log("Two-stat validation result:", isValid2);

V2 Multi-Stat Validation

Use statKeys when you need the current V2 payload and strategy model. The requested key order is important: the response arrays statsToProve and statProofs are mapped by position, and strategy fields such as index, indexA, indexB, and statIndex refer to those same 0..N positions. Every stat in payload.stats must be covered exactly once by the strategy, or the program returns IncompleteStatCoverage.

const responseV2 = await httpClient.get("/api/scores/stat-validation", {
  params: {
    fixtureId: 18175981,
    seq: 991,
    statKeys: "1,2,3001",
  },
});
const validationV2 = responseV2.data;

const targetTsV2 = validationV2.summary.updateStats.minTimestamp;
const epochDayV2 = Math.floor(targetTsV2 / (24 * 60 * 60 * 1000));

const [dailyScoresPdaV2] = PublicKey.findProgramAddressSync(
  [
    Buffer.from("daily_scores_roots"),
    new BN(epochDayV2).toArrayLike(Buffer, "le", 2),
  ],
  program.programId
);

const payload = {
  ts: new BN(targetTsV2),
  fixtureSummary: {
    fixtureId: new BN(validationV2.summary.fixtureId),
    updateStats: {
      updateCount: validationV2.summary.updateStats.updateCount,
      minTimestamp: new BN(validationV2.summary.updateStats.minTimestamp),
      maxTimestamp: new BN(validationV2.summary.updateStats.maxTimestamp),
    },
    eventsSubTreeRoot: toBytes32(validationV2.summary.eventStatsSubTreeRoot),
  },
  fixtureProof: toProofNodes(validationV2.subTreeProof),
  mainTreeProof: toProofNodes(validationV2.mainTreeProof),
  eventStatRoot: toBytes32(validationV2.eventStatRoot),
  stats: validationV2.statsToProve.map((stat: unknown, index: number) => ({
    stat,
    statProof: toProofNodes(validationV2.statProofs[index]),
  })),
};

const strategy = {
  geometricTargets: [],
  distancePredicate: null,
  discretePredicates: [
    {
      binary: {
        indexA: 0, // statKeys[0] -> 1
        indexB: 1, // statKeys[1] -> 2
        op: { subtract: {} },
        predicate: {
          threshold: 0,
          comparison: { equalTo: {} },
        },
      },
    },
    {
      single: {
        index: 2, // statKeys[2] -> 3001
        predicate: {
          threshold: 0,
          comparison: { greaterThan: {} },
        },
      },
    },
  ],
};

const isValidV2 = await program.methods
  .validateStatV2(payload, strategy)
  .accounts({
    dailyScoresMerkleRoots: dailyScoresPdaV2,
  })
  .preInstructions([computeBudgetIx])
  .view();

console.log("V2 validation result:", isValidV2);

For complete runnable versions, use:

Script	V2 coverage
`subscription_scores_1stat.ts`	One requested stat with `validateStatV2`.
`subscription_scores_v2.ts`	Two-stat strategies and geometric validation.
`subscription_scores_v2a.ts`	Multi-leg strategies using four requested stat keys.

Common Validation Errors

Symptom	What to check
`InvalidMainTreeProof`	Use the same `targetTs` for `validateStat` and `daily_scores_roots` PDA derivation. Confirm the proof hashes are exactly 32 bytes and not reversed. Confirm fixture ID and `seq` match the returned proof payload.
Account integrity passes but proof fails	The PDA is probably on the right network, but the timestamp, interval, or proof payload may not match the on-chain root. Recompute `epochDay = Math.floor(targetTs / 86400000)`.
Predicate returns false	First test with an exact predicate against the returned stat value, then replace it with your application predicate.
`IncompleteStatCoverage`	Ensure every entry in `payload.stats` is referenced exactly once by a discrete predicate or geometric target. Remove unused requested stats or add the missing strategy coverage.
V2 strategy validates the wrong stat	Confirm the requested `statKeys` order and the positional strategy indexes match. `index: 0` means the first requested key, not the smallest stat key.
`401` or `403` from the proof endpoint	Renew the guest JWT, keep the `X-Api-Token`, and confirm both credentials came from the same network host.

See Troubleshooting for the full activation, streaming, and validation checklist.

Real-Time Scores Streaming

Subscribe to real-time scores updates:

const streamUrl = "https://txline.txodds.com/api/scores/stream";
const streamResponse = await fetch(streamUrl, {
  headers: {
    Authorization: `Bearer ${jwt}`,
    "X-Api-Token": apiToken,
    Accept: "text/event-stream",
    "Cache-Control": "no-cache",
  },
});

if (!streamResponse.ok) {
  throw new Error(`Stream failed: ${streamResponse.status}`);
}

// Reuse the readSseMessages and parseSseData helpers from the Streaming Data guide.
for await (const message of readSseMessages(streamResponse)) {
  console.log(message.event ?? "message", parseSseData(message.data));
}

Validation Use Cases

On-chain validation enables trustless verification of:

Trading Settlement - Prove score outcomes for bet settlement
Conditional Logic - Execute smart contract logic based on verified game stats
Dispute Resolution - Provide cryptographic proof of game data
Automated Markets - Settle prediction markets with on-chain verification
Score Differentials - Validate margins and score differences for complex betting scenarios

Getting started

Odds

Scores

Solana Programs

Examples

Legal

Overview

Validation Checklist

Setup

Fetching Scores Data

Choosing the Score Sequence

Phase and Status Semantics

Single-Stat Validation

Two-Stat Validation

V2 Multi-Stat Validation

Common Validation Errors

Real-Time Scores Streaming

Validation Use Cases

​Overview

​Validation Checklist

​Setup

​Fetching Scores Data

​Choosing the Score Sequence

​Phase and Status Semantics

​Single-Stat Validation

​Two-Stat Validation

​V2 Multi-Stat Validation

​Common Validation Errors

​Real-Time Scores Streaming

​Validation Use Cases

Overview

Validation Checklist

Setup

Fetching Scores Data

Choosing the Score Sequence

Phase and Status Semantics

Single-Stat Validation

Two-Stat Validation

V2 Multi-Stat Validation

Common Validation Errors

Real-Time Scores Streaming

Validation Use Cases