feat: make txodds live agents explicit

Author: trilltino

.gitignore

@@ -37,6 +37,9 @@ bun.lockb
 coverage*.json
 .vercel
 
+# Local TxODDS run ledgers
+examples/txodds/data/
+
 # Reference repos cloned for analysis (not part of project)
 ref/
 

coral-agents/buyer-agent/src/index.ts

@@ -40,7 +40,7 @@ const ARGS = (process.env.BUYER_ARGS || process.env.BUYER_ARG || 'SOL-USDC').spl
 const ARG = ARGS[0]
 const BID_WINDOW_MS = Number(process.env.BID_WINDOW_MS ?? '5000')
 const CYCLE_MS = Number(process.env.CYCLE_INTERVAL_MS ?? '30000')
-const SELLERS = (process.env.MARKET_SELLERS ?? 'seller-worldcup,seller-fast,seller-premium')
+const SELLERS = (process.env.MARKET_SELLERS ?? 'seller-worldcup,seller-fast,seller-premium,seller-risk-policy,seller-fan-card')
   .split(',').map((s) => s.trim()).filter(Boolean)
 // F3: the payout wallet the buyer expects (personas share one in the demo). If set, the buyer refuses
 // to deposit to an ESCROW_REQUIRED whose seller= pubkey differs - binding the award to the payout.

coral-agents/seller-agent/README.md

