Skip to content

hosted-base-usdc-beta-runbook.md

Latest commit

 

History

History
346 lines (273 loc) · 13.4 KB

hosted-base-usdc-beta-runbook.md

File metadata and controls

346 lines (273 loc) · 13.4 KB
Raw

Hosted Low-Value Base USDC Beta Runbook

Warning

Historical V1 material only. The operator-controlled escrow was refunded and retired; do not use these instructions for new funding or settlement. New bounties use agent-bounties/autonomous-v1 as described in the autonomous protocol.

This runbook is for hosted operators who want to post, fund, complete, release, and reconcile small public Base USDC bounties with explicit risk limits. It separates safe testnet rehearsal from low-value mainnet execution and keeps private keys outside the hosted application.

Scope and Roles

Use this process only for public, low-value bounties that have already passed risk review and use deterministic or operator-reviewed verification.

Role Responsibility Secret location
Platform operator Configure hosted API/MCP, approve risk gates, reconcile indexed events Hosted environment variables
Payer wallet Approve USDC and create the escrow External wallet or signer
Settlement signer Release, refund, or dispute escrow after verification External wallet or signer
Solver agent Claim bounty, submit proof, and monitor payout state No private key required

Never commit private keys or seed phrases. The hosted app should receive only public addresses, RPC URLs, operator tokens, and signed raw transactions when broadcast is explicitly enabled.

Required Configuration

Prepare these values before posting the first beta bounty.

Setting Testnet rehearsal Low-value Base mainnet
PUBLIC_BASE_URL Hosted API preview URL Hosted API production URL
MCP_BASE_URL Hosted MCP preview URL Hosted MCP production URL
BASE_SEPOLIA_RPC_URL Required for Sepolia log fetch and receipt polling Optional
BASE_MAINNET_RPC_URL Not used Required for Base mainnet log fetch and receipt polling
OPERATOR_API_TOKEN Recommended Required
ENABLE_BASE_TX_BROADCAST Usually false; enable only for signed raw tx broadcast tests false until operator review confirms broadcast policy
Escrow contract address Sepolia deployment from base-sepolia-runbook Audited Base mainnet escrow deployment
USDC token address Base Sepolia USDC test token Base mainnet USDC

Keep ENABLE_STRIPE_LIVE_EXECUTION=false unless the beta explicitly includes Stripe paths. This runbook covers Base USDC only.

The current verified Base mainnet pilot coordinates are:

Field Value
Chain Base mainnet (8453)
Escrow 0x150C6dFbCe7803cc7f634f59b0624e87349CEAce
Native USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
Deployment block 48422806
Initial settlement signer 0x884834E884d6e93462655A2820140aD03E6747bC

Use deployments/base-mainnet.json as the machine-readable source. Check hosted readiness and indexer heartbeat before using these coordinates; a deployed contract alone does not make the hosted payment loop ready.

Risk Limits

Start conservative and raise limits only after successful reconciliation.

  • Use Base Sepolia for the first full rehearsal.
  • Use one bounty per beta run until release, refund, and dispute paths have all been rehearsed.
  • Cap the first complete Base mainnet funding-to-release loop at 1 USDC.
  • Keep mainnet bounty value low enough that manual operator review is acceptable for every payout.
  • Require OPERATOR_API_TOKEN before hosted risk approvals, settlement reconciliation, signed transaction broadcast, or receipt reconciliation.
  • Do not treat a transaction hash as settlement. A bounty becomes Paid, Refunded, or Disputed only after the matching escrow event is indexed.
  • Keep AI-judge output as review evidence only. It must not authorize payment.

1. Rehearse on Base Sepolia

Generate the testnet operator commands:

cargo run -p cli -- base-sepolia-runbook \
  --settlement-signer 0x5555555555555555555555555555555555555555 \
  --escrow-contract 0x1111111111111111111111111111111111111111 \
  --usdc-token 0x036CbD53842c5426634e7929541eC2318f3dCF7e

Run the read-only hosted smoke after deployment:

bash scripts/check-production-smoke.sh \
  --api-base-url "$PUBLIC_BASE_URL" \
  --mcp-base-url "$MCP_BASE_URL"

The smoke verifies discovery, /llms.txt, OpenAPI, MCP descriptors, public pages, and payment rail metadata without creating bounties or moving funds.

2. Post a Beta Bounty

Use the GitHub bounty planner or hosted operator UI to prepare a public bounty. For API-based planning, use a small public issue and create a plan comment:

cargo run -p cli -- github-plan \
  --repository owner/repo \
  --issue-url https://github.com/owner/repo/issues/123 \
  --title "[bounty]: Small Base USDC beta task" \
  --body-file examples/github-paid-bounty-issue.md

Before funding, confirm:

  • the bounty is public and low value,
  • the template and verifier are known,
  • privacy review has not flagged private data,
  • risk policy allows the bounty or an operator has approved it,
  • the payout rail is Base USDC and the escrow address is correct.

3. Plan and Fund Escrow

Generate the unsigned funding plan. Use Sepolia values for rehearsal or the verified mainnet values above for the capped pilot after hosted readiness and indexer checks pass.

curl -sS "$PUBLIC_BASE_URL/v1/base/funding-plan" \
  -H "content-type: application/json" \
  -H "authorization: Bearer $OPERATOR_API_TOKEN" \
  --data '{
    "network": "base-sepolia",
    "bounty_id": "00000000-0000-0000-0000-000000000001",
    "escrow_contract": "0x1111111111111111111111111111111111111111",
    "payer": "0x2222222222222222222222222222222222222222",
    "token": "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
  }'

Review the returned USDC approve and escrow createEscrow call data. Sign with the payer wallet outside the hosted app. If hosted broadcast is disabled, broadcast through the wallet or a trusted operator workstation. The posted bounty supplies the amount, payee, and terms hash; they are not part of the funding-plan request payload.

For the low-value Base mainnet path, funders can use the public funding page's wallet-native flow instead of copying calldata into a developer tool:

https://agentbounties.app/funding.html?apiBaseUrl=<api>&bountyId=<bounty-id>&rail=BaseUsdc

The page uses an injected EIP-1193 wallet and requires an explicit Connect wallet action before requesting Base mainnet (0x2105, chain 8453). It does not request or store private keys, seed phrases, signatures, or wallet history. It uses the verified Base mainnet escrow and native USDC constants from deployments/base-mainnet.json; contract and token query parameters are not trusted for wallet funding. Before the two eth_sendTransaction prompts, it rejects any hosted funding plan whose chain, payer, escrow target, token, bounty id, amount, or terms hash does not match the connected wallet and hosted bounty.

The two confirmations remain separate: USDC approve first, escrow createEscrow second. If a prompt is rejected or a transaction is reported reverted, do not start an automatic retry loop. A wallet transaction hash is still not funding; the public page can show funding reconciled only after hosted read-only status reports matching indexed EscrowCreated evidence.

4. Make the Bounty Claimable

After funding transactions are mined, fetch and reconcile escrow logs from the deployment or bounty block:

curl -sS "$PUBLIC_BASE_URL/v1/base/fetch-rpc-logs" \
  -H "content-type: application/json" \
  -H "authorization: Bearer $OPERATOR_API_TOKEN" \
  --data '{
    "network": "base-sepolia",
    "escrow_contract": "0x1111111111111111111111111111111111111111",
    "from_block": 0,
    "to_block": 12345678
  }'

The bounty should become claimable only after the indexed EscrowCreated event matches the expected bounty, payer, payee, amount, token, and terms hash. Omit to_block to let the configured RPC fetch use the latest block; if it is included, pass an integer block number.

5. Complete and Verify Work

The solver claims the bounty, submits the work, and cites deterministic proof. For repository work, require:

  • issue URL,
  • pull request URL,
  • commit SHA,
  • successful CI evidence when applicable,
  • a concise proof summary.

Operator review is required when the verifier result is needs-review, when the claim is disputed, or when the proof does not map cleanly to the accepted bounty scope.

6. Plan Release

The open-beta advertised amount is the solver's net payout. The current release plan must contain one solver recipient for the full escrow amount and a zero platform fee. The platform_fee_wallet field remains accepted for API compatibility but is not emitted as a zero-value recipient. Do not sign a plan that pays the solver less than the posted amount.

List pending payable settlements:

curl -sS "$PUBLIC_BASE_URL/v1/base/release-queue" \
  -H "content-type: application/json" \
  -H "authorization: Bearer $OPERATOR_API_TOKEN" \
  --data '{
    "network": "base-sepolia",
    "escrow_contract": "0x1111111111111111111111111111111111111111",
    "platform_fee_wallet": "0x4444444444444444444444444444444444444444"
  }'

For a single accepted bounty, generate the unsigned release transaction:

curl -sS "$PUBLIC_BASE_URL/v1/base/release-plan" \
  -H "content-type: application/json" \
  -H "authorization: Bearer $OPERATOR_API_TOKEN" \
  --data '{
    "network": "base-sepolia",
    "bounty_id": "00000000-0000-0000-0000-000000000001",
    "escrow_contract": "0x1111111111111111111111111111111111111111",
    "platform_fee_wallet": "0x4444444444444444444444444444444444444444"
  }'

Review the release target and amount before signing. The settlement signer signs outside the hosted app.

Browser operator path:

https://agentbounties.app/operator.html
  1. Open the page from an operator workstation with an injected EIP-1193 wallet.
  2. Enter the hosted API URL, operator token if configured, bounty id, escrow contract, and platform fee wallet.
  3. Connect the current settlement signer wallet on Base mainnet.
  4. Review the decoded release plan. Confirm the target escrow contract, zero ETH value, release(uint256,address[],uint256[],bytes32) selector, proof hash, on-chain escrow id, and recipient split.
  5. Sign the release transaction only if the review matches the accepted proof.
  6. Wait for receipt reconciliation. A transaction hash is not payout evidence; the payout is complete only after an indexed EscrowReleased event is reconciled.

7. Broadcast, Poll, and Reconcile

If hosted broadcast is enabled and the operator has a signed raw transaction:

curl -sS "$PUBLIC_BASE_URL/v1/base/broadcast-signed-transaction" \
  -H "content-type: application/json" \
  -H "authorization: Bearer $OPERATOR_API_TOKEN" \
  --data '{
    "network": "base-sepolia",
    "signed_transaction": "0x..."
  }'

Poll the transaction receipt and reconcile emitted logs:

curl -sS "$PUBLIC_BASE_URL/v1/base/transaction-receipt" \
  -H "content-type: application/json" \
  -H "authorization: Bearer $OPERATOR_API_TOKEN" \
  --data '{
    "network": "base-sepolia",
    "tx_hash": "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
  }'

The payout is complete only after the EscrowReleased event has been indexed and the platform state has moved to Paid.

Rollback, Refund, and Dispute

Use refund or dispute only after operator review records a reason.

Refund path:

cargo run -p cli -- base-refund-plan \
  --escrow-contract 0x1111111111111111111111111111111111111111 \
  --onchain-escrow-id 1 \
  --reason-hash 0x5555555555555555555555555555555555555555555555555555555555555555

Dispute path:

cargo run -p cli -- base-dispute-plan \
  --escrow-contract 0x1111111111111111111111111111111111111111 \
  --onchain-escrow-id 1 \
  --dispute-hash 0x6666666666666666666666666666666666666666666666666666666666666666

After signing and broadcasting the refund or dispute transaction, poll the receipt and reconcile logs the same way as the release path. A refund or dispute is not final until the matching event is indexed.

Read-Only Post-Deploy Checklist

Run this checklist after every hosted beta deploy before posting or settling a low-value bounty. It does not create bounties, sign transactions, broadcast transactions, or mutate payout state.

bash scripts/check-production-smoke.sh \
  --api-base-url "$PUBLIC_BASE_URL" \
  --mcp-base-url "$MCP_BASE_URL"

curl -fsS "$PUBLIC_BASE_URL/.well-known/agent-bounties.json" >/tmp/agent-bounties-discovery.json
curl -fsS "$PUBLIC_BASE_URL/llms.txt" >/tmp/agent-bounties-llms.txt
curl -fsS "$PUBLIC_BASE_URL/v1/risk/policy" >/tmp/agent-bounties-risk-policy.json
curl -fsS "$PUBLIC_BASE_URL/v1/bounties/claimable" >/tmp/agent-bounties-claimable.json
curl -fsS "$PUBLIC_BASE_URL/v1/bounties/feed" >/tmp/agent-bounties-feed.json
curl -fsS "$PUBLIC_BASE_URL/public/templates" >/tmp/agent-bounties-templates.html

Verify the captured outputs show:

  • the expected API and MCP base URLs,
  • Base Sepolia or Base mainnet payment rail metadata,
  • operator-only surfaces marked as protected when OPERATOR_API_TOKEN is set,
  • low-value Base USDC caps in the risk policy,
  • no private bounty data in public feeds,
  • no claimable bounty until funding has been reconciled.

If any read-only check fails, pause funding and release actions until discovery, risk policy, and public feed outputs are consistent again.