From 72f27042cbac2462c867a06cf3893f0f21af04b9 Mon Sep 17 00:00:00 2001 From: Berektassuly Date: Fri, 21 Aug 2026 20:31:40 +0500 Subject: [PATCH] docs: document V4 validation flows --- README.md | 5 ++++- documentation/examples/devnet-examples.mdx | 16 +++++++++++++++ documentation/examples/onchain-validation.mdx | 20 +++++++++++++++++-- 3 files changed, 38 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 07314ff..a0ea08d 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/documentation/examples/devnet-examples.mdx b/documentation/examples/devnet-examples.mdx index 9fd40cf..330150e 100644 --- a/documentation/examples/devnet-examples.mdx +++ b/documentation/examples/devnet-examples.mdx @@ -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. | @@ -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. +## 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) | + + +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. + + ## 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. diff --git a/documentation/examples/onchain-validation.mdx b/documentation/examples/onchain-validation.mdx index 3a3e189..8f13451 100644 --- a/documentation/examples/onchain-validation.mdx +++ b/documentation/examples/onchain-validation.mdx @@ -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. @@ -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) | + + +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. + + ## Common Validation Errors | Symptom | What to check |