Skip to content

docs: document V4 validation flows and runnable examples #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
beriktassuly wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: document V4 validation flows and runnable examples #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,12 +95,15 @@ Use one network consistently. Devnet subscribe transactions must use the devnet

## Current Examples

The current copy-paste examples live in the hosted documentation pages rather than a top-level `examples/` directory:
The hosted documentation pages provide the guided integration flows. Runnable end-to-end scripts are available in [`examples/devnet/scripts`](https://github.com/txodds/tx-on-chain/tree/main/examples/devnet/scripts) and [`examples/mainnet/scripts`](https://github.com/txodds/tx-on-chain/tree/main/examples/mainnet/scripts):

- [Quickstart](https://txline.txodds.com/documentation/quickstart) - purchase, subscribe, activate, and API-token header setup.
- [Fetching Snapshots](https://txline.txodds.com/documentation/examples/fetching-snapshots) - fixtures, odds, and scores snapshots.
- [Streaming Data](https://txline.txodds.com/documentation/examples/streaming-data) - odds and scores Server-Sent Events.
- [On-Chain Validation](https://txline.txodds.com/documentation/examples/onchain-validation) - validation proof retrieval and program calls.
- [`purchase_tokens_usdt.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/purchase_tokens_usdt.ts) - Devnet TxLINE token purchase using a backend quote and fake Devnet USDT.
- [`subscription_scores_v4.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_scores_v4.ts) - V2 and V4 score-validation comparison, including the state-changing V4 validation flow.
- [`subscription_granular_custom_demo_v4.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_granular_custom_demo_v4.ts) - custom-league subscription and paid V4 odds validation on devnet.

The `backup/` directory is a historical archive of older Anchor examples and IDL snapshots. It is kept for reference only and should not be treated as the current integration path.

Expand Down
16 changes: 16 additions & 0 deletions documentation/examples/devnet-examples.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,12 +35,15 @@ yarn ts-node examples/devnet/scripts/subscription_free_tier.ts

| Script | What it demonstrates |
|--------|----------------------|
| [`purchase_tokens_usdt.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/purchase_tokens_usdt.ts) | Purchasing TxLINE tokens on devnet with a backend quote and fake Devnet USDT, with local transaction-safety verification before signing. |
| [`subscription_free_tier.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_free_tier.ts) | Free-tier subscription activation, odds snapshot fetches, and odds SSE streams. |
| [`subscription_scores.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_scores.ts) | Scores snapshots, recent score scanning, legacy `validateStat` with `statKey`, and scores SSE streams. |
| [`subscription_scores_1stat.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_scores_1stat.ts) | Latest V2 score validation with one requested `statKeys` entry and `validateStatV2`. |
| [`subscription_scores_v2.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_scores_v2.ts) | V2 validation with two stats, binary predicates, and geometric distance predicates. |
| [`subscription_scores_v2a.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_scores_v2a.ts) | Rich multi-leg V2 validation with `statKeys=1,2,3001,3002` and two-, three-, and four-leg strategies. |
| [`subscription_scores_v3c.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_scores_v3c.ts) | V3 multiproof validation demonstrating both V2 and V3 validation approaches for comparison. |
| [`subscription_scores_v4.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_scores_v4.ts) | V2 and V4 score-validation comparison, including V4 multiproof payloads, validation-credit purchase, and a state-changing `validateStatV4` transaction. |
| [`subscription_granular_custom_demo_v4.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_granular_custom_demo_v4.ts) | Custom-league subscription, odds discovery, and paid V4 odds validation with validation credits and `validateOddsV4`. |
| [`fixture_validation_view_only.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/fixture_validation_view_only.ts) | Fixture proof validation by simulation using the fixture validation endpoint and on-chain PDA. |
| [`historical_scores.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/historical_scores.ts) | Fetching complete historical score updates for a specific fixture. |

Expand Down Expand Up @@ -83,6 +86,19 @@ const payload = {
The fixed `fixtureId` and `seq` pairs in the example scripts are demo fixtures. In production, derive `fixtureId`, `seq`, phase, and status from an observed score record from snapshot, updates, historical data, or the scores stream.
</Warning>

## V4 Validation

V4 is a paid, state-changing validation path. The API returns a validation `payload` and signature; the examples serialize the payload with the matching IDL/types, add an Ed25519 verification instruction, purchase validation credits, and submit the V4 transaction.

| Data | API request | On-chain instruction | Runnable devnet example |
|------|-------------|----------------------|-------------------------|
| Scores | `/scores/stat-validation-v4?fixtureId=...&seq=...&statKeys=...` | `validateStatV4` | [`subscription_scores_v4.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_scores_v4.ts) |
| Odds | `/odds/validation-v4?messageId=...&ts=...` | `validateOddsV4` | [`subscription_granular_custom_demo_v4.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_granular_custom_demo_v4.ts) |

<Warning>
Unlike the V2 examples, the V4 examples submit transactions and purchase validation credits. Run them with a devnet wallet and the matching devnet IDL/types; do not substitute a mainnet wallet or endpoint.
</Warning>

## Final Outcome and Fixtures

On the current devnet and mainnet releases, final scores records use `action=game_finalised` with `statusId=100` and `period=100`. Use those records when validating or settling the final match outcome, regardless of whether the match ended after regulation time, extra time, penalties, or abandonment.
Expand Down
20 changes: 18 additions & 2 deletions documentation/examples/onchain-validation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,14 +17,15 @@ description: "Validate scores data using cryptographic Merkle proofs"

## 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.
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, V2 multi-stat, and V4 state-changing validations.

The public `/api/scores/stat-validation` endpoint supports both validation shapes:
The score-validation endpoints support the following validation paths:

| 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. |
| `statKeys=1,2,...` at `/api/scores/stat-validation-v4` | `validateStatV4` | Paid, state-changing score validation with a signed multiproof payload. |

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

Expand Down Expand Up @@ -389,6 +390,21 @@ For complete runnable versions, use:
| [`subscription_scores_v2.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_scores_v2.ts) | Two-stat strategies and geometric validation. |
| [`subscription_scores_v2a.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_scores_v2a.ts) | Multi-leg strategies using four requested stat keys. |

## V4 Validation

V4 validates an API-provided payload and signature in a state-changing transaction. The response contains a `payload` and `signature`; serialize the payload with the selected network's matching IDL/types, hash the serialized bytes with SHA-256, and add the corresponding Ed25519 verification instruction before the V4 call.

Before sending the transaction, purchase validation credits with `purchaseValidationCredits`. The V4 instructions require the signing user, the user's validation-state PDA, the instructions sysvar, and the matching daily Merkle-roots PDA.

| Data | Proof endpoint | On-chain instruction | Runnable devnet example |
|------|----------------|----------------------|-------------------------|
| Scores | `/api/scores/stat-validation-v4?fixtureId=...&seq=...&statKeys=...` | `validateStatV4(payload, strategy)` | [`subscription_scores_v4.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_scores_v4.ts) |
| Odds | `/api/odds/validation-v4?messageId=...&ts=...` | `validateOddsV4(payload)` | [`subscription_granular_custom_demo_v4.ts`](https://github.com/txodds/tx-on-chain/blob/main/examples/devnet/scripts/subscription_granular_custom_demo_v4.ts) |

<Warning>
V4 is not a drop-in replacement for the V2 `.view()` examples: it purchases validation credits and submits a transaction. Start with the runnable devnet scripts, use the devnet endpoint, program ID, and generated types together, and review the transaction before signing.
</Warning>

## Common Validation Errors

| Symptom | What to check |
Expand Down