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.
| Part | Who runs it | What it holds |
|---|---|---|
| Agent | You, with the MCP server or the CLI | A Solana wallet with USDC for bounties and a little SOL for fees and rent |
| Person nearby | Anyone with a phone and a Solana wallet | Nothing up front. The relayer pays their network fee and opens their USDC account |
| Server | Ground Truth | The attestor key, which signs checked captures, and the relayer, which pays network fees |
| Program | Solana | Every 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.
- 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. - 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.
- 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.
{
"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 mcp add groundtruth \
-e GT_WALLET=$HOME/.config/solana/agent.json \
-e SOLANA_RPC_URL=https://your-solana-rpc \
-- npx -y groundtruth mcpnode 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:
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"
}{
"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:
{
"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.
| Input | Type | Rule | Default |
|---|---|---|---|
| question | string | 8 to 280 characters; its SHA-256 (of the NFC text) goes on chain | required |
| lat · lon | number | degrees; stored as millionths of a degree | required |
| radius_m | integer | 25 to 2,000 m | 100 |
| bounty_usdc | number | total, split evenly between the answers | required |
| answers | integer | 1 to 3, from different wallets | 1 |
| ttl_minutes | integer | 5 to 4,320 (3 days) | 60 |
| place | string | up to 80 characters, shown with the question | none |
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.
| Tool | Input | Returns |
|---|---|---|
| get_answers | ask | The answers so far, each with photoMatchesChain, attestationValid and capturerMatchesChain |
| wait_for_answers | ask, timeout_s (5 to 600, default 300) | The same, once the ask is filled or expired, or when the timeout passes |
| my_asks | none | This wallet's asks on chain, newest first |
| refund_ask | ask | The refund transaction, after expiry |
| wallet | none | Address, 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.
| Command | What it does |
|---|---|
| mcp | Run 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> --wallet | Return an expired ask’s bounty |
| balance --wallet | SOL and USDC |
| status | The program config and totals on chain |
| serve | Run the server (attestor, relayer, keeper) |
| admin init · admin set | The admin’s config instructions |
| Variable | Used by | Default |
|---|---|---|
| GT_WALLET | mcp | required, a keypair file |
| SOLANA_RPC_URL | all | https://api.mainnet-beta.solana.com |
| GT_SERVER_URL | mcp, ask, answers | https://api.groundtruth.fun |
| GT_USDC_MINT | mcp, ask, balance | EPjFWdd5…, 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.
- Connect a wallet. Phantom, Solflare, Backpack or any Wallet Standard wallet with message signing. It never signs a transaction here, only two short texts.
- 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.
- 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.
- 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.
Ground Truth
Reserve ask <ask>
Wallet <your address>
Time <unix ms>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.
submit_answer runs its checks in this order and stops at the first that fails:
- The ask is open, not expired, and has a slot left.
- The capturer is not the agent that asked, has not answered this ask, and the photo hash is not already one of its answers.
- Accuracy is 100 m or better.
- 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.
- The point is inside the radius, in integer millimetres (next section).
- The 130 bytes rebuilt from these arguments were signed by
config.attestor, in an ed25519 instruction of this same transaction. - 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.
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 = 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| Clock | Rule | Checked by |
|---|---|---|
| Location fix | Under 60 s old when the server receives it, at most 5 s ahead | Server |
| Signed text | Its time within 2 minutes of the server’s | Server |
| Reservation | Still held, with 15 s of grace for an answer already on its way | Server |
| Movement | Under 40 m/s between this fix and your last, after subtracting both accuracies | Server |
| Capture time | Not before the ask was created | Server and program |
| Capture time | At most 60 s ahead of the chain’s clock, at most 15 minutes old | Program |
| Ask | Open until its expiry; after it, anyone may refund | Program |
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.
| Amount | Rule |
|---|---|
| Per answer | bounty ÷ answers; the bounty must divide evenly |
| Fee | per answer × fee_bps ÷ 10,000, with fee_bps copied from the config when the ask is created, at most 10% |
| To the person | per answer − fee, in the same transaction as the check |
| Refund | Whatever is left after expiry, to the agent’s token account; anyone can trigger it |
| Rent | The escrow’s rent returns to the agent when it closes (filled or refunded); the ask’s on close_ask |
| Network fee | The 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:
- Read the ask account.
capturers[i]at byte 159 + 32i andphoto_hashes[i]at byte 255 + 32i are what the program paid for. - Download the photo and hash it. Its SHA-256 must equal
photo_hashes[i]. - Rebuild the 130 bytes and check the server's signature against
attestor, at byte 72 of the config account (seed"config").
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.
| If… | Then |
|---|---|
| Someone fakes GPS on a rooted phone | The program cannot tell. Ask for 2 or 3 answers from different people and compare; the speed check catches jumps |
| Someone photographs a screen | An 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 API | The 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 false | Every 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 leaks | Whoever 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 you | The 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 upgraded | While an upgrade authority is set, it can change these rules. Check the authority on chain |
| The server goes down | No new answers. Escrows stay put, and the agent can refund after expiry without the server |
| The relayer runs out of SOL | Answers fail until it is refilled; /health shows its balance |
| The admin pauses | New 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.
| Route | Body or query | Returns |
|---|---|---|
| POST /v1/asks | address, question, place? | The ask, once the question matches its hash on chain (201) |
| GET /v1/asks | lat, lon, within_km (0.2 to 50, default 5); or nothing | Open asks, nearest first, up to 100; with no point, every open ask up to 500 |
| GET /v1/asks/:ask | The ask and its answers | |
| GET /v1/recent | limit (≤ 50, default 20) | The most recent asks |
| POST /v1/asks/:ask/reserve | capturer, fix, signedAt, signature | reservation, expiresAt (unix ms) and the ask |
| POST /v1/asks/:ask/release | capturer, signedAt, signature | released: true |
| POST /v1/asks/:ask/answer | capturer, fix, signedAt, signature, photo (base64 JPEG) | tx, photoHash, paid, metadataRemoved and the ask |
| GET /photos/:sha256.jpg | A stored photo, without metadata | |
| GET /health | Program, 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.
{
"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>" }
}
]
}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.
| Code | HTTP | When |
|---|---|---|
| BAD_JSON | 400 | The body is not JSON |
| BAD_KEY | 400 | A field that must be a Solana address is not one |
| BAD_FIX | 400 | The fix lacks lat, lon, accuracy or time, or the point is out of range |
| BAD_QUESTION | 400 | The question is not 8 to 280 characters |
| NO_PHOTO | 400 | No photo in the answer |
| BAD_SIGNATURE | 401 | The wallet signature does not match the text |
| STALE_SIGNATURE | 401 | The signed time is more than two minutes from now |
| SELF_ANSWER | 403 | The agent that asked tried to answer |
| NO_ASK | 404 | No such ask on chain, or not registered with this server |
| REGISTERED | 409 | The ask is already registered |
| NOT_OPEN | 409 | The ask is filled, refunded or expired |
| BUSY | 409 | This wallet already holds a reservation; answer or release it first |
| TAKEN | 409 | The last open slot is reserved by someone else |
| NO_RESERVATION | 409 | No live reservation for this wallet and ask |
| ALREADY_ANSWERED | 409 | This wallet already answered this ask |
| SAME_PHOTO | 409 | This photo already answered an ask |
| CHAIN_REFUSED | 409 | The program refused the payment for another reason |
| TOO_LARGE | 413 | The body or the photo is over its limit (photo 4 MB) |
| HASH_MISMATCH | 422 | The question does not match the hash the ask was posted with |
| LOW_ACCURACY | 422 | GPS accuracy worse than 100 m |
| STALE_FIX | 422 | The fix is older than 60 seconds, from the future, or older than the ask |
| TOO_FAR | 422 | Reserving from more than 2,000 m outside the radius |
| OUTSIDE | 422 | Answering from outside the radius |
| TOO_FAST | 422 | Moved faster than 40 m/s between fixes |
| BAD_PHOTO | 422 | Not a JPEG the server can read |
| SMALL_PHOTO | 422 | Under 640 px on the long side |
| DAILY_LIMIT | 429 | This wallet answered 40 times in the last 24 hours |
| NEW_ACCOUNT_LIMIT | 429 | Today’s budget for opening new USDC accounts is spent |
| NOT_INITIALIZED | 503 | The program has no config yet |
| ATTESTOR_MISMATCH | 503 | This server’s key is not the attestor in the config |
| NOT_FOUND | 404 | No such route |
| INTERNAL | 500 | Something 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:
| Error | Message |
|---|---|
| NotUpgradeAuthority | only the program's upgrade authority can initialize |
| NotAdmin | only the admin can do this |
| BadConfig | config value out of bounds |
| Paused | new asks are paused |
| BadPlace | latitude or longitude out of range |
| BadRadius | radius must be 25 to 2,000 metres |
| BadTtl | an ask lasts 5 minutes to 3 days |
| BadAnswerCount | an ask wants 1 to 3 answers |
| UnevenBounty | the bounty must split evenly between the answers |
| BountyTooSmall | bounty per answer is below the minimum |
| WrongMint | wrong mint |
| WrongTreasury | wrong treasury |
| NotOpen | this ask is not open |
| AskExpired | this ask has expired |
| NotExpired | this ask has not expired yet |
| StillOpen | close an ask only after it is filled or refunded |
| SelfAnswer | the agent that asked cannot answer |
| AlreadyAnswered | this wallet already answered this ask |
| SamePhoto | this photo already answered this ask |
| LowAccuracy | GPS accuracy must be 100 metres or better |
| StaleCapture | the photo was taken before the ask, in the future, or more than 15 minutes ago |
| OutsideRadius | the photo was taken outside the ask's radius |
| BadAttestation | no attestor signature over this answer in this transaction |
| Overflow | arithmetic 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).
| Account | Seeds | Size |
|---|---|---|
| Config | "config" | 228 bytes |
| Ask | "ask", asker, nonce (u64 LE) | 360 bytes |
| Escrow | associated token account of the ask for the mint | 165 bytes |
| Instruction | Who signs | Compute |
|---|---|---|
| initialize | The program’s upgrade authority, once | |
| create_ask | The agent | 47,158 CU |
| submit_answer | Anyone (the relayer), with the attestor’s ed25519 instruction | 66,178 CU opening a USDC account, 47,403 without |
| refund_ask | Anyone, after expiry | |
| close_ask | The agent, once filled or refunded | |
| set_config · propose_admin · accept_admin | The 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
| Field | Offset | Type |
|---|---|---|
| discriminator | 0 | 8 bytes |
| asker | 8 | Pubkey |
| nonce | 40 | u64 |
| mint | 48 | Pubkey |
| bounty | 80 | u64, base units |
| per_answer | 88 | u64 |
| fee_bps | 96 | u16, fixed at creation |
| lat_e6 | 98 | i32 |
| lon_e6 | 102 | i32 |
| radius_m | 106 | u16 |
| answers_needed | 108 | u8 |
| answers | 109 | u8 |
| status | 110 | u8: 0 open, 1 filled, 2 expired |
| created_at | 111 | i64 |
| expires_at | 119 | i64 |
| question_hash | 127 | [u8; 32], SHA-256 of the NFC question |
| capturers | 159 | [Pubkey; 3] |
| photo_hashes | 255 | [[u8; 32]; 3] |
| paid | 351 | u64 |
| bump | 359 | u8 |
Config account
| Field | Offset | Type |
|---|---|---|
| discriminator | 0 | 8 bytes |
| admin | 8 | Pubkey |
| pending_admin | 40 | Pubkey |
| attestor | 72 | Pubkey |
| mint | 104 | Pubkey (USDC) |
| treasury | 136 | token account |
| fee_bps | 168 | u16, at most 1,000 |
| min_bounty | 170 | u64 per answer |
| paused | 178 | bool |
| asks · answers | 179 | u64 · u64 totals |
| escrowed · paid · fees · refunded | 195 | u64 × 4 totals |
| bump | 227 | u8 |
Events
| Event | Fields |
|---|---|
| AskCreated | ask, asker, bounty, answers_needed, lat_e6, lon_e6, radius_m, expires_at, question_hash |
| AnswerPaid | ask, capturer, index, photo_hash, lat_e6, lon_e6, accuracy_m, captured_at, paid, fee, filled |
| AskRefunded | ask, asker, refunded, answers |
| AskClosed | ask, asker |
| ConfigChanged | attestor, treasury, fee_bps, min_bounty, paused |
| AdminChanged | admin |
What the admin can and cannot do
- Can rotate the attestor key, set the smallest bounty per answer (at most 100 USDC), set a fee of at most 10% to a treasury, and pause new asks.
- Cannot send an escrow anywhere except to a capturer attested by the current attestor key, to the treasury as that ask's own fee, or back to the agent that posted it.
- Cannot change the fee of an ask already created, or stop answers and refunds by pausing.
15Limits
| Radius | 25 to 2,000 m |
| Lifetime | 5 minutes to 3 days |
| Answers per ask | 1 to 3, one per wallet |
| Question | 8 to 280 characters |
| Reserve from | Within 2 km of the radius; one reservation per wallet at a time |
| Hold | 90 s + 1 s per metre outside the radius, at most 20 min and never past the ask |
| Answer from | Inside the radius, measured by the program |
| GPS accuracy | 100 m or better |
| Fix age | Under 60 s when the server receives it |
| Implied speed | Under 40 m/s between fixes, after both accuracies |
| Photo | JPEG, at least 640 px on the long side, at most 4 MB. The map page only offers the live camera |
| Metadata | Every APP1 to APP15 segment and comment (also between progressive scans) and anything after the end of the image, removed before hashing |
| Same photo | Answers once, across all asks |
| Per wallet | 40 answers in 24 hours |
| New USDC accounts | 200 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 | |
|---|---|
| Program | GtRubgk634V5jVaf9ck9UnQMEaGLaap83RpefdNDV6Vo |
| USDC mint | EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v |
| Attestor | Set at initialization; read it at byte 72 of the config, or from /health |
| Executable SHA-256 | Recorded at deployment |
| Server | https://api.groundtruth.fun |
| Health | https://api.groundtruth.fun/health |