Add payment rail runtime and TxODDS procurement demo

Author: trilltino

SKILLS.md

@@ -1,22 +1,28 @@
-# Skills — Solana dev
+# Skills - Solana Dev
 
-An optional Claude Code skill set that adds commands and knowledge for Solana development — handy if you
-fork or extend the escrow contract.
+An optional Claude Code skill set that adds commands and knowledge for Solana development, handy if
+you fork or extend the escrow contract.
 
-## Solana dev skill
+## Solana Dev Skill
 
 ```sh
 npx skills add https://github.com/solana-foundation/solana-dev-skill --global --yes
 ```
 
-Installed via the [`skills`](https://github.com/vercel-labs/skills) CLI. Adds Solana knowledge +
-tooling: `@solana/kit`, Anchor & Pinocchio programs, LiteSVM/Mollusk/Surfpool testing, Codama client
-generation, Token-2022, Solana Pay, and a security checklist.
+Installed via the [`skills`](https://github.com/vercel-labs/skills) CLI. Adds Solana knowledge and
+tooling: `@solana/kit`, Anchor and Pinocchio programs, LiteSVM/Mollusk/Surfpool testing, Codama
+client generation, Token-2022, Solana Pay, and a security checklist.
 
-Where it helped in this repo: the **escrow program** (`examples/txodds/escrow/`) — written,
+Where it helped in this repo: the escrow program (`examples/txodds/escrow/`) was written and
 security-reviewed against the skill's checklist (`init` not `init_if_needed`, per-order PDA seeds,
-`has_one`, `close = buyer`, checked math), built, **deployed to devnet**, and tested. That's the
-worked example of what this skill is for.
+`has_one`, `close = buyer`, checked math), built, deployed to devnet, and tested. That's the worked
+example of what this skill is for.
 
-> The skill is what you'd reach for to take a fork further — accept USDC (Token-2022), add an arbiter
-> to the escrow, or generate typed clients with Codama.
+The skill is what you'd reach for to take a fork further: accept USDC (Token-2022), add an arbiter to
+the escrow, or generate typed clients with Codama.
+
+## Solana Agent Commerce Skill
+
+This repo also includes `skills/solana-agent-commerce/`, a local builder skill for extending the
+market with paid services, seller personas, payment rails, verifier gates, Pay.sh procurement, x402
+endpoints, USDC settlement, and agent-commerce examples.

examples/txodds/README.md

@@ -70,6 +70,18 @@ On the board you can also click **Pay with Phantom / Solflare** to buy the read
 **Solana Pay** reference-tagged transfer from your wallet to the seller, verified on-chain by the proxy
 (`/api/pay-intent` + `/api/pay-verify`). Needs a Devnet-funded wallet.
 
+The board also includes **Run Pay.sh procurement demo**. That route calls
+`/api/pay-sh-edge`, has the seller buy simulated upstream context through the shared
+`payment-runtime` Pay.sh rail, writes `PAYMENT_REQUIRED -> PAYMENT_PROOF -> PAYMENT_CONFIRMED` into
+the run transcript, then settles the buyer payment through the same escrow path. Each run folder gets
+a `procurement.json` receipt beside the delivered read and settlement files.
+
+**Every settle leaves a run** — agent-settled or wallet-paid, the proxy persists it to a run ledger
+(`data/txodds-runs/`, session `web-oracle`): the read, the order-bound reference, the txs. The UI's
+**Runs panel** lists them (`/api/runs`, `/api/run?runId=`), and **Grade runs** (`/api/grade-runs`)
+checks each settled read against the **actual match result** once the fixture resolves, writing
+`outcome.json` into the run folder — paid reads graded against reality, not just delivered.
+
 ## CoralOS round (the multi-agent view)
 
 The web demo above is one agent. For the **multi-agent** version - a buyer agent + a World Cup seller

