Metadata-Version: 2.4
Name: svs-solana
Version: 0.2.0
Summary: Python client for SVS: Solana Verification System.
Project-URL: Homepage, https://github.com/CryptoZaddy-dev/solana-verification-system
Project-URL: Documentation, https://github.com/CryptoZaddy-dev/solana-verification-system/tree/codex/solana-verification-mvp/packages/svs-python
Author: SVS
License: Apache-2.0
License-File: LICENSE
Keywords: agent-verification,bot-verification,request-signing,solana,svs
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# svs-solana

Python client for `SVS: Solana Verification System`.

Use this package when a Python trading bot, automation script, or agent runtime needs to submit signed SVS actions without reimplementing HMAC headers, timestamp freshness, request nonces, or production-proof polling.

This is the thin Python adoption layer. It mirrors the public `@svsprotocol/solana` client surface where Python bots need it first:

- HMAC signed request headers compatible with the SVS bot API.
- Signed action submission with automatic replay-protection nonce.
- Signed bot self-test.
- Credential-readiness read.
- Action production-proof status, proof fetch, and polling.
- Verified-agent profile and registry verification for protocols and auditors.

The private dashboard, release tooling, deployment evidence, registry authority, wallets, keys, and local operator files are intentionally not part of this package.

## Install

From PyPI:

```sh
python3 -m pip install svs-solana
```

For local development from this repo:

```sh
python3 -m pip install -e ./packages/svs-python
```

## Environment

```sh
export SVS_SERVER_URL="http://127.0.0.1:4173"
export SVS_BOT_ID="devnet-memo-bot"
export SVS_BOT_API_KEY="svs_..."
export SVS_BOT_REQUEST_SIGNING_SECRET="..."
```

## Submit a Signed Action

```python
import os
from svs_solana import SolanaVerificationClient

svs = SolanaVerificationClient(
    base_url=os.environ["SVS_SERVER_URL"],
    api_key=os.environ["SVS_BOT_API_KEY"],
    request_signing_secret=os.environ["SVS_BOT_REQUEST_SIGNING_SECRET"],
)

readiness = svs.check_bot_readiness(bot_id=os.environ["SVS_BOT_ID"])
if not readiness["ok"]:
    raise RuntimeError(readiness["nextAction"]["message"])

result = svs.submit_action({
    "intent": {
        "botId": os.environ["SVS_BOT_ID"],
        "type": "memo",
        "memo": "verified from Python"
    },
    "policyId": "memo-human-approval"
})

record_id = result["queue"]["record"]["id"]
proof = svs.wait_for_action_production_proof(
    record_id,
    attempts=12,
    interval_seconds=5,
    fetch_proof=True,
)
```

## Verify Request Signing Locally

```python
from svs_solana import create_signed_bot_request

signed = create_signed_bot_request(
    {"intent": {"botId": "bot"}},
    request_signing_secret="secret",
    timestamp="2026-06-02T21:45:00.000Z",
)

print(signed["headers"]["svs-request-signature"])
```

## Verify a Profile or Registry

```python
import json
from svs_solana import (
    verify_verified_agent_profile,
    verify_verified_agent_registry,
)

profile = json.load(open("./data/security/verified-agent-profile.json"))
profile_result = verify_verified_agent_profile(
    profile,
    expected_bot_id="devnet-memo-bot",
    stale_after_ms=24 * 60 * 60 * 1000,
)

registry_result = verify_verified_agent_registry(
    registry_path="./data/verified-agent-registry/registry.json",
    stale_after_ms=24 * 60 * 60 * 1000,
)

if not profile_result["ok"] or not registry_result["ok"]:
    raise RuntimeError("SVS verified-agent trust check failed.")
```

## External Bot Example

```sh
cp examples/external-bots/python-signed-memo-bot.env.example \
  examples/external-bots/python-signed-memo-bot.local.env

PYTHONPATH=./packages/svs-python \
  python3 ./examples/external-bots/python-signed-memo-bot.py \
  --env ./examples/external-bots/python-signed-memo-bot.local.env
```

The example submits a signed memo action with `SolanaVerificationClient`, API-key authentication, HMAC request signing, automatic nonce replay protection, and the same dashboard human-review handoff used by the JavaScript examples. If `SVS_SERIALIZED_TRANSACTION_BASE64` is present, the queued action can also carry a prebuilt memo transaction for wallet approval and broadcast.

Run the package tests:

```sh
npm run sdk:python:check
```

Persist adoption evidence after a live dashboard run:

```sh
npm run sdk:python:adoption-evidence -- --require-production-proof true
```

That writes `data/security/python-sdk-adoption-evidence.json`, proving package hygiene, Python tests, signed request intake, transaction-backed human review, approval, broadcast, custom registry registration, and independent production-proof verification without exposing API keys or signing secrets.
