Skip to content
A91yPublic

About

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Full-Time

A trust-minimized settlement rail for parametric sports markets on Solana. Resolution by proof, not by permission.

TxODDS anchors a daily Merkle root of all match data on-chain; the leaf + sibling hashes are fetched from a normal REST API at settlement time. validate_stat recomputes the root from the supplied proof and compares it to the anchored one. A forged score fails, so settlement stays trustless even though the data path is a centralized convenience.

What this is: settlement infrastructure, shown through a prediction market. The permissionless proof-based settlement engine is the product; @fulltime/settle packages it as an installable SDK (any Node app can create → place → settle-by-proof → claim); the yes/no market in web/ is the reference app that consumes that SDK; the keeper is an internal component that settles autonomously (proving anyone can). Every hard property here (no admin, provable finality, self-correcting overrides, a refund that can't lock funds) is a settlement property, not a betting-UX one.

Built for the TxODDS World Cup Hackathon: Prediction Markets & Settlement track. TxODDS built the verifiable, blockchain-anchored data layer; Full-Time is the permissionless settlement layer that consumes it: the trustless, no-operator version of automated settlement that any TxLINE builder can plug into. The same engine settles parametric insurance/hedging, prize-pool payouts, and B2B escrow, not just bets (see Beyond betting).

Live demo: fulltime.ayushagr.me · Devnet program: 2WutitkMWgjionZjL8dTv5MrANNdYkAqDgR2oAMtSZzH · Powered by TxLINE (TxODDS) — verifiable match data + on-chain proofs. Full-Time is the settlement layer built on it.


What it does

  • Users lock USDC into a market on a real World Cup fixture + a parametric condition (single-stat like "P1 total goals > 0.5", or two-stat with add/subtract like "total goals > 2.5").
  • After the match, anyone submits TxODDS's game_finalised proof and the market resolves: no operator, no oracle key, no dispute committee.
  • Winners split the losing pool pro-rata, minus a protocol fee. If a match never finalises (postponed/cancelled), anyone can trigger a refund, so funds are never locked.

Beyond betting

The same settle-by-proof engine is a settlement primitive, not a betting feature. The market is one framing of many (same instructions, different copy):

  • Parametric sports insurance / hedging: a fan-fest buys "match abandoned → payout" cover; a bar hedges "fewer than 1 goal → payout." Collateral sits in a neutral PDA, released the instant a verified TxLINE proof is submitted.
  • Fantasy / prize-pool settlement: a pool pays out by proof, with no operator holding the pot.
  • B2B escrow: two parties escrow USDC against a match-stat condition and settle trustlessly.

How settlement works (the core)

settle is permissionless (no authority signer) and trustless because every outcome-determining field is bound to the market's stored terms before the CPI:

                       off-chain (convenience)             on-chain (trust)
 user ──place USDC──▶ Market PDA ──▶ vault (escrow)
                          │
 keeper ─ GET /scores/snapshot ─────── detect game_finalised (statusId = 100)
        ─ GET /scores/stat-validation ─ period = 100 proof
                          │
                          └─ settle ──CPI──▶ txoracle::validate_stat ──▶ daily_scores_merkle_roots
                                             recompute Merkle root, compare → outcome bool [0]/[1]
 winners ──claim──▶ stake + pro-rata(losing pool) − fee
  • Provable finality: binds stat.period == 100, TxODDS's game_finalised marker, which covers regulation / extra time / penalties / abandonment as one signal. (We raised the "match status isn't provable" gap with TxODDS; they shipped this marker.)
  • State machine Open → Resolved | Refunded, with a fixed contest window: a real settle can override a premature refund, and a strictly-newer proof can correct an earlier settle, but the claim-lock time is fixed on the first transition, so no one can stall claims (no timer-reset attack).
  • Refund fallback: any market not resolved by deadline + grace_window is refundable by anyone (mirrors TxODDS's own refund_batch expiry model; cancelled/postponed isn't provable on-chain, so time is the only no-lock guarantee).

Program interface

Instruction Signer Purpose
init_market creator Create market + vault; period must be 100 (finalised-only).
place user Lock USDC yes/no while Open and before deadline.
settle none CPI validate_stat on a period=100 proof → Resolved. Overrides refund / weaker settle within the contest window.
refund none After deadline + grace_window → Refunded.
claim user The only fund transfer: pays winners / returns stakes (fee only on genuine resolution; refunds & voids return stake whole); closes Position.

PDAs: Market ["market", fixture_id, market_nonce] · Position ["position", market, user] · vault = market PDA's ATA. TxODDS roots: daily_scores_merkle_roots ["daily_scores_roots", epoch_day u16 LE].

SDK: @fulltime/settle

The settlement flow is packaged as a dependency-light, BYO-token, Node-first TypeScript SDK (packages/settle) so a third party can build on the engine without this repo or the web app:

import { SettleClient } from "@fulltime/settle";

const ft = new SettleClient({ rpcUrl, txlineOrigin, jwt, apiToken, keypair });
const { market } = await ft.createMarket({ fixtureId, spec, deadline, graceWindow, contestWindow, feeBps, feeRecipient: ft.wallet });
await ft.placeBet(market, true, 1_000_000n);
await ft.settleByProof(market, fixtureId, spec);   // permissionless: fetches the game_finalised proof + submits
await ft.claim(market);
  • Bring your own TxLINE token (free World Cup tier): never bundled; it fetches the proof direct from TxLINE (no Next proxy).
  • Verified end-to-end on devnet (create → place → settle-by-proof → claim, no web app). @solana/kit + Codama + axios; no React/Next.
  • The web/ app is itself a consumer: it imports the Codama client, instruction builders, and constants from this package. Scope note: createMarket is USDC-wired though the program takes any Token-2022 mint. See packages/settle/README.md.

TxLINE endpoints used

  • GET /api/scores/snapshot/{fixtureId}: detect game_finalised (StatusId == 100).
  • GET /api/scores/stat-validation?fixtureId&seq&statKey[&statKey2]: the period=100 Merkle proof.
  • GET /api/fixtures/snapshot: fixture metadata.
  • On-chain: txoracle::validate_stat (CPI) + subscribe (free World Cup tier).

Deployed

  • Devnet program: 2WutitkMWgjionZjL8dTv5MrANNdYkAqDgR2oAMtSZzH (Solscan)
  • Txoracle (TxLINE) devnet: 6pW64gN1s2uqjHkn1unFeEjAwJkPGHoppGvS715wyP2J
  • Settlement asset: any SPL/Token-2022 mint. The e2e uses Circle devnet USDC 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU (fund your wallet at faucet.circle.com).

Quickstart

npm install
cp .env.example .env         # fill RPC_URL, API_ORIGIN, KEEPER_KEYPAIR, TXORACLE_PROGRAM, TXL_MINT
npm run subscribe            # free World Cup tier → TXLINE_JWT + TXLINE_API_TOKEN in .env

npm run test:setup && npm test   # build + regen the gitignored txoracle.so, then the LiteSVM suite (44/44)
npm run keeper:verify            # keeper on LiteSVM + live detection (7/7)
npm run e2e                      # full lifecycle on devnet: deploy target → place → keeper settles → claim (6/6, prints Solscan links)
npm run keeper                   # run the settlement keeper against the configured cluster

Web app (web/)

A Next.js reference dApp, and a consumer of @fulltime/settle: it imports the Codama client, instruction builders, and constants from the SDK, keeping only the genuinely browser-specific pieces (a server-side TxLINE proxy so tokens never reach the browser, and wallet-adapter signing). Create markets, bet, and settle / refund / claim by proof from the browser, plus a live, shareable ProofReceipt that no incumbent shows. No database.

# build the SDK first; web resolves @fulltime/settle from its dist/
cd packages/settle && npm install && npm run build
cd ../web && npm install && npm run dev     # http://localhost:3000

See web/README.md for stack, architecture, and the wallet↔kit signing bridge.

Demo

npm run e2e is the money shot: it creates a market on the real finalised fixture 18187298, funds two wallets, and, with no human touching settlement, the keeper detects game_finalised via the live TxLINE API, submits the period=100 proof, and settle verifies it on-chain against TxODDS's anchored root. Winner claims live; every step prints a Solscan link.

Live devnet run (6/6, real Circle devnet USDC):

(Video: link TBD.)

Security / trust notes

  • No admin, no oracle key. Settle has no authority signer: anyone can call it; the proof decides. settled_by is recorded for audit only.
  • Centralized API, trustless verification. A fake score won't match the on-chain Merkle root → validate_stat rejects it.
  • Funds are never lockable. Not resolved by deadline + grace_window ⇒ refundable by anyone.
  • Bounded, self-correcting. Overrides need a strictly-newer proof; the contest window can't be extended; identical/weaker proofs are rejected.
  • Fee only on genuine resolution. Refunds and empty-winning-side voids return the stake whole, so the protocol never keeps funds when there's no winner.

Limitations & roadmap

  • Client SDK shipped; on-chain crate is roadmap. The settle-by-proof flow is now an installable TS SDK, @fulltime/settle (packages/settle), so any Node app can create → place → settle → claim. The deeper primitive, a reusable Rust verify_stat crate so any program CPIs it directly, remains roadmap.
  • Abandoned matches settle on TxODDS's official finalised stats (abandonment isn't distinguishable on-chain); refund only covers matches that never finalise.
  • Finality is liveness-based: correctness needs someone to submit the true-final proof within the contest window (winners are incentivised to). game_finalised can lag 10 to 15 min (player-stat checks).

About

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages