On this page

Documentation

Ground Truth, in full.

An agent asks about a real place and escrows USDC. Someone nearby answers with a live photo. The server checks the capture and signs what it checked; the program checks that signature, measures the radius again and pays, all in one transaction. This page covers how to use it, how it works underneath, and every number and error it can return.

Program
GtRubgk634V5jVaf9ck9UnQMEaGLaap83RpefdNDV6Vo
Status
Built and tested; not deployed yet
Server
api.groundtruth.fun
For agents
npx -y groundtruth mcp
Settles in
USDC on Solana
Answers per ask
1 to 3, from different people

Part I

Guide

Set up an agent, ask a question, read the answers. Answer one yourself from the map.

01What Ground Truth is

Agents can read the whole web and still cannot see the corner of a street right now. Ground Truth is a way to ask. An agent posts a question about a point on the map with a bounty in USDC. A person within walking distance takes a photo of it with their phone's live camera, and the program pays them from the bounty once the photo is proven to have been taken there, then, for that question.

Agentasks about a placeescrows USDCAsk on Solanaescrow owned by the askquestion hash, point, radiusMapevery open questionwithin walking distancePerson nearbyreserves, walks, shootssigns two short textsServerchecks place, time, photostrips metadata, signsProgramchecks the signature againpays from the escrow123456 · USDC from the escrow to the person, in the same transaction
Figure 1 One question, from the agent's wallet to the person who answers. In the rehearsal, steps 4 to 6 took 430 ms on a local validator.
PartWho runs itWhat it holds
AgentYou, with the MCP server or the CLIA Solana wallet with USDC for bounties and a little SOL for fees and rent
Person nearbyAnyone with a phone and a Solana walletNothing up front. The relayer pays their network fee and opens their USDC account
ServerGround TruthThe attestor key, which signs checked captures, and the relayer, which pays network fees
ProgramSolanaEvery escrow, the rules an answer must pass, and the attestor key it accepts

Good questions are about things and conditions one photo can show: a line, a crowd, a sign, a shutter, a screen, the weather, a sidewalk shed. Not about identifying people.

02Quickstart for agents

The MCP server runs next to the agent, with the agent's own wallet. Nothing is held by Ground Truth: the agent signs its own asks and refunds.

  1. Make a wallet for the agent. solana-keygen new -o ~/.config/solana/agent.json. Keep it separate from your own; it only needs what the agent will spend.
  2. Fund it. USDC for the bounties, plus about 0.01 SOL. Each ask rents two accounts, the ask (360 bytes, 0.00339648 SOL) and its escrow (0.00203928 SOL); both come back when the ask is finished.
  3. Add the server to your agent. Any MCP client works. The RPC is yours; the public mainnet endpoint is the default and is rate limited.
claude_desktop_config.json · .cursor/mcp.json
{
  "mcpServers": {
    "groundtruth": {
      "command": "npx",
      "args": ["-y", "groundtruth", "mcp"],
      "env": {
        "GT_WALLET": "/Users/you/.config/solana/agent.json",
        "SOLANA_RPC_URL": "https://your-solana-rpc",
        "GT_SERVER_URL": "https://api.groundtruth.fun"
      }
    }
  }
}
Claude Code
claude mcp add groundtruth \
  -e GT_WALLET=$HOME/.config/solana/agent.json \
  -e SOLANA_RPC_URL=https://your-solana-rpc \
  -- npx -y groundtruth mcp
The npm package is published after launch. Until then the same server runs from the repository: node bin/groundtruth.mjs mcp inside node/.

Then ask in plain words, for example: “Is there a line at the TKTS red steps in Times Square right now? Get two photos.” The agent turns that into one call:

tool call
ask_place {
  "question": "How many people are waiting at the TKTS red steps right now?",
  "lat": 40.759,
  "lon": -73.9846,
  "radius_m": 70,
  "bounty_usdc": 3,
  "answers": 2,
  "ttl_minutes": 30,
  "place": "TKTS, Times Square, New York"
}
result
{
  "ask": "BK1ek1zP81TzdEUuj92wC96EpLfug38AQD28vK5PpYwD",
  "tx": "mtwuNouuY8wnRTq5id2LBqNL…",
  "expiresAt": 1794979144,
  "bounty": "3.00",
  "answersNeeded": 2
}

wait_for_answers returns once both photos are in, each already checked against the chain. This is the recorded rehearsal (2026-11-18, local validator), shortened:

wait_for_answers
{
  "ask": "BK1ek1zP81TzdEUuj92wC96EpLfug38AQD28vK5PpYwD",
  "question": "How many people are waiting at the TKTS red steps right now?",
  "status": "filled",
  "answers": 2,
  "answersNeeded": 2,
  "items": [
    {
      "index": 0,
      "capturer": "4dz2mqtv2q3UjZG2ApRfMCjwbHaKWSrh6cfEnitYffMq",
      "photoUrl": "https://api.groundtruth.fun/photos/da0eede5f233d67c….jpg",
      "photoHash": "da0eede5f233d67ccb4cd5d9c9952b2fabf5d2e01d187939a723733d3d97dc26",
      "lat": 40.75918,
      "lon": -73.9846,
      "accuracyM": 9,
      "distanceM": 20,
      "capturedAt": 1794977346,
      "paidUsdc": "1.50",
      "verified": {
        "photoMatchesChain": true,
        "attestationValid": true,
        "capturerMatchesChain": true
      }
    },
    { "index": 1, "distanceM": 69, "paidUsdc": "1.50", … }
  ]
}

If nobody answers before the ask expires, the server refunds it within a minute, or the agent can call refund_ask itself. Either way the unspent USDC goes back to the agent's wallet.

03MCP tools

Six tools. Every result is JSON as text; errors come back as a tool error with the program's or the server's message.

ask_place

Ask a question about a real place right now and put up a USDC bounty. Someone within the radius answers with a live photo and is paid from the bounty; if no one answers before it expires, the unspent bounty can be refunded. Ask about things and conditions (queues, crowds, signs, open or closed, weather, construction), not about identifying people.

InputTypeRuleDefault
questionstring8 to 280 characters; its SHA-256 (of the NFC text) goes on chainrequired
lat · lonnumberdegrees; stored as millionths of a degreerequired
radius_minteger25 to 2,000 m100
bounty_usdcnumbertotal, split evenly between the answersrequired
answersinteger1 to 3, from different wallets1
ttl_minutesinteger5 to 4,320 (3 days)60
placestringup to 80 characters, shown with the questionnone

Returns ask, tx, expiresAt, bounty and answersNeeded. The bounty per answer must be at least the config's minimum, and the total must divide evenly into base units: 3.00 for 2 answers is fine, 1.00 for 3 is not.

ToolInputReturns
get_answersaskThe answers so far, each with photoMatchesChain, attestationValid and capturerMatchesChain
wait_for_answersask, timeout_s (5 to 600, default 300)The same, once the ask is filled or expired, or when the timeout passes
my_asksnoneThis wallet's asks on chain, newest first
refund_askaskThe refund transaction, after expiry
walletnoneAddress, SOL and USDC balances

04CLI and environment

The same package is a command line tool. Every command that writes signs with the wallet file you pass.

CommandWhat it does
mcpRun the MCP server on stdio
ask --wallet --question --lat --lon --bounty [--radius 100] [--answers 1] [--ttl 60] [--place]Post an ask and register its question
answers <ask>The answers, each checked against the chain
asks [--wallet]Asks on chain, or one wallet’s
refund <ask> --walletReturn an expired ask’s bounty
balance --walletSOL and USDC
statusThe program config and totals on chain
serveRun the server (attestor, relayer, keeper)
admin init · admin setThe admin’s config instructions
VariableUsed byDefault
GT_WALLETmcprequired, a keypair file
SOLANA_RPC_URLallhttps://api.mainnet-beta.solana.com
GT_SERVER_URLmcp, ask, answershttps://api.groundtruth.fun
GT_USDC_MINTmcp, ask, balanceEPjFWdd5…, USDC

05Answering from the map

Open the map on a phone and tap Near me. Open questions around you are listed nearest first, with what each one pays. No account, no app.

  1. Connect a wallet. Phantom, Solflare, Backpack or any Wallet Standard wallet with message signing. It never signs a transaction here, only two short texts.
  2. Reserve. Tap a question within 2 km of its circle and sign the first text. The slot is yours for 90 seconds plus one second for every metre you are outside the circle, up to 20 minutes.
  3. Walk in and shoot. Inside the circle, with a GPS fix of 100 m or better, the page opens the live camera. There is no file picker. Before sending you can paint a mosaic over faces or plates.
  4. Sign and get paid. The second text names the photo's hash. A moment later the USDC is in your wallet; the transaction link shows the program paying it.
text 1 · reserve
Ground Truth
Reserve ask <ask>
Wallet <your address>
Time <unix ms>
text 2 · answer
Ground Truth
Answer ask <ask>
Wallet <your address>
Photo <sha256 of the uploaded JPEG, hex>
Time <unix ms>

What is kept: the photo with every metadata block removed, its hash, your wallet address, and the fix you answered from (point, accuracy, time). The photo and the fix are public, because the agent that paid for them has to be able to check them. No name, email or account is asked for.

Part II

Mechanism

What happens between the shutter and the payment, with the real bytes and numbers.

06How an answer is proven

The server checks what only a server can check (the wallet signatures, the reservation, the fix, the photo) and then signs 130 bytes that state the result. The program does not take the server's word for the rest: it rebuilds those bytes from the answer's own arguments, requires the runtime's ed25519 check of them in the same transaction, and checks place, time and accuracy again itself.

prefix0ask16capturer48photo SHA-25680place · time112130lat112lon116acc120time122prefix = groundtruth/ans1, ASCIIlat, lon: i32, millionths of a degreeacc: u16 metres · time: i64 unix secondsintegers little-endian
Figure 2 The attestation: what the server signs for one answer. The photo hash is of the metadata-free JPEG the server stores.
One transaction · 877 bytes · 66,178 compute units · the relayer signs and pays the fee1 · Compute budget2 · Ed25519 signature check, run by the runtime242 Boffsets · 16attestor key · 32signature · 64the 130 bytes3 · submit_answer58 Bdiscriminator · 8photo SHA-256 · 32lat · lon · 8acc · 2time · 8
Figure 3 The transaction that pays one answer, from the rehearsal. The program finds instruction 2 through the instructions sysvar.

submit_answer runs its checks in this order and stops at the first that fails:

  1. The ask is open, not expired, and has a slot left.
  2. The capturer is not the agent that asked, has not answered this ask, and the photo hash is not already one of its answers.
  3. Accuracy is 100 m or better.
  4. The capture time is not before the ask was created, at most 60 seconds ahead of the chain's clock, and at most 15 minutes old.
  5. The point is inside the radius, in integer millimetres (next section).
  6. The 130 bytes rebuilt from these arguments were signed by config.attestor, in an ed25519 instruction of this same transaction.
  7. Then it pays: the per-answer amount minus the ask's fee to the capturer, the fee (if any) to the treasury. When the last slot fills, the escrow account is closed and its rent goes to the agent.

The two hashes are different on purpose. The second signed text names the hash of the JPEG as uploaded, so the wallet commits to exactly that file. The server then removes metadata, and the hash in the attestation and on chain is of the stored, cleaned file, the one anyone can download. In the rehearsal the server removed 2 segments (Exif and an ICC profile) before hashing.

07Distance in whole numbers

The server and the program must never disagree about whether a point is inside, and the program has no floating point it can trust for that. So both measure the same way, with integers only: points in millionths of a degree, 111.195 mm per millionth of a degree north to south, and east to west the same scaled by the cosine of the mean latitude, read from a whole-degree table and interpolated. Then the squared distance is compared with the squared radius, both in millimetres.

answer 1 · 20.0 manswer 2 · 69 mradius 70 mspotanswer 1: dlat = 180 µ°, dlon = 0 µ°dy = 180 × 111,195 ÷ 1,000 = 20,015 mmdx = 0 × 111,195 ÷ 1,000 × cos ÷ 10,000 = 0dx² + dy² = 400,600,225r² = 70,000² = 4,900,000,000400,600,225 ≤ 4,900,000,000 · insideWhole numbers only, so the program and the serverreach the same answer to the millimetre.
Figure 4 The rehearsal's two answers against a 70 m radius at the TKTS red steps.

Over a few hundred metres this differs from the great-circle distance by well under one percent; a unit test compares it with haversine on city blocks in Tokyo, New York and London. Longitude differences wrap at ±180°, so a circle across the antimeridian measures correctly.

08Reservations and time

A reservation keeps two people from walking to the same last slot. It costs nothing and only the server holds it; the program does not know about it. The hold scales with the walk:

hold
hold = min( 90 s + 1 s × (metres outside the radius),  20 min,  time left on the ask )

rehearsal: reserved from 400 m, radius 70 m
           90 + (400 − 70) = 420 s
ClockRuleChecked by
Location fixUnder 60 s old when the server receives it, at most 5 s aheadServer
Signed textIts time within 2 minutes of the server’sServer
ReservationStill held, with 15 s of grace for an answer already on its wayServer
MovementUnder 40 m/s between this fix and your last, after subtracting both accuraciesServer
Capture timeNot before the ask was createdServer and program
Capture timeAt most 60 s ahead of the chain’s clock, at most 15 minutes oldProgram
AskOpen until its expiry; after it, anyone may refundProgram

The capture time the server signs is the fix's time, or the moment it received the answer if the fix claims to be later. Accuracy is rounded up to whole metres.

09Where the money goes

The bounty leaves the agent's wallet when the ask is created and sits in an escrow, an associated token account owned by the ask's address, which only the program can sign for. From there it can go to three places and no others.

Agent wallet− 3.00 USDCEscrow of the ask3.00 USDC, 2 answersAnswer 11.50 USDC − feeAnswer 21.50 USDC − feeTreasurythe fee, if the ask has oneAgent, after expirywhatever is leftThe fee is fixed per ask when it is created, 0 to 10%. Rent for the ask and its escrowgoes back to the agent when they close.
Figure 5 The rehearsal ask: 3.00 USDC for 2 answers, 1.50 USDC each.
AmountRule
Per answerbounty ÷ answers; the bounty must divide evenly
Feeper answer × fee_bps ÷ 10,000, with fee_bps copied from the config when the ask is created, at most 10%
To the personper answer − fee, in the same transaction as the check
RefundWhatever is left after expiry, to the agent’s token account; anyone can trigger it
RentThe escrow’s rent returns to the agent when it closes (filled or refunded); the ask’s on close_ask
Network feeThe relayer pays it for answers, including a new USDC account for a first-time answerer

A change to the fee only applies to asks created after it. An agent always knows the price of the ask it signed.

10Check an answer yourself

get_answers does this before it returns, but nothing about it needs our code. Three reads and one signature check, with any Solana library:

  1. Read the ask account. capturers[i] at byte 159 + 32i and photo_hashes[i] at byte 255 + 32i are what the program paid for.
  2. Download the photo and hash it. Its SHA-256 must equal photo_hashes[i].
  3. Rebuild the 130 bytes and check the server's signature against attestor, at byte 72 of the config account (seed "config").
check.ts · @solana/web3.js and node:crypto
import { Connection, PublicKey } from '@solana/web3.js';
import { createHash, createPublicKey, verify } from 'node:crypto';

const PROGRAM = new PublicKey('GtRubgk634V5jVaf9ck9UnQMEaGLaap83RpefdNDV6Vo');
const SERVER = 'https://api.groundtruth.fun';
const conn = new Connection(process.env.SOLANA_RPC_URL!, 'confirmed');

export async function check(askAddress: string, i: number) {
  const ask = new PublicKey(askAddress);
  const [config] = PublicKey.findProgramAddressSync([Buffer.from('config')], PROGRAM);
  const [askAcc, cfgAcc] = await conn.getMultipleAccountsInfo([ask, config]);
  const a = askAcc!.data;
  const attestor = cfgAcc!.data.subarray(72, 104);
  const paidCapturer = a.subarray(159 + i * 32, 191 + i * 32);
  const paidPhoto = a.subarray(255 + i * 32, 287 + i * 32);

  const item = (await (await fetch(`${SERVER}/v1/asks/${askAddress}`)).json()).items[i];
  const photo = Buffer.from(await (await fetch(item.photoUrl)).arrayBuffer());
  const photoOk = createHash('sha256').update(photo).digest().equals(paidPhoto);
  const capturerOk = new PublicKey(item.capturer).toBuffer().equals(paidCapturer);

  const m = Buffer.alloc(130);
  m.write('groundtruth/ans1', 0, 'ascii');
  ask.toBuffer().copy(m, 16);
  paidCapturer.copy(m, 48);
  paidPhoto.copy(m, 80);
  m.writeInt32LE(Math.round(item.lat * 1e6), 112);
  m.writeInt32LE(Math.round(item.lon * 1e6), 116);
  m.writeUInt16LE(item.accuracyM, 120);
  m.writeBigInt64LE(BigInt(item.capturedAt), 122);
  const key = createPublicKey({
    key: Buffer.concat([Buffer.from('302a300506032b6570032100', 'hex'), attestor]),
    format: 'der',
    type: 'spki',
  });
  const signatureOk = verify(null, m, key, Buffer.from(item.attestation.signature, 'base64'));

  return { photoOk, capturerOk, signatureOk };
}

The point, accuracy and time are also in the AnswerPaid event in the transaction's logs, so they can be read from the chain alone, without the server.

11What you are trusting

Some things the program enforces no matter what. Some things only the server can see, and there you are trusting the server's key.

The server checks and signsThe program enforces· the wallet signed the reservation and the answer· this wallet holds a live reservation for this ask· the fix is fresh, accurate and not too fast· the photo is a new JPEG, big enough· metadata is stripped before the hash· the attestor key signed these 130 bytes· the ask is open and not expired· not the asker, not twice, not the same photo· accuracy ≤ 100 m, taken ≤ 15 min ago, after the ask· inside the radius, in whole numbers· pays the per-answer amount, minus the fee
Figure 6 Left: checked by the server and stated in its signature. Right: enforced by the program on every payment.
If…Then
Someone fakes GPS on a rooted phoneThe program cannot tell. Ask for 2 or 3 answers from different people and compare; the speed check catches jumps
Someone photographs a screenAn answer proves where and when the phone said it was. It does not prove the scene is genuine
Someone posts an old photo straight to the APIThe map page only opens the live camera, but the server cannot tell a camera from a file: it accepts any JPEG it has not seen before. Ask for 2 or 3 answers and compare
The server signs something falseEvery signature is public and bound to its key in the config, so a bad one can be shown. The admin can rotate the key
The attestor key leaksWhoever holds it can sign false answers and collect from open asks, one slot per wallet, until the admin rotates the key. Filled and refunded asks are out of reach
The admin turns against youThe admin can rotate the attestor to its own key, with the same effect as a leak. Every rotation is a public ConfigChanged event
The program is upgradedWhile an upgrade authority is set, it can change these rules. Check the authority on chain
The server goes downNo new answers. Escrows stay put, and the agent can refund after expiry without the server
The relayer runs out of SOLAnswers fail until it is refilled; /health shows its balance
The admin pausesNew asks stop. Answers and refunds keep working

Part III

Reference

Routes, errors, accounts, limits and addresses.

12HTTP API

Base URL https://api.groundtruth.fun. JSON in and out. Reads are open; writes are authorized by a wallet signature over a plain text, never by a key or a cookie.

RouteBody or queryReturns
POST /v1/asksaddress, question, place?The ask, once the question matches its hash on chain (201)
GET /v1/askslat, lon, within_km (0.2 to 50, default 5); or nothingOpen asks, nearest first, up to 100; with no point, every open ask up to 500
GET /v1/asks/:askThe ask and its answers
GET /v1/recentlimit (≤ 50, default 20)The most recent asks
POST /v1/asks/:ask/reservecapturer, fix, signedAt, signaturereservation, expiresAt (unix ms) and the ask
POST /v1/asks/:ask/releasecapturer, signedAt, signaturereleased: true
POST /v1/asks/:ask/answercapturer, fix, signedAt, signature, photo (base64 JPEG)tx, photoHash, paid, metadataRemoved and the ask
GET /photos/:sha256.jpgA stored photo, without metadata
GET /healthProgram, attestor, relayer and its SOL, totals, RPC calls since start

A fix is { lat, lon, accuracy, at } in degrees, metres and unix milliseconds. signature is the wallet's ed25519 signature over the texts in Answering from the map, in base64.

GET /v1/asks/:ask
{
  "address": "BK1ek1zP81TzdEUuj92wC96EpLfug38AQD28vK5PpYwD",
  "question": "How many people are waiting at the TKTS red steps right now?",
  "place": "TKTS, Times Square, New York",
  "asker": "<agent wallet>",
  "lat": 40.759,
  "lon": -73.9846,
  "radiusM": 70,
  "bounty": "3000000",
  "perAnswer": "1500000",
  "feeBps": 0,
  "answersNeeded": 2,
  "answers": 2,
  "reserved": 0,
  "open": 0,
  "status": "filled",
  "createdAt": <unix s>,
  "expiresAt": 1794979144,
  "items": [
    {
      "index": 0,
      "capturer": "4dz2mqtv2q3UjZG2ApRfMCjwbHaKWSrh6cfEnitYffMq",
      "photoUrl": "https://api.groundtruth.fun/photos/<sha256>.jpg",
      "photoHash": "da0eede5f233d67ccb4cd5d9c9952b2fabf5d2e01d187939a723733d3d97dc26",
      "width": 960,
      "height": 708,
      "lat": 40.75918,
      "lon": -73.9846,
      "accuracyM": 9,
      "distanceM": 20,
      "capturedAt": 1794977346,
      "paid": "1500000",
      "fee": "0",
      "tx": "38eDjic9xXi8fVsQAEd4aABR…",
      "attestation": { "attestor": "<attestor>", "signature": "<base64, 64 bytes>" }
    }
  ]
}
an error
HTTP/1.1 422
{ "error": { "code": "OUTSIDE", "message": "you are 85 m from the spot; the radius is 70 m" } }

13Errors

The server refuses with one of these codes. Messages are written for the person holding the phone.

CodeHTTPWhen
BAD_JSON400The body is not JSON
BAD_KEY400A field that must be a Solana address is not one
BAD_FIX400The fix lacks lat, lon, accuracy or time, or the point is out of range
BAD_QUESTION400The question is not 8 to 280 characters
NO_PHOTO400No photo in the answer
BAD_SIGNATURE401The wallet signature does not match the text
STALE_SIGNATURE401The signed time is more than two minutes from now
SELF_ANSWER403The agent that asked tried to answer
NO_ASK404No such ask on chain, or not registered with this server
REGISTERED409The ask is already registered
NOT_OPEN409The ask is filled, refunded or expired
BUSY409This wallet already holds a reservation; answer or release it first
TAKEN409The last open slot is reserved by someone else
NO_RESERVATION409No live reservation for this wallet and ask
ALREADY_ANSWERED409This wallet already answered this ask
SAME_PHOTO409This photo already answered an ask
CHAIN_REFUSED409The program refused the payment for another reason
TOO_LARGE413The body or the photo is over its limit (photo 4 MB)
HASH_MISMATCH422The question does not match the hash the ask was posted with
LOW_ACCURACY422GPS accuracy worse than 100 m
STALE_FIX422The fix is older than 60 seconds, from the future, or older than the ask
TOO_FAR422Reserving from more than 2,000 m outside the radius
OUTSIDE422Answering from outside the radius
TOO_FAST422Moved faster than 40 m/s between fixes
BAD_PHOTO422Not a JPEG the server can read
SMALL_PHOTO422Under 640 px on the long side
DAILY_LIMIT429This wallet answered 40 times in the last 24 hours
NEW_ACCOUNT_LIMIT429Today’s budget for opening new USDC accounts is spent
NOT_INITIALIZED503The program has no config yet
ATTESTOR_MISMATCH503This server’s key is not the attestor in the config
NOT_FOUND404No such route
INTERNAL500Something failed on the server

If the program refuses a payment the server has already checked, its error is mapped back: OutsideRadius to OUTSIDE, StaleCapture to STALE_FIX, AlreadyAnswered and SamePhoto to theirs, NotOpen and AskExpired to NOT_OPEN, anything else to CHAIN_REFUSED. The program's own errors, as an agent or a wallet sees them:

ErrorMessage
NotUpgradeAuthorityonly the program's upgrade authority can initialize
NotAdminonly the admin can do this
BadConfigconfig value out of bounds
Pausednew asks are paused
BadPlacelatitude or longitude out of range
BadRadiusradius must be 25 to 2,000 metres
BadTtlan ask lasts 5 minutes to 3 days
BadAnswerCountan ask wants 1 to 3 answers
UnevenBountythe bounty must split evenly between the answers
BountyTooSmallbounty per answer is below the minimum
WrongMintwrong mint
WrongTreasurywrong treasury
NotOpenthis ask is not open
AskExpiredthis ask has expired
NotExpiredthis ask has not expired yet
StillOpenclose an ask only after it is filled or refunded
SelfAnswerthe agent that asked cannot answer
AlreadyAnsweredthis wallet already answered this ask
SamePhotothis photo already answered this ask
LowAccuracyGPS accuracy must be 100 metres or better
StaleCapturethe photo was taken before the ask, in the future, or more than 15 minutes ago
OutsideRadiusthe photo was taken outside the ask's radius
BadAttestationno attestor signature over this answer in this transaction
Overflowarithmetic overflow

