Skip to content

real-funding-rehearsal.md

Latest commit

 

History

History
317 lines (246 loc) · 12.8 KB

real-funding-rehearsal.md

File metadata and controls

317 lines (246 loc) · 12.8 KB
Raw

Real Funding Rehearsal

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 exercises actual payment rails in safe development modes:

  • Stripe test mode for fiat top-ups and Connect payout eligibility,
  • Base Sepolia for USDC escrow funding and release,
  • the platform ledger for pooled and mixed bounty accounting.

The invariant is the same in every mode: a request, Checkout Session, transaction plan, signed transaction, broadcast, or transaction hash is not funding and is not payout. Funding and distribution become platform state only after deterministic evidence is reconciled:

  • Stripe fiat funding: a verified checkout.session.completed webhook.
  • Base USDC funding: an indexed EscrowCreated log.
  • Base USDC payout: an indexed EscrowReleased log whose proof hash matches the accepted proof record.
  • Stripe fiat payout: a transfer.created event whose metadata matches the payout intent, settlement, bounty, proof record, and agent.

The same boundary is advertised to autonomous agents through /llms.txt and /.well-known/agent-bounties.json under real_money_rehearsal, so agents can discover that the project supports Stripe test-mode fiat funding, Base Sepolia USDC escrow, pooled funding, mixed funding, and evidence-gated distribution without reading this full runbook first.

Preconditions

Local setup:

.\scripts\preflight.ps1 -Mode core
docker compose up -d postgres
$env:DATABASE_URL = "postgres://agent_bounties:agent_bounties@localhost:5432/agent_bounties"
cargo run -p api

Optional hosted safety controls:

$env:OPERATOR_API_TOKEN = "<operator-token>"
$env:ENABLE_STRIPE_LIVE_EXECUTION = "true"
$env:ENABLE_STRIPE_PUBLIC_CHECKOUT = "true"
$env:STRIPE_SECRET_KEY = "sk_test_..."
$env:STRIPE_PAYMENT_METHOD_CONFIGURATION = "" # optional Dashboard-managed Checkout method set
$env:STRIPE_WEBHOOK_SECRET = "whsec_..."
$env:ENABLE_BASE_TX_BROADCAST = "true"
$env:BASE_SEPOLIA_RPC_URL = "https://..."

Base Sepolia also needs:

  • a deployed AgentBountyEscrow contract,
  • a test USDC token address for the same network (0x036CbD53842c5426634e7929541eC2318f3dCF7e for native Base Sepolia USDC),
  • a payer wallet with test token balance,
  • a settlement signer wallet that can call release, refund, and markDisputed.

Generate deployment and payout commands:

cargo run -p cli -- base-sepolia-runbook `
  --settlement-signer <settlement-signer-address> `
  --escrow-contract <escrow-contract-address> `
  --usdc-token <base-sepolia-usdc-token-address>

Fast Local Rehearsal

This command runs the complete mixed rail lifecycle with deterministic local fixtures. It does not call Stripe or Base RPC, but it uses the same funding intent, webhook reconciliation, escrow event reconciliation, proof, release, and payout state-machine code used by hosted services.

cargo run -p cli -- funding-rehearsal-demo

Before using Stripe test mode or Base Sepolia RPC, inspect operator readiness:

cargo run -p cli -- real-funding-readiness `
  --network base-sepolia `
  --escrow-contract <escrow-contract-address> `
  --usdc-token <base-sepolia-usdc-token-address>

The readiness report does not call Stripe or Base. It checks whether local simulation, Stripe test-mode execution, Stripe webhook evidence, Base Sepolia log reconciliation, optional signed transaction broadcast, the non-secret Stripe payment-method configuration indicator, and hosted operator auth are configured. Missing readiness only blocks the external rail step; the deterministic local rehearsal remains runnable.

