ardyn 0.3.1

Official Python client for the Ardyn Liability Verification Substrate API

Ardyn Python SDK

Official Python client for the Ardyn Liability Verification Substrate API.

Installation

pip install ardyn

Quick Start

New customer? Contact [e-mail] to start a pilot. We'll provision your credential. Self-serve onboarding is on the roadmap.

import asyncio
from ardyn import ArdynClient

async def main():
    async with ArdynClient(
        gateway_url="https://api.ardyn.ai",
        api_key="your-api-key",   # obtained from pilot provisioning
    ) as client:
        # Register an agent on AMD SEV-SNP hardware (production path)
        agent = await client.register_agent(
            platform="amd_sev_snp",
            capabilities=["sev_snp_report"],
            public_key="your-ed25519-public-key-hex",
        )
        print(f"Agent ID: {agent.agent_id}")

        # Activate the agent
        activated = await client.activate_agent(agent.agent_id)
        print(f"Agent status: {activated.status}")  # -> Active

        # Create an attestation (issues a DDC)
        attestation = await client.attest(
            tool_name="web_search",
            input_hash="sha256:abc123...",
            output_hash="sha256:def456...",
        )
        print(f"Attestation ID: {attestation.attestation_id}")
        print(f"AEA ID: {attestation.aea_id}")

        # Trustless verify: re-derive the verdict from raw evidence.
        # ZERO server contact, zero trust in Ardyn.
        result = await client.verify_offline(aea_id=attestation.aea_id)
        print(f"Verified: {result['verified']}")
        for check in result.get("details", []):
            print(f"  {check}")

asyncio.run(main())

Trustless Verification

Three call paths, all trustless. Zero trust in Ardyn:

# 1. Fetch by ID: downloads the bundle, re-derives locally
#    One server contact for the bytes; zero trust in Ardyn's verdict
result = await client.verify_offline(aea_id="...")
print(f"Verified: {result['verified']}")
for check in result["details"]:
    print(f"  {check}")

# 2. Auditor path: caller already holds the bundle — ZERO Ardyn contact
result = await client.verify_offline(bundle={...})

# 3. File on disk: bundle stored offline — ZERO Ardyn contact
result = await client.verify_offline(bundle_path="bundle.json")

# Synchronous convenience for scripts
result = client.verify_offline_file("bundle.json")

How it works: All three paths run the standalone ardyn-verify CLI, which re-derives every claim — ARK→ASK→VCEK chain, ECDSA P-384 report signature, report_data binding, issuer Ed25519 signature — from raw hardware evidence. The verifier is not bundled with the SDK. The trust anchor is a verifier you build and inspect from source:

cargo install ardyn-verify         # build from source
cargo install --git https://github.com/ardyn/ardyn-verify

If ardyn-verify is not installed, verify_offline() raises FileNotFoundError with explicit build-from-source instructions.

Where verification happens:

Path	Trust Model	Ardyn Contact	Use Case
client.verify(aea_id)	Trusts gateway (deprecated)	Yes (verdict)	Quick check
client.verify_offline(aea_id="...")	Zero-trust	Yes (bytes only)	Audit
client.verify_offline(bundle={...})	Trustless	None	Court-admissible
client.verify_offline(bundle_path="...")	Trustless	None	Offline auditor
ardyn-verify --input bundle.json	Trustless	None	Raw CLI

Getting an API Key

For pilot clients, Ardyn provisions your tenant directly via POST /v1/tenants (admin key → tenant_id + api_key). Contact [e-mail] to start.

Self-serve onboarding is on the roadmap. Currently, all credentials are admin-provisioned.

Features

• Async-first: Built on httpx for modern async Python
• Type-safe: Full type annotations and dataclass models
• Auto-retry: Exponential backoff on transient failures (3 attempts: 1s, 2s, 4s)
• Connection pooling: Efficient HTTP/2 connection reuse
• Comprehensive errors: Typed exceptions for auth, not-found, validation, and server errors

API Reference

ArdynClient

ArdynClient(
    gateway_url: str,        # Base URL of the Ardyn gateway
    api_key: str,            # API key for authentication
    timeout: float = 30.0,   # Request timeout in seconds
    max_retries: int = 3,    # Max retry attempts
)

Methods

Method	Description
register_tenant(name, config?)	Internal/operator use only (admin route) — customers get credentials via pilot provisioning
register_agent(platform, capabilities, public_key, manifest_signature?, cert_fingerprint?)	Register an agent
activate_agent(agent_id)	Activate your own agent
heartbeat(agent_id, status, uptime_secs, attestations_performed, agent_instance_id?)	Send agent heartbeat
attest(tool_name, input_hash, output_hash, metadata?)	Create attestation
submit_proof(request_id, agent_id, proof_type, proof_data, timestamp, signature, input_hash?, output_hash?)	Submit proof
verify_offline(aea_id, bundle, bundle_path)	Trustless verification — re-derives from raw evidence, zero trust in Ardyn
verify(ddc_id)	Deprecated — use verify_offline() instead
verify_offline_file(path)	Synchronous convenience for offline verification
get_usage(tenant_id)	Get usage statistics
get_settlement(tenant_id, period)	Get settlement details
get_dashboard(tenant_id)	Get dashboard data
health()	Check gateway health

Error Types

• ArdynError - Base exception
• AuthError - Authentication failed (401/403)
• NotFoundError - Resource not found (404)
• ValidationError - Request validation failed (400/422)
• ServerError - Server error (5xx)

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

License

MIT