docs: decide USDC-over-SAC payment rail and testnet agent-wallet custody (ADR-0003) with a verified testnet payment PoC

[XxHugheadxX]

Closes #7

Summary

Decides how consumers pay agents and who holds agent keys, with a real testnet payment as proof.

• docs/spikes/payments-and-wallets.md: answers the 6 questions of spike: agent payment rail and wallet custody on Stellar #7, each with sources
• docs/adr/0003-payment-rail-and-custody.md: the decision, alternatives, and impact on feat: register agent flow (wallet and on-chain identity) #18, feat: hire and pay endpoint with on-chain payment verification #19, feat: wallet connection in Flutter app #25, chore: testnet configuration and secrets management #30, spike: agent definition (manifest) and deployment model for Agent Studio #33, feat: Agent Escrow and Payment contract on Soroban #55
• spikes/payments-poc/pay.sh (+ README.md, .env.example): makes one real testnet payment on the chosen rail and verifies it over plain HTTP
• docs/spikes/agent-definition.md, docs/adr/0004-…: resolve deploy steps 3 and 5, which spike: agent definition (manifest) and deployment model for Agent Studio #33 left pending on this ADR
• .gitignore: add !**/.env.example. The **/.env.* rule from feat(contracts): add agent identity registry per ADR-0002 #56 was ignoring every .env.example, including the one spike: agent payment rail and wallet custody on Stellar #7 requires

Decisions

1. Rail: direct USDC transfer through the SAC to the agent's muxed address, whose muxed id is the hire id. The SAC's transfer event returns it as to_muxed_id, so one event proves who was paid, how much, and for which hire. No x402, MPP SDK, or escrow in the MVP.
2. The server verifies over plain HTTP (getTransaction, xdrFormat: "json") and accepts a payment only if: status is SUCCESS; the event comes from the configured USDC SAC (a look-alike token must not pass); to is the agent wallet; the amount matches exactly; to_muxed_id is the hire id; and the tx hash was not used before. The PoC showed the same hire can be paid twice, so the server must dedupe.
3. Agent wallets: server-custodied G-accounts, testnet only. Mainnet is blocked until agent wallets move to smart accounts with spending limits.
4. Server-side signing with stellar_dart (pure Dart), inside the Serverpod LedgerPort adapter. Fallback: a TypeScript sidecar.
5. set_agent_wallet two-party auth: the agent account is the transaction source (server signs), and the builder signs only their authorization entry with Freighter's signAuthEntry.

Acceptance criteria

• All 6 questions are answered, each with at least one source link
• Question 6 ends with a concrete decision: which component signs which transactions, and with which library
• ADR-0003 exists and states its impact on feat: register agent flow (wallet and on-chain identity) #18 and feat: hire and pay endpoint with on-chain payment verification #19
• The PoC runs with the documented command and prints a tx hash
• The tx hash is posted in this PR and opens on a testnet explorer
• No secret keys are committed (keys are Stellar CLI identities; .env.example is provided)

Verification evidence

$ cd spikes/payments-poc && HIRE_ID=7 bash pay.sh
...
5/6 pay: transfer 5000000 stroops to the agent, muxed id = hire 7
    to MAV3KOEEBJC77IP4T2JT7FDUTQ5Y5GJXTIZGRG4CZFZ3GZX7V6IUOAAAAAAAAAAAA4A5I
6/6 verify over plain HTTP (getTransaction, xdrFormat=json)
    ✓ SUCCESS · to GAV3KOEEBJC77IP4T2JT7FDUTQ5Y5GJXTIZGRG4CZFZ3GZX7V6IUPBUK · amount 5000000 · hire 7

tx hash: 17ac14e085609df8e042b84e6c25aac7e1c30344eaa1b1fd0bcbed399b65243f

Explorer: https://stellar.expert/explorer/testnet/tx/17ac14e085609df8e042b84e6c25aac7e1c30344eaa1b1fd0bcbed399b65243f

Negative checks on the same transaction, with the script's matching rules:

Check	Value	Result
hire id	7 / 8 / 70	accept / reject / reject
amount	5000000 / 4999999 / 50000000	accept / reject / reject
emitting SAC	expected / other contract id	accept / reject

Secret scan on the diff (S[A-Z2-7]{55}): no matches. git check-ignore confirms .env.example is tracked while .env, .env.local and .env.production stay ignored.

Notes for reviewers

• @TOMOKI977: this issue was assigned to you; I started it in parallel (comment). Please review whether the decisions match what you had in mind.
• Proven vs. documented: the payment and HTTP verification are proven by the PoC. The set_agent_wallet two-party signing and getEvents in JSON are documented but not run; they are open questions for feat: register agent flow (wallet and on-chain identity) #18 and feat: agent catalog endpoints with on-chain indexing #17.
• Real testnet USDC works the same way; the README shows how to switch the PoC from the test asset to Circle's faucet USDC.

[cloudflare-workers-and-pages]

Deploying puls3 with    Cloudflare Pages

Latest commit:	e811502
Status:	✅  Deploy successful!
Preview URL:	https://a297e7f6.puls3-4lw.pages.dev
Branch Preview URL:	https://docs-7-payments-and-wallets.puls3-4lw.pages.dev

View logs