Skip to main content

Evidence Quick Start

Generate and verify evidence bundles in 5 minutes.

Prerequisites​

Step 1: Install the SDK​

pip install qcos-sdk[evidence]

Step 2: Configure API Key​

export QCOS_API_KEY="qcos_live_your_key_here"

Step 3: Generate Evidence for a Job​

from qcos import Client
from qcos.evidence import EvidenceClient

# First, run an optimization job
client = Client()
job = client.optimize(
    qasm="OPENQASM 2.0; ...",
    backend="ionq_simulator",
    shots=1024,
    options={"evidence": True}  # Enable evidence
)

# Evidence is automatically attached
print(f"Job ID: {job.job_id}")
print(f"Evidence Bundle ID: {job.evidence_bundle_id}")

Step 4: Retrieve Evidence Bundle​

from qcos.evidence import EvidenceClient

evidence = EvidenceClient()

# Get the bundle
bundle = evidence.get("ev_abc123")

print(f"Bundle ID: {bundle.bundle_id}")
print(f"Type: {bundle.type}")
print(f"Timestamp: {bundle.timestamp}")
print(f"Algorithm: {bundle.signature_algorithm}")

Step 5: Verify Evidence​

from qcos.evidence import EvidenceClient

evidence = EvidenceClient()

# Get and verify
bundle = evidence.get("ev_abc123")
verification = evidence.verify(bundle)

print(f"Valid: {verification.valid}")
print(f"Checks:")
for check, result in verification.checks.items():
    status = "✅" if result == "valid" else "❌"
    print(f"  {status} {check}: {result}")

Expected Output:

Valid: True
Checks:
  ✅ signature: valid
  ✅ circuit_hash: valid
  ✅ results_hash: valid
  ✅ timestamp: valid
  ✅ chain: valid

Step 6: Export for Audit​

from qcos.evidence import EvidenceClient

evidence = EvidenceClient()
bundle = evidence.get("ev_abc123")

# Export as JSON (machine-readable)
bundle.export("evidence.json", format="json")

# Export as PDF (human-readable audit document)
bundle.export("audit_report.pdf", format="pdf")

# Export as CBOR (compact binary)
bundle.export("evidence.cbor", format="cbor")

Step 7: Generate Evidence Manually​

For cases where you need to generate evidence after the fact:

from qcos.evidence import EvidenceClient

evidence = EvidenceClient()

# Generate evidence for existing job
bundle = evidence.generate(
    job_id="job_xyz789",
    include_circuit=True,
    include_results=True,
    pqc_algorithm="ML-DSA-65"
)

print(f"New Bundle ID: {bundle.bundle_id}")

Step 8: List Your Evidence​

from qcos.evidence import EvidenceClient

evidence = EvidenceClient()

# List recent bundles
bundles = evidence.list(
    limit=10,
    type="optimization"
)

for b in bundles:
    print(f"{b.bundle_id}: {b.timestamp} ({b.type})")

Complete Example​

#!/usr/bin/env python3
"""Evidence Complete Example"""

from qcos import Client
from qcos.evidence import EvidenceClient

def main():
    # Initialize clients
    qcos = Client()
    evidence = EvidenceClient()

    # Run optimization with evidence
    print("Running optimization...")
    job = qcos.optimize(
        qasm="""
        OPENQASM 2.0;
        include "qelib1.inc";
        qreg q[2];
        creg c[2];
        h q[0];
        cx q[0],q[1];
        measure q -> c;
        """,
        backend="ionq_simulator",
        shots=1024,
        options={"evidence": True, "pqc_signing": True}
    )

    print(f"Job completed: {job.job_id}")

    # Get evidence bundle
    print("\nRetrieving evidence...")
    bundle = evidence.get(job.evidence_bundle_id)

    print(f"Bundle ID: {bundle.bundle_id}")
    print(f"Type: {bundle.type}")
    print(f"Algorithm: {bundle.signature_algorithm}")

    # Verify
    print("\nVerifying evidence...")
    verification = evidence.verify(bundle)

    print(f"Valid: {verification.valid}")
    for check, result in verification.checks.items():
        status = "✅" if result == "valid" else "❌"
        print(f"  {status} {check}")

    # Export
    print("\nExporting evidence...")
    bundle.export("evidence_report.pdf", format="pdf")
    print("Saved to evidence_report.pdf")

    print("\n✅ Evidence workflow complete!")

if __name__ == "__main__":
    main()

REST API Direct Usage​

Get Evidence Bundle​

curl https://api.softquantus.com/api/v2/evidence/ev_abc123 \
  -H "Authorization: Bearer $QCOS_API_KEY"

Verify Evidence​

curl -X POST https://api.softquantus.com/api/v2/evidence/verify \
  -H "Authorization: Bearer $QCOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bundle_id": "ev_abc123"}'

Generate Evidence​

curl -X POST https://api.softquantus.com/api/v2/evidence/generate \
  -H "Authorization: Bearer $QCOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "job_xyz789",
    "include_circuit": true,
    "include_results": true
  }'

Next Steps​

© 2024-2026 SoftQuantus Innovative OÜ