From 1fbae87983dce8ab828705e6efd1b3b141a11100 Mon Sep 17 00:00:00 2001
From: AlgoVoi <chopmob@gmail.com>
Date: Tue, 4 Aug 2026 11:34:52 +0100
Subject: [PATCH 1/2] feat(samples): add human-present crypto-solana scenario
 (AP2 + Solana Pay reference binding)

Signed-off-by: AlgoVoi <chopmob@gmail.com>
---
 .../a2a/human-present/crypto-solana/README.md | 143 ++++++++++++++++++
 .../a2a/human-present/crypto-solana/run.sh    | 132 ++++++++++++++++
 2 files changed, 275 insertions(+)
 create mode 100644 code/samples/python/scenarios/a2a/human-present/crypto-solana/README.md
 create mode 100755 code/samples/python/scenarios/a2a/human-present/crypto-solana/run.sh

diff --git a/code/samples/python/scenarios/a2a/human-present/crypto-solana/README.md b/code/samples/python/scenarios/a2a/human-present/crypto-solana/README.md
new file mode 100644
index 00000000..16680b4d
--- /dev/null
+++ b/code/samples/python/scenarios/a2a/human-present/crypto-solana/README.md
@@ -0,0 +1,143 @@
+<!-- cspell:words Hedera Solflare keypair mainnet devnet ALGOVOI algv Helius Backpack Triton Phantom -->
+
+# Agent Payments Protocol Sample: Human Present Purchases with On-Chain Solana USDC
+
+This sample demonstrates the A2A `ap2-extension` for a human-present transaction
+where the buyer settles with on-chain USDC on Solana (or native SOL for
+micropayments). It mirrors the existing `x402` scenario but uses Solana Pay
+semantics (specifically the **`reference` pubkey** primitive) to bind the
+settling transaction to a specific AP2 `PaymentMandate`.
+
+**Note:** This sample pairs with the separate `crypto-algo` human-present
+scenario. Together they cover non-EVM settlement on Algorand and Solana as a
+complement to the EVM-focused `x402` path.
+
+## Scenario
+
+Human-present flows are commerce flows where the user is present to confirm
+purchase details. The user signs the `PaymentMandate` giving all parties high
+confidence in the transaction.
+
+The Solana variant adds one additional primitive on top of the standard AP2
+mandate chain:
+
+### Solana Pay `reference` binding
+
+Solana has no native transaction memo field (unlike Algorand or Hedera), and
+the SPL Memo Program is unreliable across wallets. Instead, Solana Pay defines
+a `reference` pubkey mechanism:
+
+1. The merchant (or its Merchant Agent) generates a fresh, single-use ed25519
+   keypair per checkout.
+2. The public key is embedded in the Solana Pay URL:
+
+   ```text
+   solana:<recipient>
+     ?amount=<amount>
+     &spl-token=<USDC_MINT>
+     &reference=<reference_pubkey>
+     &label=<label>
+     &message=<order-id>
+   ```
+
+3. The buyer's wallet (Phantom, Solflare, Backpack, etc.) includes the
+   `reference` pubkey as a read-only, non-signer account in the transfer
+   instruction.
+4. After the user signs and broadcasts the SPL Token transfer, the merchant
+   (or facilitator) queries `getSignaturesForAddress(<reference>)` to locate
+   the exact transaction that settled this order.
+5. Final verification compares the on-chain transfer's recipient, amount, and
+   SPL mint against the AP2 `PaymentMandate` contents. All three must match.
+
+This is stronger than relying on amount uniqueness (EVM-style) and more
+wallet-compatible than relying on memos. It also means the merchant never has
+to ask the buyer to paste a transaction signature back.
+
+## Key Actors
+
+This sample consists of:
+
+- **Shopping Agent:** The main orchestrator that handles the user's shopping
+  request and delegates to specialist agents.
+- **Merchant Agent:** Handles product queries and assembles the `CartMandate`.
+- **Merchant Payment Processor Agent:** Takes payments on behalf of the
+  merchant and, in the Solana flow, verifies the on-chain USDC transfer
+  against the expected `reference`, amount, and mint.
+- **Credentials Provider Agent:** Holds the user's payment credentials, in
+  this flow the Solana wallet address and optional mint preferences.
+
+## Mandate Chain
+
+The AP2 mandate chain is unchanged by the Solana variant:
+
+```text
+IntentMandate  ──▶  CartMandate  ──▶  PaymentMandate
+     (user)              (merchant)       (user-signed)
+                                                │
+                                                ▼
+                                 Solana Pay URL (reference-bound)
+                                                │
+                                                ▼
+                             SPL Token Transfer + reference pubkey
+                                                │
+                                                ▼
+                              getSignaturesForAddress(reference)
+                                                │
+                                                ▼
+                                   PaymentReceipt
+```
+
+## Payment Method
+
+This scenario sets `PAYMENT_METHOD=CRYPTO_SOLANA` at startup. Downstream agents
+treat it as a non-card, non-x402 payment flow and route through the
+Solana-aware credentials provider path.
+
+## Assets Supported
+
+| Asset | Mint | Decimals |
+| --- | --- | --- |
+| USDC (Solana mainnet) | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | 6 |
+| USDT (Solana mainnet) | `Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB` | 6 |
+| USDC (Solana devnet) | `4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU` | 6 |
+| Native SOL | n/a | 9 |
+
+The Solana Pay URL format
+(`solana:<recipient>?amount=...&spl-token=<mint>&reference=<pubkey>`) carries
+the mint identifier, so supporting additional SPL tokens is a configuration
+concern on the Merchant Agent and does not require protocol changes.
+
+## Running the sample
+
+```bash
+# From the repository root:
+export GOOGLE_API_KEY="..."                 # required (or GOOGLE_GENAI_USE_VERTEXAI=true)
+export SOLANA_RPC_URL="https://..."         # optional; defaults to Solana devnet
+# Optional: if your Solana-aware AP2 facilitator requires an API key, export it, e.g.
+# export ALGOVOI_API_KEY="..."
+./code/samples/python/scenarios/a2a/human-present/crypto-solana/run.sh
+```
+
+The sample script starts the Merchant, Credentials Provider, and Merchant
+Payment Processor agents locally, then launches the Shopping Agent via the ADK
+web UI. You can then drive a purchase end-to-end with USDC on Solana.
+
+## Why Solana Pay `reference` matters for AP2
+
+AP2 mandates are already cryptographically signed, but they describe intent
+and authorization, not the on-chain settlement event itself. The `reference`
+pubkey is the missing link that ties a specific blockchain transaction to a
+specific `PaymentMandate` deterministically, without trusting the buyer to
+self-report their transaction signature. For agent-initiated commerce, where
+the "buyer" may be an AI agent and the "merchant" may be another AI agent,
+this mechanical binding removes an otherwise social trust layer.
+
+## Reference implementations
+
+- A Solana-aware AP2 facilitator (AlgoVoi is one example) verifies Solana
+  USDC transfers by (a) resolving `getSignaturesForAddress(reference)`,
+  (b) fetching the transaction, (c) checking mint + amount + recipient, and
+  (d) confirming the `reference` pubkey appears in the transaction's
+  account keys.
+- [Solana Pay specification](https://solanapay.com/), the canonical
+  reference for URL format and merchant-side flow.
diff --git a/code/samples/python/scenarios/a2a/human-present/crypto-solana/run.sh b/code/samples/python/scenarios/a2a/human-present/crypto-solana/run.sh
new file mode 100755
index 00000000..9e59a988
--- /dev/null
+++ b/code/samples/python/scenarios/a2a/human-present/crypto-solana/run.sh
@@ -0,0 +1,132 @@
+#!/bin/bash
+# cspell:words ALGOVOI algv mainnet devnet Helius
+
+# A script to automate the execution of the crypto-solana (on-chain USDC on Solana)
+# AP2 example. It starts all necessary servers and agents in the background.
+#
+# This scenario uses Solana Pay `reference` pubkey binding to link the settling
+# transaction deterministically to the signed AP2 PaymentMandate. See README.md
+# for the full flow.
+
+set -e
+
+export PAYMENT_METHOD=CRYPTO_SOLANA
+
+AGENTS_DIR="code/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
+
+# Source .env for defaults, but do not override variables already present in
+# the calling environment, which lets the caller's shell settings take
+# precedence over local configuration files.
+if [ -f .env ]; then
+  while IFS='=' read -r key remainder || [[ -n "$key" ]]; do
+    case "$key" in ''|\#*) continue ;; esac  # skip blank lines and comments
+    [[ -v "$key" ]] && continue              # already exported, do not override
+    export "$key=$remainder"
+  done < .env
+fi
+
+USE_VERTEXAI=$(printf "%s" "${GOOGLE_GENAI_USE_VERTEXAI}" | tr '[:upper:]' '[:lower:]')
+if [ -z "${GOOGLE_API_KEY}" ] && [ "${USE_VERTEXAI}" != "true" ]; then
+  echo "Please set your GOOGLE_API_KEY environment variable before running."
+  echo "Alternatively, set GOOGLE_GENAI_USE_VERTEXAI=true to use Vertex AI with ADC."
+  exit 1
+fi
+
+# Facilitator for on-chain verification. This scenario is facilitator-agnostic:
+# any Solana-aware AP2 facilitator works. Some facilitators authenticate with an
+# API key; if yours does, export it before running. The agents start regardless,
+# so you can drive the local flow without one.
+if [ -z "${ALGOVOI_API_KEY}" ]; then
+  echo "Note: no facilitator API key detected (e.g. ALGOVOI_API_KEY). Continuing."
+  echo "Set your facilitator's API key if it requires one for on-chain verification."
+fi
+
+# Solana RPC. Defaults to the public devnet endpoint for safe local testing;
+# override with a mainnet or paid provider (Helius, Alchemy, Triton) for real
+# settlement and rate-limit headroom.
+if [ -z "${SOLANA_RPC_URL}" ]; then
+  export SOLANA_RPC_URL="https://api.devnet.solana.com"
+  echo "SOLANA_RPC_URL not set; defaulting to the public Solana devnet endpoint."
+  echo "For mainnet settlement, set SOLANA_RPC_URL to a mainnet or paid RPC provider."
+fi
+
+echo "Setting up the Python virtual environment..."
+
+if [ ! -d ".venv" ]; then
+  uv venv
+fi
+
+case "$OSTYPE" in
+  msys* | cygwin*)
+    source .venv/Scripts/activate
+    ;;
+  *)
+    source .venv/bin/activate
+    ;;
+esac
+echo "Virtual environment activated."
+
+mkdir -p "$LOG_DIR"
+
+# Initialise pids before the trap so cleanup() is always safe to call,
+# even if the script exits before any background processes are started.
+pids=()
+
+cleanup() {
+  echo ""
+  echo "Shutting down background processes..."
+  if [ ${#pids[@]} -ne 0 ]; then
+    kill "${pids[@]}" 2>/dev/null
+    wait "${pids[@]}" 2>/dev/null
+  fi
+  echo "Cleanup complete."
+}
+
+trap cleanup EXIT
+
+echo "Syncing virtual environment with uv sync..."
+if uv sync --package ap2-samples; then
+  echo "Virtual environment synced successfully."
+else
+  echo "Error: uv sync failed. Aborting."
+  exit 1
+fi
+
+echo "Clearing the logs directory..."
+if [ -d "$LOG_DIR" ]; then
+  find "$LOG_DIR" -mindepth 1 -delete
+fi
+
+echo ""
+echo "Starting remote servers and agents as background processes..."
+
+UV_RUN_CMD="uv run --no-sync"
+
+if [ -f ".env" ]; then
+  UV_RUN_CMD="$UV_RUN_CMD --env-file .env"
+fi
+
+echo "-> Starting the Merchant Agent (port:8001 log:$LOG_DIR/merchant_agent.log)..."
+$UV_RUN_CMD --package ap2-samples python -m roles.merchant_agent >"$LOG_DIR/merchant_agent.log" 2>&1 &
+pids+=($!)
+
+echo "-> Starting the Credentials Provider (port:8002 log:$LOG_DIR/credentials_provider_agent.log)..."
+$UV_RUN_CMD --package ap2-samples python -m roles.credentials_provider_agent >"$LOG_DIR/credentials_provider_agent.log" 2>&1 &
+pids+=($!)
+
+echo "-> Starting the Merchant Payment Processor Agent (port:8003 log:$LOG_DIR/mpp_agent.log)..."
+$UV_RUN_CMD --package ap2-samples python -m roles.merchant_payment_processor_agent >"$LOG_DIR/mpp_agent.log" 2>&1 &
+pids+=($!)
+
+echo ""
+echo "All remote servers are starting."
+
+echo "Starting the Shopping Agent..."
+$UV_RUN_CMD --package ap2-samples adk web --host 0.0.0.0 $AGENTS_DIR/shopping_agent

From 623f3e9d5ab19db8d398a636a6b3bdd5692d5ad8 Mon Sep 17 00:00:00 2001
From: AlgoVoi <chopmob@gmail.com>
Date: Tue, 4 Aug 2026 11:34:53 +0100
Subject: [PATCH 2/2] ci: green Lint Code Base and zizmor via hardened
 linter.yaml

Signed-off-by: AlgoVoi <chopmob@gmail.com>
---
 .github/workflows/linter.yaml | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/linter.yaml b/.github/workflows/linter.yaml
index fea1b9c1..cfeddead 100644
--- a/.github/workflows/linter.yaml
+++ b/.github/workflows/linter.yaml
@@ -4,6 +4,11 @@ on:
   pull_request:
     branches: [main]
 
+permissions:
+  contents: read
+  statuses: write
+  pull-requests: write
+
 jobs:
   build:
     name: Lint Code Base
@@ -11,20 +16,22 @@ jobs:
 
     steps:
       - name: Checkout Code
-        uses: actions/checkout@v5
+        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
         with:
           fetch-depth: 0
+          persist-credentials: false
 
       - name: Lint Code Base
-        uses: super-linter/super-linter/slim@v8
+        uses: super-linter/super-linter/slim@4ce20838b8ab83717e78138c5b3a1407148e0918 # v8.7.0
         env:
           DEFAULT_BRANCH: main
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           LOG_LEVEL: WARN
           SHELLCHECK_OPTS: -e SC1091 -e 2086
           VALIDATE_ALL_CODEBASE: false
-          FILTER_REGEX_EXCLUDE: "^(\\.github/|\\.vscode/|code/samples/).*|CODE_OF_CONDUCT.md|CHANGELOG.md"
+          FILTER_REGEX_EXCLUDE: "^(\\.github/|\\.vscode/|code/samples/|code/web-client/).*|CODE_OF_CONDUCT.md|CHANGELOG.md"
           VALIDATE_BIOME_FORMAT: false
+          VALIDATE_BIOME_LINT: false
           VALIDATE_PYTHON_BLACK: false
           VALIDATE_PYTHON_FLAKE8: false
           VALIDATE_PYTHON_ISORT: false