@@ -22,7 +22,7 @@ In arbiter mode, the seller verifies the escrow buyer as the vault PDA from `DEP
 |---|---|
 | `src/index.ts` | Coral market loop and funding verification. |
 | `src/escrow.ts` | Read-only escrow funding check. |
-| `src/service.ts` | TxODDS service delivery. |
+| `src/service.ts` | Service delivery for `txline`, `risk-policy`, `fan-card`, and `freelance`. |
 | `src/payment.ts` | Older direct-payment helper/tests. |
 | `src/replay.ts` | Replay helpers/tests. |
 
@@ -65,7 +65,7 @@ The Pay.sh rail is a simulated proof-adapter rail until a live provider API is i
 |---|---|
 | `SELLER_WALLET` | Payout address. |
 | `AGENT_NAME` | Agent/persona name. |
-| `SERVICES` | Supported services, usually `txline`. |
+| `SERVICES` | Comma-separated supported services. Current coded services are `txline`, `risk-policy`, `fan-card`, and `freelance`. |
 | `FLOOR_SOL` | Minimum bid. |
 | `PERSONA` | Persona label/config. |
 | `SETTLEMENT_MODE` | `arbiter` or `direct`. |

coral-agents/seller-agent/src/service.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { deliverService } from './service.js'
 
-describe('deliverService txline-only routing', () => {
+describe('deliverService routing', () => {
   const realFetch = global.fetch
 
   beforeEach(() => {
@@ -19,7 +19,38 @@ describe('deliverService txline-only routing', () => {
 
   it('rejects legacy generic services', async () => {
     const out = JSON.parse(await deliverService('coingecko eth'))
-    expect(out).toEqual({ error: 'unsupported service', service: 'coingecko', supported: ['txline', 'freelance'] })
+    expect(out).toEqual({
+      error: 'unsupported service',
+      service: 'coingecko',
+      supported: ['txline', 'freelance', 'risk-policy', 'fan-card'],
+    })
+  })
+
+  it('delivers a deterministic fixture risk policy', async () => {
+    const out = JSON.parse(await deliverService('risk-policy edge 18175397'))
+    expect(out).toMatchObject({
+      service: 'risk-policy',
+      fixtureId: '18175397',
+      policy: {
+        action: 'observe',
+        maxExposureSol: 0,
+      },
+    })
+    expect(out.policy.requires).toContain('verifier pass before escrow release')
+    expect(out.policy.guardrails).toContain('no real-money wagering')
+  })
+
+  it('delivers a deterministic fan explainer card', async () => {
+    const out = JSON.parse(await deliverService('fan-card edge 18175397'))
+    expect(out).toMatchObject({
+      service: 'fan-card',
+      fixtureId: '18175397',
+      card: {
+        audience: 'fan',
+      },
+      limits: ['educational summary', 'not betting advice'],
+    })
+    expect(out.card.explainer).toContain('break-even fair line')
   })
 
   it('freelance without an LLM key returns an honest error payload (verifier fails it, no release)', async () => {

coral-agents/seller-agent/src/service.ts

@@ -1,25 +1,82 @@
 /**
  * Seller services.
  *
- * `txline` — the headline product: a verified TxLINE fair-line read for a fixture.
- * `freelance` — the generic LLM worker (the freelancer market's baseline seller): the brief goes to
+ * `txline` - verified TxLINE fair-line reads for a fixture.
+ * `risk-policy` - deterministic policy guardrails for a fixture/order.
+ * `fan-card` - deterministic fan-facing explanation card for a fixture/order.
+ * `freelance` - the generic LLM worker (the freelancer market's baseline seller): the brief goes to
  * the LLM, the deliverable comes back as JSON. Without an LLM key it returns an error payload, which
- * the verifier fails and the buyer refuses to pay for — no-capability sellers don't get released.
+ * the verifier fails and the buyer refuses to pay for - no-capability sellers don't get released.
  */
 import { complete, parseJsonReply } from '@pay/agent-runtime'
 
 const TXLINE_BASE = process.env.TXLINE_BASE_URL || 'https://txline-dev.txodds.com'
+const SUPPORTED_SERVICES = ['txline', 'freelance', 'risk-policy', 'fan-card']
 
 export async function deliverService(request: string): Promise<string> {
   const [first, ...rest] = request.trim().split(/\s+/).filter(Boolean)
   const service = (first ?? 'txline').toLowerCase()
   if (service === 'freelance') return freelanceService(rest.join(' '))
+  if (service === 'risk-policy') return riskPolicyService(rest.join(' '))
+  if (service === 'fan-card') return fanCardService(rest.join(' '))
   if (service !== 'txline') {
-    return JSON.stringify({ error: 'unsupported service', service, supported: ['txline', 'freelance'] })
+    return JSON.stringify({ error: 'unsupported service', service, supported: SUPPORTED_SERVICES })
   }
   return txlineService(rest.join(' '))
 }
 
+function fixtureIdFrom(request: string): string | undefined {
+  return request.trim().split(/\s+/).find((token) => /^\d+$/.test(token))
+}
+
+async function riskPolicyService(request: string): Promise<string> {
+  const fixtureId = fixtureIdFrom(request)
+  return JSON.stringify({
+    service: 'risk-policy',
+    ...(fixtureId ? { fixtureId } : {}),
+    request: request || 'unspecified',
+    policy: {
+      action: fixtureId ? 'observe' : 'no-action',
+      maxExposureSol: 0,
+      requires: [
+        'verified TxLINE fair-line payload',
+        'buyer budget policy pass',
+        'verifier pass before escrow release',
+      ],
+      guardrails: [
+        'devnet only',
+        'no real-money wagering',
+        'no automated sportsbook execution',
+      ],
+    },
+    rationale: fixtureId
+      ? `Fixture ${fixtureId} can be analyzed after verified fair-line delivery.`
+      : 'No fixture id supplied.',
+  })
+}
+
+async function fanCardService(request: string): Promise<string> {
+  const fixtureId = fixtureIdFrom(request)
+  const target = fixtureId ? `fixture ${fixtureId}` : 'the selected fixture'
+  return JSON.stringify({
+    service: 'fan-card',
+    ...(fixtureId ? { fixtureId } : {}),
+    request: request || 'unspecified',
+    card: {
+      title: `Fair-line explainer for ${target}`,
+      audience: 'fan',
+      explainer: 'TxODDS provides a break-even fair line. A value claim needs an outside book price above that fair price.',
+      sections: [
+        { label: 'What was bought', value: 'verified fair-line context' },
+        { label: 'What it is not', value: 'not a sportsbook recommendation' },
+        { label: 'Proof path', value: 'hash-bound delivery, verifier verdict, devnet escrow release' },
+      ],
+      shareCopy: `Agent-delivered fair-line context for ${target}; verification and settlement are recorded in the run ledger.`,
+    },
+    limits: ['educational summary', 'not betting advice'],
+  })
+}
+
 async function freelanceService(brief: string): Promise<string> {
   try {
     const text = await complete({

coral-agents/verifier-agent/src/verify.test.ts

@@ -34,6 +34,12 @@ describe('checkDelivery - deterministic checks decide first', () => {
     expect(v.sha).toBe(sha256Hex(payload))
   })
 
+  it('passes txline edge payloads for the requested fixture before consulting the LLM', async () => {
+    const txline = '{"service":"txline-edge","fixtureId":"12345","analysis":{"call":"Home value","confidence":0.7}}'
+    const v = await checkDelivery(req({ payload: txline, sha: sha256Hex(txline) }), 'v', llmSays('{"pass":false,"reason":"too literal"}'))
+    expect(v).toMatchObject({ verdict: 'pass', reason: 'hash + txline fixture verified', by: 'v' })
+  })
+
   it('honours an LLM fail verdict on structurally valid payloads', async () => {
     const v = await checkDelivery(req(), 'v', llmSays('{"pass":false,"reason":"does not answer the arg"}'))
     expect(v).toMatchObject({ verdict: 'fail', reason: 'does not answer the arg' })

coral-agents/verifier-agent/src/verify.ts

@@ -28,6 +28,14 @@ export async function checkDelivery(req: VerifyRequest, name: string, llm: Llm =
     const err = String((data as Record<string, unknown>).error).slice(0, 40)
     return { ...base, verdict: 'fail', reason: `payload reports error: ${err}` }
   }
+  const structured = data && typeof data === 'object' ? data as Record<string, unknown> : undefined
+  if (
+    req.service === 'txline' &&
+    structured?.service === 'txline-edge' &&
+    String(structured.fixtureId ?? '') === req.arg
+  ) {
+    return { ...base, verdict: 'pass', reason: 'hash + txline fixture verified' }
+  }
 
   try {
     const parsed = parseJsonReply<{ pass?: boolean; reason?: string }>(await llm({

examples/txodds/coral/README.md

@@ -6,11 +6,13 @@ This folder launches the TxODDS service as a CoralOS multi-agent session. A buye
 
 ```text
 buyer-agent