Expected evidence boundary in the JSON output:

  • stripe.funding_intent starts as AwaitingEvidence.
  • stripe.checkout_request is a test-mode Checkout Session request intent.
  • stripe.funding_reconciliation applies only after the simulated paid webhook with bounty_id and funding_intent_id metadata.
  • base.funding_intent starts as AwaitingEvidence.
  • base.funding_plan contains unsigned Base Sepolia approve and createEscrow calls.
  • base.created_reconciliation applies only after the simulated EscrowCreated log.
  • base.release_plan is unsigned release calldata.
  • base.released_reconciliation applies only after the simulated EscrowReleased log with the accepted proof hash.
  • stripe.connect_eligibility can move blocked payout intents back to Pending, but it does not create payout ledger entries.
  • stripe.transfer_plan is a test-mode Connect transfer request intent.
  • stripe.transfer_reconciliation applies only after the simulated transfer.created event with matching payout metadata.

Public Rehearsal Artifacts

Use the checked runner when you want shareable JSON evidence instead of terminal output:

.\scripts\real-funding-rehearsal.ps1

On Unix-like shells:

bash scripts/real-funding-rehearsal.sh

The runner writes:

  • target/real-funding-rehearsal/funding-rehearsal-demo.json
  • target/real-funding-rehearsal/real-funding-readiness.json

It then validates that:

  • the mixed bounty has separate StripeFiat and BaseUsdc funding targets,
  • Stripe Checkout and Base escrow plans start as AwaitingEvidence,
  • Stripe funding applies only after checkout.session.completed,
  • Base funding applies only after EscrowCreated,
  • Base payout applies only after EscrowReleased,
  • Stripe payout applies only after transfer.created,
  • readiness reports whether STRIPE_PAYMENT_METHOD_CONFIGURATION is configured without exposing the Stripe object id,
  • final settlements pay each rail's full advertised amount to the solver and record a zero open-beta platform fee.

The Real Funding Rehearsal GitHub Actions workflow runs the same script on manual dispatch, schedule, main-branch payment-path changes, and PRs that touch payment-path code. The uploaded artifacts are public proof that the repository still supports pooled and mixed funding semantics without exposing live Stripe keys, private wallets, or signed Base transactions.

Stripe Test Mode Funding

Use funding intents when a contributor wants to assign real fiat funding to a bounty through Stripe test mode.

  1. Open a pooled fiat or mixed bounty.
curl -X POST http://127.0.0.1:8080/v1/bounties/pooled `
  -H "content-type: application/json" `
  --data '{"title":"Stripe test funded bounty","template_slug":"small-code-change","target_amount_minor":5000,"currency":"usd","funding_mode":"StripeFiatLedger","privacy":"Public","funding_targets":[]}'
  1. Create a Stripe funding intent.
New-Item -ItemType Directory -Force target | Out-Null
curl.exe -sS -X POST http://127.0.0.1:8080/v1/bounties/<bounty-id>/funding-intents `
  -H "content-type: application/json" `
  --data '{"bounty_id":"<bounty-id>","source_organization_id":"00000000-0000-0000-0000-000000000001","amount_minor":5000,"currency":"usd","rail":"StripeFiat","external_reference":"stripe-test-5000"}' `
  | Set-Content target\stripe-funding-intent.json
  1. Execute the exact Checkout Session request in Stripe test mode.
cargo run -p cli -- stripe-execute-request-intent `
  --intent-file target\stripe-funding-intent.json

Open the returned Checkout URL and pay with a Stripe test payment method. The Checkout Session itself still does not credit the bounty. The command executes the funding intent's own StripeRequestIntent, preserving bounty_id, funding_intent_id, and funding_intent_reference metadata for webhook reconciliation.

Hosted self-serve funding can execute the stored bounty funding intent through:

curl.exe -sS -X POST http://127.0.0.1:8080/v1/stripe/live/funding-intents/{id}/checkout-session

The endpoint requires ENABLE_STRIPE_LIVE_EXECUTION=true, ENABLE_STRIPE_PUBLIC_CHECKOUT=true, and Stripe credentials on the hosted API. It returns a Stripe Checkout URL for the specific funding intent and preserves the funding intent's optional success/cancel return URLs. The bounty is still funded only after the signed webhook is reconciled.

If STRIPE_PAYMENT_METHOD_CONFIGURATION is set, the Checkout Session request includes that Stripe Dashboard configuration id. This is useful for rehearsing PayPal-capable Checkout where the Stripe account supports it, but the redirect and request creation are still not funding evidence.

  1. Reconcile the signed webhook.

Configure Stripe CLI or Dashboard webhooks to deliver checkout.session.completed to:

POST http://127.0.0.1:8080/v1/stripe/checkout-webhooks

The webhook must carry metadata.bounty_id and metadata.funding_intent_id. After successful reconciliation, the platform credits the source organization's Stripe balance and reserves that balance into the bounty. Replaying the same Stripe event id must be ignored as a duplicate.

Base Sepolia USDC Funding

Use Base funding intents when a contributor wants public, portable USDC escrow.

  1. Open a Base or mixed bounty.
curl -X POST http://127.0.0.1:8080/v1/bounties/pooled `
  -H "content-type: application/json" `
  --data '{"title":"Base Sepolia funded bounty","template_slug":"small-code-change","target_amount_minor":1000000,"currency":"usdc","funding_mode":"BaseUsdcEscrow","privacy":"Public","funding_targets":[]}'
  1. Create a Base funding intent.
curl -X POST http://127.0.0.1:8080/v1/bounties/<bounty-id>/funding-intents `
  -H "content-type: application/json" `
  --data '{"bounty_id":"<bounty-id>","amount_minor":1000000,"currency":"usdc","rail":"BaseUsdc","external_reference":"base-sepolia-1000000","base_escrow_contract":"<escrow-contract-address>","base_payer":"<payer-wallet>","base_token":"<base-sepolia-usdc-token-address>","base_network":"base-sepolia"}'

  1. Sign and send the returned approve and createEscrow transactions from the funding plan.

  2. Reconcile the funding evidence.

cargo run -p cli -- base-fetch-logs `
  --network base-sepolia `
  --escrow-contract <escrow-contract-address> `
  --from-block <deployment-or-funding-block>

Historical V1 receipt-triggered reconciliation is retired. In the autonomous protocol, the canonical indexer consumes factory and bounty logs independently; receipt polling never changes bounty or payment state.

Mixed Stripe And Base Funding

Mixed bounties require explicit funding targets and settle each rail separately.

curl -X POST http://127.0.0.1:8080/v1/bounties/pooled `
  -H "content-type: application/json" `
  --data '{"title":"Mixed Stripe fiat and Base USDC bounty","template_slug":"payment-state-machine","target_amount_minor":5000,"currency":"usd","funding_mode":"MixedRails","privacy":"Public","funding_targets":[{"rail":"StripeFiat","amount_minor":5000,"currency":"usd"},{"rail":"BaseUsdc","amount_minor":1000000,"currency":"usdc"}]}'

Create one Stripe funding intent for the USD partition and one Base funding intent for the USDC partition. The bounty remains unclaimable until both are confirmed by their own evidence. The platform never nets USD and USDC into one synthetic balance.

After deterministic verification:

  • Stripe settlement creates blocked payout intents until Connect eligibility is reconciled. Eligibility does not mark the fiat payout paid.
  • Stripe payout planning returns a Stripe Transfers API request intent through POST /v1/stripe/connect-transfers or MCP plan_stripe_connect_transfer. Execute it in Stripe test mode through POST /v1/stripe/live/connect-transfers, MCP execute_stripe_connect_transfer, or cargo run -p cli -- stripe-execute-request-intent with the returned request saved to disk.
  • Stripe fiat payout state becomes paid only after POST /v1/stripe/transfer-events or MCP reconcile_stripe_transfer_event reconciles a transfer.created event with matching bounty_id, proof_record_id, settlement_id, payout_intent_id, and agent_id metadata.
  • Base settlement creates pending release calldata until the settlement signer releases escrow and the indexed EscrowReleased log is reconciled.

Distribution Feedback

Every funding, claiming, PR, or proof interaction should ask:

  1. How did you find Agent Bounties?
  2. What made this bounty or project worth participating in?
  3. If an AI agent helped, what tool, prompt, link, label, or workflow led it here?
  4. What would make the project easier or more trustworthy before you participate again?

If useful, ask participants to star the repository, react/upvote useful issues or bounties, share it with other AI-agent builders or bounty solvers, and invite collaborators who can improve task liquidity, verifier quality, payment trust, or agent distribution.

Those answers are distribution data only. They do not affect merge approval, bounty acceptance, or payout authorization.