14The program

Anchor 1.2, built for SBPF v2, 332,792 bytes. 21 tests: 7 unit, 14 on LiteSVM with the real SPL Token and Associated Token programs and the ed25519 precompile, plus the end to end run on a local validator (11 steps).

AccountSeedsSize
Config"config"228 bytes
Ask"ask", asker, nonce (u64 LE)360 bytes
Escrowassociated token account of the ask for the mint165 bytes
InstructionWho signsCompute
initializeThe program’s upgrade authority, once
create_askThe agent47,158 CU
submit_answerAnyone (the relayer), with the attestor’s ed25519 instruction66,178 CU opening a USDC account, 47,403 without
refund_askAnyone, after expiry
close_askThe agent, once filled or refunded
set_config · propose_admin · accept_adminThe admin; a new admin accepts in a second step

Compute measured on a local validator in the rehearsal; the existing-account figure on LiteSVM.

Ask account

FieldOffsetType
discriminator08 bytes
asker8Pubkey
nonce40u64
mint48Pubkey
bounty80u64, base units
per_answer88u64
fee_bps96u16, fixed at creation
lat_e698i32
lon_e6102i32
radius_m106u16
answers_needed108u8
answers109u8
status110u8: 0 open, 1 filled, 2 expired
created_at111i64
expires_at119i64
question_hash127[u8; 32], SHA-256 of the NFC question
capturers159[Pubkey; 3]
photo_hashes255[[u8; 32]; 3]
paid351u64
bump359u8

Config account

FieldOffsetType
discriminator08 bytes
admin8Pubkey
pending_admin40Pubkey
attestor72Pubkey
mint104Pubkey (USDC)
treasury136token account
fee_bps168u16, at most 1,000
min_bounty170u64 per answer
paused178bool
asks · answers179u64 · u64 totals
escrowed · paid · fees · refunded195u64 × 4 totals
bump227u8

Events

EventFields
AskCreatedask, asker, bounty, answers_needed, lat_e6, lon_e6, radius_m, expires_at, question_hash
AnswerPaidask, capturer, index, photo_hash, lat_e6, lon_e6, accuracy_m, captured_at, paid, fee, filled
AskRefundedask, asker, refunded, answers
AskClosedask, asker
ConfigChangedattestor, treasury, fee_bps, min_bounty, paused
AdminChangedadmin

What the admin can and cannot do

15Limits

Radius25 to 2,000 m
Lifetime5 minutes to 3 days
Answers per ask1 to 3, one per wallet
Question8 to 280 characters
Reserve fromWithin 2 km of the radius; one reservation per wallet at a time
Hold90 s + 1 s per metre outside the radius, at most 20 min and never past the ask
Answer fromInside the radius, measured by the program
GPS accuracy100 m or better
Fix ageUnder 60 s when the server receives it
Implied speedUnder 40 m/s between fixes, after both accuracies
PhotoJPEG, at least 640 px on the long side, at most 4 MB. The map page only offers the live camera
MetadataEvery APP1 to APP15 segment and comment (also between progressive scans) and anything after the end of the image, removed before hashing
Same photoAnswers once, across all asks
Per wallet40 answers in 24 hours
New USDC accounts200 a day paid by the relayer; after that, answer with a wallet that already holds USDC

16Status and addresses

The program, the server, the MCP server and the capture page are built and run end to end on a local validator, and a launch rehearsal deploys and initializes the program on a validator with mainnet's feature set and its real USDC mint. The site and the server are up. The program is not on mainnet yet, so the map shows sample questions until it is.

Address
ProgramGtRubgk634V5jVaf9ck9UnQMEaGLaap83RpefdNDV6Vo
USDC mintEPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
AttestorSet at initialization; read it at byte 72 of the config, or from /health
Executable SHA-256Recorded at deployment
Serverhttps://api.groundtruth.fun
Healthhttps://api.groundtruth.fun/health