-  -> WANT service=txline arg="edge <fixtureId>"
+  -> WANT service=txline arg=<fixtureId>
 
 seller-worldcup
 seller-fast
 seller-premium
+seller-risk-policy
+seller-fan-card
   -> BID price=<sol> by=<agent>
 
 buyer-agent
@@ -21,6 +23,10 @@ buyer-agent
   -> DEPOSITED settlement=arbiter vault=<vault PDA>
 seller
   -> DELIVERED payload=<json>
+buyer-agent
+  -> VERIFY sha=<delivery hash>
+verifier-agent
+  -> VERIFIED verdict=pass
 buyer-agent
   -> ARBITER_RELEASED sig=<devnet tx>
 ```
@@ -55,6 +61,16 @@ npm run coral
 
 `round.ts` reads a live fixture id from the proxy's `/api/board` when available, starts the buyer and seller personas, and injects `SETTLEMENT_MODE=arbiter`.
 
+Default sellers:
+
+| Agent | Services |
+|---|---|
+| `seller-worldcup` | `txline` |
+| `seller-fast` | `txline` |
+| `seller-premium` | `txline` |
+| `seller-risk-policy` | `txline`, `risk-policy` |
+| `seller-fan-card` | `txline`, `fan-card` |
+
 ## Logs
 
 CoralOS names containers by generated ids. Find and tail by image: