Bounties

Six routes read and act on bounties posted against sealed models through the bounty program (bountyProgramId in GET /v1/config, built on voynich-cpi). On the site, /bounties uses these routes directly.

A bounty is posted in one transaction and won in a single drawer signature: draw registers bounty::on_receipt as a Voynich settlement callback, so settle_call verifies the settled Receipt and pays the reward to the drawer inside the same transaction.

StepRoute
Post a bounty reward in escrowPOST /v1/bounties/build, then POST /v1/transactions/submit
Draw, settle and pay in one signaturePOST /v1/bounties/{address}/draw/build, submit, then send the encrypted input to POST /v1/calls/{id}/input with addresses.call
Collect a pre-callback attempt manuallyPOST /v1/bounties/{address}/collect/build, then submit
Cancel an open bounty as its creatorPOST /v1/bounties/{address}/cancel/build, then submit

In every path, {address} is the Bounty account's address. The errors every route shares are in Overview.

Bounty#

FieldMeaning
addressaddressrequired

The Bounty PDA account.

creatoraddressrequired

The wallet that posted and funded the bounty.

noncedecimal stringrequired

The unsigned 64-bit nonce that derives the Bounty PDA with creator.

modeladdressrequired

The sealed Model account that classifies attempts.

modelNamestring or nullrequired

The model's name, when indexed.

targetLabelstring, 1 to 32 bytesrequired

The label the model's verified open answer must match to win the bounty.

rewardMoneyrequired

The reward held in escrow, as a Money.

statusstringrequired

open: taking draw attempts. claimed: paid out to winner. cancelled: refunded to creator.

winneraddress or nullrequired

The drawer paid when status is claimed.

winningCalladdress or nullrequired

The Call account that won the bounty.

winningReceiptaddress or nullrequired

The Receipt account verified by on_receipt (or collect for legacy attempts).

createdSlotslotrequired

The slot the bounty was posted in.

claimedSlotslot or nullrequired

The slot the bounty was claimed in, or null.

attemptsdecimal stringrequired

Number of draw attempts opened against this bounty.

BountyAttempt#

FieldMeaning
addressaddressrequired

The Attempt PDA account, derived from bounty and call.

bountyaddressrequired

The Bounty account.

draweraddressrequired

The wallet that paid the model's call price and receives the reward if the label matches.

calladdressrequired

The Voynich Call account opened via CPI by the bounty program's caller PDA.

createdSlotslotrequired

The slot the attempt opened in.

refundedbooleanrequired

true if an expired attempt call was refunded.

GET /v1/bounties#

Lists bounties, one page at a time.

FieldMeaning
statusstring

Filter by open, claimed or cancelled. All statuses when omitted.

modeladdress or name

Filter to bounties targeting one model.

cursorstring
limitinteger, 1 to 100

24 when omitted.

Returns a page whose items are Bounty objects.

GET /v1/bounties/{address}#

Reads one bounty and its recorded attempts, latest attempt first.

FieldMeaning
bountyBountyrequired

The Bounty.

attemptsarray of BountyAttemptrequired

Every BountyAttempt recorded for this bounty.

CodeWhen
VALIDATION_ERROR{address} is not an address.
BOUNTY_NOT_FOUNDNo bounty has this address.

POST /v1/bounties/build#

Builds post: creates a Bounty PDA and moves reward (SOL or any SPL Token mint) into the bounty's escrow.

HTTP
POST /v1/bounties/build
Content-Type: application/json

{
  "wallet": "<creator address>",
  "model": "sketch-32",
  "targetLabel": "star",
  "reward": { "amount": "20000000", "mint": null, "decimals": 9, "symbol": "SOL" },
  "nonce": "<optional unsigned 64-bit integer>"
}
FieldMeaning
walletaddressrequired

The creator wallet. Pays rent, the transaction fee and the escrowed reward.

modeladdress or namerequired

The target model (such as sketch-32).

targetLabelstring, 1 to 32 bytesrequired

The label that wins the bounty.

rewardMoneyrequired

The reward amount and mint (mint: null for SOL).

noncedecimal string, unsigned 64-bit

A nonce unused by wallet. Drawn randomly when omitted.

Returns a Build with action: "post_bounty" and addresses: { model, bounty }.

CodeWhen
PROGRAM_UNAVAILABLEThe bounty program is not configured on this API. Retryable.
MODEL_NOT_FOUNDNo model has this name or address.
INSUFFICIENT_FUNDSwallet holds less than the reward, rent and fee.
SIMULATION_FAILEDRefused by the bounty program in simulation.

POST /v1/bounties/{address}/draw/build#

Builds draw: transfers the model's call price from the drawer to the bounty's caller PDA, creates the drawer's reward associated token account idempotently for SPL bounties, invokes voynich_cpi::open_call_with_callback in open answer mode with bounty::on_receipt as the settlement callback, and records an Attempt PDA.

HTTP
POST /v1/bounties/<bounty address>/draw/build
Content-Type: application/json

{
  "wallet": "<drawer address>",
  "enclave": "<enclave address>",
  "inputHash": "<sha-256 of the input envelope, 64 hex characters>",
  "nonce": "<optional unsigned 64-bit integer>"
}
FieldMeaning
walletaddressrequired

The drawer. Pays the model's call price, rent and transaction fee, and receives the bounty if the settled answer matches targetLabel.

enclaveaddressrequired

The live, reachable Enclave account holding a grant for the bounty's model.

inputHashhashrequired

SHA-256 of the encrypted input envelope sent next to POST /v1/calls/{id}/input.

noncedecimal string, unsigned 64-bit

Call nonce for the bounty's caller PDA. Drawn randomly when omitted.

Returns a Build with action: "draw_bounty" and addresses: { model, bounty, attempt, call }.

CodeWhen
PROGRAM_UNAVAILABLEThe bounty program is not configured on this API. Retryable.
BOUNTY_NOT_FOUNDNo bounty has this address.
BOUNTY_NOT_OPENThe bounty is already claimed or cancelled.
MODEL_NOT_FOUND, ENCLAVE_NOT_FOUND, MODEL_NOT_LIVE, GRANT_REQUIRED, ENCLAVE_EXPIRED, MEASUREMENT_NOT_ALLOWEDAs on POST /v1/calls/build.
INSUFFICIENT_FUNDSwallet holds less than the model's call price, rent and fee.

Next: sign and submit the Build, send the encrypted input envelope to POST /v1/calls/{id}/input using addresses.call, and wait for settlement. When the settled label matches targetLabel, settle_call invokes bounty::on_receipt and pays the reward to wallet in the same transaction. Poll GET /v1/bounties/{address} to observe status: "claimed" and winningCall.

POST /v1/bounties/{address}/collect/build#

Builds collect: invokes voynich_cpi::read_receipt on chain to verify the settled Receipt for call and pays the bounty reward to the attempt's drawer when the on-chain open answer's label matches targetLabel. Attempts opened with draw settle and pay automatically via on_receipt; collect remains available for pre-callback attempts.

HTTP
POST /v1/bounties/<bounty address>/collect/build
Content-Type: application/json

{
  "wallet": "<signer address>",
  "call": "<call address from draw>"
}
FieldMeaning
walletaddressrequired

The signer paying the transaction fee (and any missing SPL token account rent for the winner). Any wallet may submit collect; the reward always lands in the attempt's drawer.

calladdressrequired

The Call account opened by draw.

Returns a Build with action: "collect_bounty" and addresses: { model, bounty, attempt, call }.

CodeWhen
PROGRAM_UNAVAILABLEThe bounty program is not configured on this API. Retryable.
BOUNTY_NOT_FOUNDNo bounty has this address.
BOUNTY_NOT_OPENThe bounty is already claimed or cancelled.
CALL_NOT_FOUNDNo bounty attempt exists for {address} and call.
PROGRAM_REFUSEDThe Receipt does not match targetLabel (LabelMismatch) or is not a valid open Receipt for this attempt.

POST /v1/bounties/{address}/cancel/build#

Builds cancel: refunds an open bounty's full escrow back to its creator.

HTTP
POST /v1/bounties/<bounty address>/cancel/build
Content-Type: application/json

{
  "wallet": "<creator address>"
}
FieldMeaning
walletaddressrequired

The bounty's creator. Must match the creator recorded in the Bounty account.

Returns a Build with action: "cancel_bounty" and addresses: { model, bounty }.

CodeWhen
PROGRAM_UNAVAILABLEThe bounty program is not configured on this API. Retryable.
BOUNTY_NOT_FOUNDNo bounty has this address.
BOUNTY_NOT_OPENThe bounty is already claimed or cancelled.
SIMULATION_FAILEDwallet is not the bounty's creator.