feat(samples): add human-present crypto-solana scenario (AP2 + Solana Pay reference binding)

[chopmob-cloud]

Adds a new human-present A2A scenario: samples/python/scenarios/a2a/human-present/crypto-solana/.

What this adds

A parallel to the existing cards, x402, and open crypto-algo (PR #218) scenarios — but settling on Solana using on-chain USDC (SPL Token) with Solana Pay reference pubkey binding for deterministic tx↔mandate correlation.

Why reference binding matters here

Solana has no native transaction memo field (unlike Algorand / Hedera), and the SPL Memo Program is inconsistently supported across wallets (Phantom exposes it, Backpack and most agentic wallets do not). The canonical Solana Pay primitive for binding a settling transaction to a specific order is a reference pubkey — a fresh ed25519 public key included as a read-only, non-signer account on the transfer instruction:

solana:<recipient>?amount=<x>&spl-token=<USDC_MINT>&reference=<burner_pubkey>&label=...&message=<mandate_id>

After settlement, the merchant (or AP2 Merchant Payment Processor Agent) resolves the transaction deterministically via getSignaturesForAddress(<reference>). This is:

• Cryptographically unique per checkout (256-bit entropy) — no amount-uniqueness gymnastics
• Wallet-universal — every Solana Pay–compliant wallet attaches the reference automatically
• Non-interactive from the buyer's side — no need to paste a tx signature back

For agent-initiated commerce (AP2's core use case), this removes a social trust layer that card and x402 flows don't have to worry about.

Scope of this PR

Minimal and additive. Mirrors the existing cards/ and crypto-algo/ scenario structure:

• samples/python/scenarios/a2a/human-present/crypto-solana/README.md — full scenario walkthrough + asset table + mandate-chain diagram
• samples/python/scenarios/a2a/human-present/crypto-solana/run.sh — PAYMENT_METHOD=CRYPTO_SOLANA + merchant / credentials-provider / MPP / shopping-agent startup (identical control flow to crypto-algo and cards)

No changes to the Python agent code in samples/python/src/roles/. Downstream branching on CRYPTO_SOLANA is a natural follow-up once the AP2 core adds a formal payment method registry entry — open to doing that in a follow-up PR once this scenario shell is merged.

Assets supported

Asset	Mint	Decimals
USDC (mainnet)	EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v	6
USDT (mainnet)	Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB	6
USDC (devnet)	4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU	6
Native SOL	—	9

Reference implementation

A production AP2 facilitator with Solana Pay reference verification is already live at https://api1.ilovechicken.co.uk (AlgoVoi). The verifier resolves getSignaturesForAddress(reference), fetches the transaction, confirms SPL mint + amount + recipient against the PaymentMandate contents, and requires the reference pubkey to appear in the tx's account keys. Source: AlgoVoi-Platform-Adapters (MCP adapter) — happy to share the facilitator's Solana verifier as a separate AP2 core contribution if useful.

Relationship to existing PRs

• Complements open PR feat(samples): add human-present crypto-algo scenario (AP2 v0.1 + AlgoVoi on-chain USDC extension) #218 (crypto-algo — Algorand/VOI on-chain USDC). Together they cover non-EVM settlement across the two largest non-EVM chains alongside the existing EVM-focused x402 scenario.
• x402 scenario (already merged) + crypto-algo (pending) + crypto-solana (this PR) = full AVM, EVM, and SVM coverage for human-present commerce in AP2.

Testing

Run locally:

export GOOGLE_API_KEY=...
export ALGOVOI_API_KEY=algv_...   # any Solana-aware AP2 facilitator
export SOLANA_RPC_URL=...
./samples/python/scenarios/a2a/human-present/crypto-solana/run.sh

Happy to sign the Google CLA as per PR #218.

[gemini-code-assist]

Code Review

This pull request introduces a new sample scenario for human-present transactions using on-chain Solana USDC, including a detailed README on the Solana Pay reference binding mechanism and a shell script to orchestrate the necessary agents. Feedback was provided regarding the order of environment variable sourcing in the startup script to prevent unintended overrides from local configuration files and to improve the robustness of the cleanup process by initializing process tracking earlier.

[gemini-code-assist]

The PAYMENT_METHOD environment variable is set at line 12, but then .env is sourced at line 25. If the user has PAYMENT_METHOD defined in their .env file, it will override the scenario-specific value (CRYPTO_SOLANA), potentially causing the script to execute with the wrong payment logic. It is safer to source the .env file first and then set scenario-specific overrides. Additionally, initializing the pids array early ensures that the cleanup trap (line 80) is always safe even if the script fails during early setup (e.g., line 20).

Suggested change

	export PAYMENT_METHOD=CRYPTO_SOLANA
	AGENTS_DIR="samples/python/src/roles"
	LOG_DIR=".logs"
	if [ ! -d "$AGENTS_DIR" ]; then
	echo "Error: Directory '$AGENTS_DIR' not found."
	echo "Please run this script from the root of the repository."
	exit 1
	fi
	if [ -f .env ]; then
	set -a
	source .env
	set +a
	fi
	if [ -f .env ]; then
	set -a
	source .env
	set +a
	fi
	export PAYMENT_METHOD=CRYPTO_SOLANA
	AGENTS_DIR="samples/python/src/roles"
	LOG_DIR=".logs"
	pids=()
	if [ ! -d "$AGENTS_DIR" ]; then
	echo "Error: Directory '$AGENTS_DIR' not found."
	echo "Please run this script from the root of the repository."
	exit 1
	fi