examples/txodds/agent/procurement.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest'
+import { procureTxOddsContext } from './procurement.js'
+
+describe('procureTxOddsContext', () => {
+  it('creates a Pay.sh request, verifies a receipt, and emits market payment messages', async () => {
+    const result = await procureTxOddsContext({
+      orderId: 'txodds-pay-sh-1',
+      round: 7,
+      fixtureId: '9001',
+      buyer: 'seller-agent',
+      seller: 'pay.sh/txodds-context',
+      amount: '0.03',
+    })
+    expect(result.request.rail).toBe('pay-sh')
+    expect(result.verification.paid).toBe(true)
+    expect(result.verification.proof).toMatch(/^pay-sh-demo:/)
+    expect(result.messages[0]).toContain('PAYMENT_REQUIRED round=7 rail=pay-sh')
+    expect(result.messages[1]).toContain('PAYMENT_PROOF round=7 rail=pay-sh')
+    expect(result.messages[2]).toContain('PAYMENT_CONFIRMED round=7 rail=pay-sh')
+  })
+})

examples/txodds/agent/procurement.ts

@@ -0,0 +1,98 @@
+import { createHash } from 'node:crypto'
+import {
+  type PaymentRequest,
+  type PaymentVerification,
+} from '../../../packages/payment-runtime/src/types.js'
+import { PaymentRailRouter } from '../../../packages/payment-runtime/src/rail-router.js'
+import { payShRail } from '../../../packages/payment-runtime/src/rails/pay-sh.js'
+import {
+  formatPaymentConfirmed,
+  formatPaymentProof,
+  formatPaymentRequired,
+} from '../../../packages/agent-runtime/src/market/protocol.js'
+
+export interface PayShProcurement {
+  provider: string
+  service: string
+  request: PaymentRequest
+  verification: PaymentVerification
+  messages: string[]
+}
+
+export interface PayShProcurementInput {
+  orderId: string
+  round: number
+  fixtureId: string
+  buyer: string
+  seller: string
+  amount: string
+  currency?: 'USDC'
+  provider?: string
+}
+
+export async function procureTxOddsContext(input: PayShProcurementInput): Promise<PayShProcurement> {
+  const provider = input.provider ?? 'pay.sh/txodds-context'
+  const router = new PaymentRailRouter([
+    payShRail({ providerAllowlist: [provider], catalogBaseUrl: 'https://pay.sh/api' }),
+  ])
+  const order = {
+    id: input.orderId,
+    round: input.round,
+    service: 'txline-edge-upstream',
+    buyer: input.buyer,
+    seller: input.seller,
+    amount: input.amount,
+    currency: input.currency ?? 'USDC',
+    rail: 'pay-sh' as const,
+    metadata: {
+      provider,
+      fixtureId: input.fixtureId,
+      url: `https://pay.sh/api/quicknode/rpc?fixtureId=${encodeURIComponent(input.fixtureId)}`,
+    },
+  }
+  const request = await router.requestPayment(order)
+  const receipt = receiptFor({ orderId: input.orderId, fixtureId: input.fixtureId, provider, amount: input.amount })
+  const verification = await router.verifyPayment({
+    ...request,
+    metadata: { ...request.metadata, payShReceipt: receipt },
+  })
+  const reference = request.reference ?? request.orderId
+  return {
+    provider,
+    service: order.service,
+    request,
+    verification,
+    messages: [
+      formatPaymentRequired({
+        round: input.round,
+        rail: 'pay-sh',
+        amount: request.amount,
+        currency: request.currency,
+        reference,
+        seller: input.seller,
+        ...(request.url ? { url: request.url } : {}),
+      }),
+      formatPaymentProof({
+        round: input.round,
+        rail: 'pay-sh',
+        reference,
+        proof: receipt,
+        buyer: input.buyer,
+      }),
+      formatPaymentConfirmed({
+        round: input.round,
+        rail: 'pay-sh',
+        reference,
+        paid: verification.paid,
+        amount: verification.amount,
+        currency: verification.currency,
+      }),
+    ],
+  }
+}
+
+function receiptFor(input: { orderId: string; fixtureId: string; provider: string; amount: string }): string {
+  return `pay-sh-demo:${createHash('sha256')
+    .update(`${input.orderId}:${input.fixtureId}:${input.provider}:${input.amount}`)
+    .digest('hex')}`
+}

examples/txodds/package.json

@@ -17,6 +17,7 @@
   "dependencies": {
     "@coral-xyz/anchor": "^0.32.1",
     "@pay/agent-runtime": "file:../../packages/agent-runtime",
+    "@pay/payment-runtime": "file:../../packages/payment-runtime",
     "@solana/spl-token": "^0.4.14",
     "@solana/web3.js": "^1.98.4",
     "axios": "^1.11.0",

examples/txodds/server/proxy.ts

@@ -32,6 +32,7 @@ import {
 } from '@pay/agent-runtime'
 import type { RunRecord, TranscriptEntry, TxEntry } from '@pay/agent-runtime'
 import { analyzeEdge, fairLine } from '../agent/edge.js'
+import { procureTxOddsContext, type PayShProcurement } from '../agent/procurement.js'
 import {
   makeArbiter, initConfig, open as arbiterOpen, arbitrateRelease,
   configPda, vaultPda, arbitratedEscrowPda, ARBITER_PROGRAM_ID,
@@ -257,6 +258,7 @@ function persistWebRun(args: {
   amountSol: number
   fixtureId: string
   payVerify?: any
+  procurement?: PayShProcurement
 }): any {
   const round = latestRound() + 1
   const now = new Date().toISOString()
@@ -283,18 +285,24 @@ function persistWebRun(args: {
       deposit: { sig: args.settle.open?.sig ?? args.settle.deposit?.sig ?? args.payVerify?.sig ?? '', buyer: args.settle.buyer ?? 'browser-wallet' },
     } : undefined,
     delivery: { raw: rawDelivery, data: args.read.delivery, sha256: sha256Hex(rawDelivery) },
-    verification: { verdict: deliveredOk(args.read.delivery) ? 'pass' : 'fail', checked: 'delivery-present' },
+    verification: {
+      verdict: deliveredOk(args.read.delivery) ? 'pass' : 'fail',
+      checked: 'delivery-present',
+      ...(args.procurement ? { upstreamPayment: args.procurement.verification } : {}),
+    },
     txs,
     updatedAt: now,
   }
   const transcript: TranscriptEntry[] = [
     { sender: 'web', text: JSON.stringify(args.read.request) },
+    ...(args.procurement?.messages.map((text) => ({ sender: 'seller-agent', text })) ?? []),
     { sender: 'oracle', text: rawDelivery },
     { sender: 'settlement', text: JSON.stringify(args.settle ?? args.payVerify) },
   ]
   const dir = writeRun(RUNS_DIR, run, transcript)
   fs.writeFileSync(join(dir, 'read_request.json'), JSON.stringify(args.read.request, null, 2) + '\n', 'utf8')
   fs.writeFileSync(join(dir, 'delivered_read.json'), JSON.stringify(args.read.delivery, null, 2) + '\n', 'utf8')
+  if (args.procurement) fs.writeFileSync(join(dir, 'procurement.json'), JSON.stringify(args.procurement, null, 2) + '\n', 'utf8')
   return { ...args.settle, runId: run.runId, runDir: dir }
 }
 
@@ -508,6 +516,40 @@ http
         }
         result = persistWebRun({ read, settle: result, amountSol: amount, fixtureId })
         res.end(JSON.stringify(result))
+      } else if (url.pathname === '/api/pay-sh-edge') {
+        // Seller-style demo: before delivering, the TxODDS seller buys upstream context through the
+        // payment-runtime Pay.sh rail, records the receipt, then settles the buyer payment as usual.
+        const amount = Number(url.searchParams.get('amount') ?? '0.001')
+        const upstreamUsdc = url.searchParams.get('upstreamUsdc') ?? '0.03'
+        const fixtureId = url.searchParams.get('fixtureId') ?? ''
+        const round = latestRound() + 1
+        const read = latestRead.get(fixtureId) ?? await readEdge(fixtureId)
+        const procurement = await procureTxOddsContext({
+          orderId: `${WEB_SESSION}/round-${round}/pay-sh`,
+          round,
+          fixtureId,
+          buyer: 'txodds-seller-agent',
+          seller: 'pay.sh/txodds-context',
+          amount: upstreamUsdc,
+        })
+        let result: any
+        if (arbiterKeypair()) {
+          try { result = await settleViaArbiter(amount, fixtureId, read, round) }
+          catch (e) { result = await settle(amount, fixtureId, read, round); result.arbiterError = (e as Error).message }
+        } else {
+          result = await settle(amount, fixtureId, read, round)
+        }
+        result = persistWebRun({ read, settle: result, amountSol: amount, fixtureId, procurement })
+        res.end(JSON.stringify({
+          ...result,
+          procurement: {
+            provider: procurement.provider,
+            amount: procurement.request.amount,
+            currency: procurement.request.currency,
+            paid: procurement.verification.paid,
+            proof: procurement.verification.proof,
+          },
+        }))
       } else if (url.pathname === '/api/runs') {
         res.end(JSON.stringify(listRuns(RUNS_DIR).filter((r) => r.session === WEB_SESSION).sort((a, b) => b.round - a.round)))
       } else if (url.pathname === '/api/run') {

examples/txodds/web/app.js

@@ -208,7 +208,7 @@ function EdgeCard({ edge }) {
 }
 
 // the explainer - what the app actually does, end to end, threaded with the selected fixture's numbers
-function Pipeline({ edge, source, settleRes }) {
+function Pipeline({ edge, source, settleRes, procurementRes }) {
   const fav = edge?.fair?.favourite
   const steps = [
     { n: 1, title: 'Verified data',
@@ -220,6 +220,9 @@ function Pipeline({ edge, source, settleRes }) {
     { n: 3, title: 'Settled by a neutral arbiter',
       desc: 'The buyer funds a per-order escrow but cannot unilaterally refund - a trusted neutral arbiter program releases to the seller on verified delivery. The escrow reference is bound to the read (sha256), so the on-chain order IS the data bought. Real devnet txs, linked on Explorer.',
       live: settleRes?.ok ? `${settleRes.amountSol} SOL${settleRes.mode === 'arbiter' ? ' - arbiter' : ''}` : `${SETTLE_SOL} SOL` },
+    { n: 4, title: 'Optional upstream spend',
+      desc: 'The seller can buy an upstream API through the Pay.sh rail before delivery. The run ledger stores PAYMENT_REQUIRED, PAYMENT_PROOF, and PAYMENT_CONFIRMED alongside the escrow settlement.',
+      live: procurementRes?.procurement?.paid ? `${procurementRes.procurement.amount} ${procurementRes.procurement.currency}` : 'Pay.sh' },
   ]
   return html`
     <section class="pipeline">
@@ -230,7 +233,7 @@ function Pipeline({ edge, source, settleRes }) {
             <div class="pipe-h"><span class="pipe-n">0${s.n}</span><span class="pipe-live">${s.live}</span></div>
             <h4>${s.title}</h4>
             <p>${s.desc}</p>
-            ${i < 2 && html`<span class="pipe-arrow">-></span>`}
+            ${i < steps.length - 1 && html`<span class="pipe-arrow">-></span>`}
           </div>`)}
       </div>
     </section>`
@@ -288,6 +291,21 @@ function SettleResult({ r }) {
       <a href=${addrLink(ESCROW_PROGRAM)} target="_blank" rel="noreferrer">escrow program open</a></div>`
 }
 
+function ProcurementResult({ r }) {
+  if (!r) return null
+  if (r.ok) return html`
+    <div class="settled ok pay-sh-result">
+      <div class="settled-line"><span class="bind-tag">Pay.sh</span>
+        seller procured upstream context for <b>${r.procurement?.amount} ${r.procurement?.currency}</b>
+        then settled <b>${r.amountSol} SOL</b> to the seller
+      </div>
+      <div class="settled-line bind">
+        proof <b>${shortAddr(r.procurement?.proof)}</b> stored in the run ledger as PAYMENT_PROOF
+      </div>
+    </div>`
+  return html`<div class="settled sim">Pay.sh demo unavailable${r.error ? ` (${String(r.error).slice(0, 70)})` : ''}</div>`
+}
+
 function RunsPanel({ runs, selectedRun, onSelect, onGrade, grading }) {
   const top = selectedRun ?? runs?.[0]
   const outcome = top?.outcome
@@ -324,6 +342,7 @@ function RunsPanel({ runs, selectedRun, onSelect, onGrade, grading }) {
                 <span>request <b>${top.want?.arg}</b></span>
                 ${top.delivery?.sha256 && html`<span>delivery sha <b>${shortAddr(top.delivery.sha256)}</b></span>`}
                 ${top.escrow?.reference && html`<span>escrow ref <b>${shortAddr(top.escrow.reference)}</b></span>`}
+                ${top.verification?.upstreamPayment?.rail && html`<span>upstream <b>${top.verification.upstreamPayment.rail} ${top.verification.upstreamPayment.amount} ${top.verification.upstreamPayment.currency}</b></span>`}
                 ${outcome && html`<span>reality <b>${outcome.status === 'graded'
                   ? `${outcome.actual?.winner ?? 'unknown'} - ${outcome.correct === true ? 'hit' : outcome.correct === false ? 'miss' : 'unscored'}`
                   : 'pending'}</b></span>`}
@@ -398,6 +417,8 @@ function App() {
   const [loadingOdds, setLoadingOdds] = useState(false)
   const [edge, setEdge] = useState(null)
   const [settleRes, setSettleRes] = useState(null)
+  const [procurementRes, setProcurementRes] = useState(null)
+  const [procuring, setProcuring] = useState(false)
   const [settling, setSettling] = useState(false)
   const [runs, setRuns] = useState(null)
   const [selectedRun, setSelectedRun] = useState(null)
@@ -423,6 +444,21 @@ function App() {
     finally { setGrading(false) }
   }
 
+  const runPayShDemo = async () => {
+    if (!selected || source !== 'live') return
+    setProcuring(true)
+    setProcurementRes(null)
+    try {
+      const r = await (await fetch(`${PROXY}/api/pay-sh-edge?fixtureId=${selected.FixtureId}&amount=${SETTLE_SOL}&upstreamUsdc=0.03`)).json()
+      setProcurementRes(r)
+      await loadRuns()
+    } catch (e) {
+      setProcurementRes({ ok: false, error: String(e?.message ?? e) })
+    } finally {
+      setProcuring(false)
+    }
+  }
+
   // load the board: fixtures with verified live odds (inlined). The free World Cup tier's odds are
   // intermittent and the proxy needs a few seconds to subscribe on a cold start, so we KEEP polling
   // until live data arrives - showing the labelled sample board meanwhile, then switching to live on
@@ -486,7 +522,7 @@ function App() {
   useEffect(() => {
     if (!selected) return
     let alive = true
-    setEdge(null); setSettleRes(null); setSettling(false)
+    setEdge(null); setSettleRes(null); setProcurementRes(null); setSettling(false)
     ;(async () => {
       // 1) the agent's call
       let e = clientEdge(selected)
@@ -525,7 +561,7 @@ function App() {
         turns it into <b>fair (break-even) odds + a plain read</b>, and gets paid through an on-chain escrow.</p>
     </header>
     <main>
-      <${Pipeline} edge=${edge} source=${source} settleRes=${settleRes} />
+      <${Pipeline} edge=${edge} source=${source} settleRes=${settleRes} procurementRes=${procurementRes} />
       ${!fixtures && html`<p class="muted" style=${{ textAlign: 'center' }}>loading fixtures...</p>`}
       ${selected && html`
         <section class="featured">
@@ -546,6 +582,10 @@ function App() {
                 <span class="spin"></span> agent delivered - arbiter settling ${SETTLE_SOL} SOL in escrow on devnet...
               </div>`}
               ${settleRes && html`<${SettleResult} r=${settleRes} />`}
+              <button class="pay-sh-btn" disabled=${source !== 'live' || procuring} onClick=${runPayShDemo}>
+                ${procuring ? html`<span class="spin"></span> procuring + settling...` : 'Run Pay.sh procurement demo'}
+              </button>
+              ${procurementRes && html`<${ProcurementResult} r=${procurementRes} />`}
               ${selected && html`<${PayButton} fixture=${selected} />`}
             </div>
           </div>