Evidence Bundle: Generate and Verify

In this tutorial, you'll create an audit-ready evidence bundle from a QCOS job execution and verify it using cryptographic proofs. Evidence bundles are essential for compliance, procurement, and audit requirements.

Objective

By the end of this tutorial, you will have:

• ✅ Executed a quantum job with evidence generation enabled
• ✅ Downloaded the evidence.tar.zst bundle
• ✅ Verified the bundle's integrity and authenticity
• ✅ Extracted and inspected the contents

---

Prerequisites

# QCOS CLI v2.1+
softqcos --version

# zstd for decompression (optional, CLI handles it)
brew install zstd  # macOS
# apt install zstd  # Ubuntu

# Authenticated
softqcos auth status

---

What's in an Evidence Bundle?

An evidence bundle contains cryptographically signed proof of:

Component	Description
manifest.json	Job metadata, timestamps, execution context
circuit.qasm	The submitted circuit (OpenQASM 3.0)
results.json	Raw measurement results
backend_snapshot.json	Backend state at execution time
transpilation_log.json	Optimization steps applied
signatures/	ML-DSA signatures for each artifact
merkle_root.txt	Merkle tree root for bundle integrity

---

Step 1: Submit a Job with Evidence Enabled

Create a simple circuit file bell_state.qasm:

// bell_state.qasm
OPENQASM 3.0;
include "stdgates.inc";

qubit[2] q;
bit[2] c;

h q[0];
cx q[0], q[1];

c = measure q;

Submit with evidence generation:

softqcos jobs submit bell_state.qasm \
  --backend softquantus_sim \
  --shots 1024 \
  --evidence \
  --output job_result.json

Output:

📤 Submitting job to softquantus_sim...

✅ Job submitted successfully!

   Job ID: job_7f8a9b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
   Status: QUEUED
   Evidence: ENABLED ✅

   Track: softqcos jobs status job_7f8a9b2c...

---

Step 2: Wait for Completion

Monitor the job:

softqcos jobs status job_7f8a9b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c --wait

Output:

⏳ Waiting for job completion...

   [00:00:05] Status: RUNNING
   [00:00:12] Status: COMPLETED ✅

   Results:
   ├── Counts: {"00": 498, "11": 526}
   ├── Execution time: 1.23s
   └── Evidence bundle: READY

---

Step 3: Download the Evidence Bundle

softqcos evidence download job_7f8a9b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c \
  --output ./evidence.tar.zst

Output:

📥 Downloading evidence bundle...

   Size: 47.3 KB
   Hash: sha3-256:b2c3d4e5f6a7...

✅ Saved to: ./evidence.tar.zst

---

Step 4: Verify the Bundle

Verify integrity and signatures before extracting:

softqcos evidence verify ./evidence.tar.zst

Output:

🔍 Verifying evidence bundle...

[1/4] Archive Integrity
  ├── Format: tar.zst (zstandard compressed)
  ├── Checksum: sha3-256:b2c3d4e5f6a7...
  └── Status: VALID ✅

[2/4] Manifest Validation
  ├── Job ID: job_7f8a9b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
  ├── Backend: softquantus_sim
  ├── Timestamp: 2026-01-04T15:42:33Z
  └── Status: VALID ✅

[3/4] Artifact Signatures (ML-DSA-65)
  ├── manifest.json: VALID ✅
  ├── circuit.qasm: VALID ✅
  ├── results.json: VALID ✅
  ├── backend_snapshot.json: VALID ✅
  └── transpilation_log.json: VALID ✅

[4/4] Merkle Root Verification
  ├── Computed: 8a9b0c1d2e3f4a5b...
  ├── Declared: 8a9b0c1d2e3f4a5b...
  └── Status: MATCH ✅

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ EVIDENCE BUNDLE VERIFIED

   This bundle provides cryptographic proof that:
   • The circuit was executed on softquantus_sim
   • Results are authentic and unmodified
   • Execution occurred at 2026-01-04T15:42:33Z

   Suitable for: Compliance audits, procurement verification
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

Step 5: Extract and Inspect

Extract the bundle:

softqcos evidence extract ./evidence.tar.zst --output ./evidence/

Or manually:

tar -xf evidence.tar.zst -C ./evidence/

Directory structure:

evidence/
├── manifest.json
├── circuit.qasm
├── results.json
├── backend_snapshot.json
├── transpilation_log.json
├── signatures/
│   ├── manifest.json.sig
│   ├── circuit.qasm.sig
│   ├── results.json.sig
│   ├── backend_snapshot.json.sig
│   └── transpilation_log.json.sig
└── merkle_root.txt

---

Step 6: Examine the Manifest

cat evidence/manifest.json | jq .

{
  "version": "1.0",
  "job_id": "job_7f8a9b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "backend": {
    "id": "softquantus_sim",
    "provider": "softquantus",
    "version": "2.1.3"
  },
  "execution": {
    "submitted_at": "2026-01-04T15:42:30Z",
    "started_at": "2026-01-04T15:42:31Z",
    "completed_at": "2026-01-04T15:42:33Z",
    "shots": 1024
  },
  "artifacts": [
    {"name": "circuit.qasm", "hash": "sha3-256:..."},
    {"name": "results.json", "hash": "sha3-256:..."},
    {"name": "backend_snapshot.json", "hash": "sha3-256:..."},
    {"name": "transpilation_log.json", "hash": "sha3-256:..."}
  ],
  "merkle_root": "8a9b0c1d2e3f4a5b...",
  "signed_by": "QCOS Evidence Authority",
  "signature_algorithm": "ML-DSA-65"
}

---

Step 7: Verify Individual Artifacts

Verify a specific file:

softqcos evidence verify-artifact evidence/results.json \
  --signature evidence/signatures/results.json.sig

Output:

✅ Artifact verified
   File: results.json
   Hash: sha3-256:c3d4e5f6a7b8...
   Signature: VALID (ML-DSA-65)

---

Verification Checklist

Artifact	Command	Expected Result
Full bundle	softqcos evidence verify ./evidence.tar.zst	All checks PASS
Manifest	cat evidence/manifest.json | jq .	Valid JSON with job metadata
Results	cat evidence/results.json | jq .counts	Measurement counts
Merkle root	cat evidence/merkle_root.txt	64-char hex string

---

Using Evidence for Compliance

For Auditors

Provide the evidence.tar.zst file along with:

# Generate verification report
softqcos evidence verify ./evidence.tar.zst --output audit-report.json

For Procurement

Evidence bundles prove:

• Authenticity: Job ran on claimed backend
• Integrity: Results haven't been modified
• Timestamp: Execution time is cryptographically attested
• Quantum-Safe: Signatures resist quantum attacks (ML-DSA)

---

Troubleshooting

"Evidence not available"

Evidence must be requested at job submission time:

softqcos jobs submit circuit.qasm --evidence

"Signature verification failed"

Update signing keys:

softqcos keys update

"Merkle root mismatch"

The bundle may be corrupted. Re-download:

softqcos evidence download $JOB_ID --force

---

Next Steps

• ACOS-ISA Certification — Certify backends
• Offline License Validation — Air-gapped operations
• Evidence API Reference — Programmatic access

---

Retention Policy

Evidence bundles are retained for 90 days by default. Enterprise plans offer extended retention and cold storage options.