feat(solana): Karma Solana SDK — verifiable execution, evidence bundles, x402 payments

[GoldenShihao]

What

Adds packages/karma_solana/ — a standalone Python SDK that plugs Karma's verifiable execution into the Solana agent ecosystem.

• KarmaSolanaVerifier — Full verify → upload → settle pipeline
• SolanaTransactionBuilder — SPL Memo + SPL Transfer transaction construction
• ArweaveUploader / IPFSUploader — Decentralized evidence storage
• SolanaX402Hook — x402 Agent-to-Agent SPL token payments
• 22 tests, 8-step E2E demo — All passing

Architecture

Karma Agent → Signed Receipts → Evidence Bundle
    → Karma Runtime (off-chain verify)
    → Arweave/IPFS (upload)
    → Solana (on-chain memo record, ~0.4s, ~$0.0002)
    → x402 Payment (SPL USDC transfer)

Why

• Solana Grant / Hackathon readiness — Clean, documented, test-covered SDK
• Cross-chain parity — Same API surface as BNB Chain (pip install "bnbagent[karma]")
• Verifiable Execution — Cryptographic proof-of-execution on Solana
• x402 Support — HTTP 402 Agent-to-Agent payments via SPL tokens

BNB Chain vs Solana

Feature	BNB Chain	Solana
Settlement	router.settle()	SPL Memo (~$0.0002)
Tx Speed	~3s	~0.4s
Evidence	BSC calldata	Arweave/IPFS (permanent)
Payment	x402 EVM	x402 SPL
Install	pip install "bnbagent[karma]"	pip install karma-solana

Quickstart

from karma_solana import KarmaSolanaVerifier
from karma.sdk import KarmaClient

verifier = KarmaSolanaVerifier(
    karma_endpoint="https://api.karma.xyz",
    api_key=***
    solana_rpc="https://api.mainnet-beta.solana.com",
)
settlement = await verifier.verify_and_settle(
    task_id="task-solana-001",
    evidence_bundle=bundle,
    signer_keypair=keypair,
)

Security Audit ✅

• api_key stored as _api_key (private), excluded from __repr__
• Keypair signing uses keypair.secret() (32-byte seed, not full 64-byte)
• Float → atomic conversion uses Decimal for precision safety
• SPL Memo payload validated against 566-byte limit
• No secret material logged or exposed in error messages

Checklist

• 22 tests, 100% passing
• 8-step E2E demo validated
• Standalone pyproject.toml — pip install karma-solana
• README with installation, comparison table, architecture diagram
• No new on-chain program required (uses existing SPL Memo)
• Compatible with Karma core SDK style
• Security-reviewed: key handling, precision, memo limits

Related

• Karma Trust Protocol: https://github.com/AtoB101/Karma
• Karma BNB Chain Integration: feat: Add Karma as pluggable verifiable evaluator for ERC-8183 bnb-chain/bnbagent-sdk#33
• ERC-8183: https://eips.ethereum.org/EIPS/eip-8183
• x402: https://x402.org

---

Note

Medium Risk
Introduces a new SDK that signs and submits Solana transactions (memos and SPL transfers) and handles evidence uploads, so bugs could affect on-chain settlement/payment behavior despite being largely additive and test-covered.

Overview
Adds a new packages/karma_solana Python SDK that connects Karma’s off-chain verification (POST /v1/verify) to Solana settlement by hashing evidence bundles, uploading them to Arweave/IPFS (with a mock store for tests), and recording the verdict on-chain via an SPL Memo.

Includes a SolanaTransactionBuilder for memo + SPL token transfer transactions and an SolanaX402Hook that executes and cryptographically signs/verifies x402 (HTTP 402) payments on Solana. Ships with a full demo script, packaging config (pyproject.toml), and a focused test suite covering hashing determinism, verification flows, and evidence-store integration.

^{Reviewed by Cursor Bugbot for commit e7714ee. Bugbot is set up for automated code reviews on this repo. Configure here.}