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

[chopmob-cloud]

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

What this adds

A parallel to the existing cards, x402, and crypto-algo (PR #218) scenarios - 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. 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 Payment Processor Agent resolves the transaction deterministically via getSignaturesForAddress(<reference>). This is:

• Cryptographically unique per checkout (256-bit entropy)
• 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

Scope

Minimal and additive - two files under code/samples/python/scenarios/a2a/human-present/crypto-solana/:

• README.md - full flow documentation including env var reference
• run.sh - launcher (starts Merchant, CP, MPP agents, then Shopping Agent via ADK web)

Uses the shared role agents already in code/samples/python/src/roles/. No changes to existing files.

Prerequisites

GOOGLE_API_KEY or GOOGLE_GENAI_USE_VERTEXAI=true
ALGOVOI_API_KEY  # sign up at https://cloud.algovoi.co.uk
SOLANA_RPC_URL   # defaults to public mainnet endpoint if not set

Production reference

The Solana Pay reference pubkey binding used in this scenario is derived from AlgoVoi's live multi-chain payment gateway, in production since 2026-05-06 across eight chain families (Algorand, VOI, Hedera, Stellar, Base, Solana, Tempo, and x402). The JCS canonicalization underlying the hash binding is governed by draft-hopley-x402-canonicalisation-jcs-v1 (IETF Independent Submission, AlgoVoi-authored). Reference implementation: AlgoVoi-authored algovoi-substrate on PyPI and npm, Apache 2.0. Cross-validated 192/192 byte-for-byte across 8 independent language implementations; conformance corpus: chopmob-cloud/algovoi-jcs-conformance-vectors.

-- AlgoVoi (chopmob-cloud)
https://docs.algovoi.co.uk/acquisition

[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

[chopmob-cloud]

This is already addressed in the current commit. PAYMENT_METHOD=CRYPTO_SOLANA is exported on line 13, before .env is processed. The while IFS= loop then uses [[ -v "$key" ]] to skip any variable that is already present in the environment — so a PAYMENT_METHOD entry in .env cannot override the scenario value. The result is identical to your suggestion (scenario value always wins) but the guard applies to every variable, not just PAYMENT_METHOD.

[chopmob-cloud]

Thanks for the review @gemini-code-assist. Both points addressed in the latest commit:

• Env var sourcing order: replaced set -a; source .env; set +a with a while IFS= loop that skips any variable already present in the calling environment. This means shell-exported variables always take precedence over values in .env, rather than being silently overwritten.

• Process tracking initialisation: moved pids=() to before the cleanup() function definition and trap cleanup EXIT, so the cleanup handler is safe to call at any point in the script's lifecycle — including early exits during uv sync.

[gemini-code-assist]

Thanks for the update, @chopmob-cloud. The changes to the environment variable sourcing and the process tracking initialization look solid and address the concerns raised. The use of a while loop for .env sourcing is a much safer approach, and moving the pids initialization ensures the cleanup function is robust against early exits. This looks good to go.

[chopmob-cloud]

Bumping for maintainer visibility -- Gemini review is satisfied (env sourcing and process tracking both approved in the April 29 pass).

Since then, the Solana Pay reference binding pattern this PR demonstrates has moved into production: the AlgoVoi gateway now settles on Solana in live agent payment flows using the same per-checkout reference pubkey approach. The MCP server (uvx algovoi-mcp / npx -y @algovoi/mcp-server) exposes Solana as one of 8 live chains for AI agents calling AP2-compatible payment tools.

Happy to rebase or split the PR if it would help.

-- AlgoVoi (chopmob-cloud)