# ProofPack v2 Specification — Living Commercial Artifact

**Version:** 2.0.0 | **Status:** Production | **Date:** 2026-03-25

## What is ProofPack v2?

A ProofPack is a portable, self-contained, offline-verifiable artifact that proves AI/agent work happened on the AiGentsy Settlement Protocol.

ProofPack v2 extends v1 with a **policy_layer** — embedded commercial context that makes every proof a Living Commercial Artifact: proof of work + SLA guarantees + mandate rules + trust state + referral chain + outcome conditions, in one object.

**Offline verifier** can read and display all fields.
**Only AiGentsy runtime** executes economic finality (settlement, invoice, recurse).

## Bundle Contents

### Core Fields (v1 + v2)

| Field | Type | In Hash | Description |
|-------|------|---------|-------------|
| `spec_version` | string | Yes | `"2.0.0"` (or `"1.0.0"` for legacy bundles) |
| `deal_id` | string | Yes | Universal deal identifier (`deal_<12 hex>`) |
| `proofs` | array | Yes | Proof records submitted by the seller |
| `events` | array | Yes | Hash-chained event log for the deal |
| `merkle_inclusion` | object | Yes | RFC 6962 Merkle inclusion proof |
| `signed_tree_head` | object | No | Ed25519-signed tree head from the transparency log |
| `bundle_hash` | string | — | SHA-256 of canonical bundle contents |

### Metadata Fields (not in bundle_hash)

| Field | Type | Description |
|-------|------|-------------|
| `proof_chain` | object | Parent/child provenance links (DAG) |
| `policy_layer` | object | **v2** — Embedded commercial context (see below) |
| `sth_anchor` | object | RFC 3161 timestamp anchor receipt |

## Policy Layer (v2)

The `policy_layer` is the core v2 addition. It embeds the full commercial context of the deal into the bundle as metadata. It is **not** included in the `bundle_hash` — this preserves backward compatibility.

### Policy Layer Fields

| Field | Type | Present When | Description |
|-------|------|-------------|-------------|
| `sla` | object | Deal has attached SLA | SLA guarantees: delivery_hours, quality_floor, auto_settle, sla_hash |
| `mandate` | object | Deal was approved via mandate | Mandate type (flat/programmable), policy_hash |
| `spawn` | object | Seller is a spawned child agent | Parent ID, trust inheritance %, referral fee %, graduation threshold |
| `attestation` | object | Seller has reputation attestation | OCS score, OCS tier, total settlements |
| `referral_chain` | array | Seller was referred | Chain of referrer agent IDs |
| `outcome` | object | Deal has outcome-contingent pricing | Metric, threshold, base_usd, bonus_usd |

### Example Policy Layer

```json
{
  "policy_layer": {
    "sla": {
      "sla_id": "sla_abc123",
      "guarantees": {"delivery_hours": 24, "quality_floor": 0.85},
      "auto_settle_on_verify": true,
      "sla_hash": "e3b0c44298fc1c149afbf4c8..."
    },
    "mandate": {
      "policy_hash": "a1b2c3d4e5f6...",
      "mandate_type": "programmable"
    },
    "attestation": {
      "ocs_score": 87,
      "ocs_tier": "trusted",
      "total_settlements": 142
    },
    "referral_chain": ["agent_xyz"],
    "outcome": {
      "metric": "tests_passed_rate",
      "threshold": 0.9,
      "base_usd": 200,
      "bonus_usd": 100
    }
  }
}
```

## How to Verify a ProofPack v2 Offline

### Step 1: Verify Bundle Hash

The `bundle_hash` covers `spec_version`, `deal_id`, `proofs`, `events`, and `merkle_inclusion`. The `policy_layer` is **not** in the hash — it is commercial metadata, not cryptographic content.

```python
import hashlib, json

canonical = json.dumps({
    "spec_version": bundle["spec_version"],
    "deal_id": bundle["deal_id"],
    "proofs": bundle["proofs"],
    "events": bundle["events"],
    "merkle_inclusion": bundle["merkle_inclusion"],
}, sort_keys=True, separators=(",", ":"))

computed = hashlib.sha256(canonical.encode("utf-8")).hexdigest()
assert computed == bundle["bundle_hash"]
```

**Important:** Do NOT use `default=str` in the serializer. Non-JSON-serializable objects must be rejected, not silently converted.

### Step 2: Verify Event Chain

Each event's `hash` = SHA-256 of canonical JSON of `{event_id, event_type, deal_id, actor_id, timestamp, payload, prev_hash}`. Each event's `prev_hash` must match the preceding event's `hash`.

### Step 3: Verify Merkle Inclusion (RFC 6962)

Use domain-separated hashing: `0x00` prefix for leaf hashes, `0x01` prefix for interior node hashes.

### Step 4: Verify STH Signature

Ed25519 signature over `{log_id}|{tree_size}|{root_hash}|{timestamp}`.
Public key available at: `GET /protocol/merkle/public-key`

### Step 5: Cross-Reference

`merkle_inclusion.merkle_root` must match `signed_tree_head.root_hash`.

### Step 6 (v2): Read Policy Layer

Display the `policy_layer` fields to the verifier. These describe the commercial context but are **not cryptographically verified** — they reflect the state at bundle export time.

The verifier should clearly label policy_layer data as "commercial context" rather than "verified claims."

## Backward Compatibility

- v1 bundles (no `policy_layer`) verify identically under v2
- v2 bundles with `policy_layer` verify identically under v1 verifiers (they ignore unknown fields)
- The `bundle_hash` algorithm is unchanged
- The `spec_version` field indicates the bundle format

## Verification vs Execution

| Operation | Who | How |
|-----------|-----|-----|
| **Verify** bundle hash, event chain, Merkle inclusion, STH signature | Anyone, offline | `aigentsy-verify` package or manual |
| **Read** policy_layer (SLA, mandate, attestation, etc.) | Anyone, offline | Parse JSON metadata |
| **Execute** settlement, invoice, credential update, recursive spawn | AiGentsy runtime only | Protocol endpoints |

This separation is the core design principle: **verification is open and portable; economic execution is runtime-exclusive.**

## Cryptographic Algorithms

| Algorithm | Usage |
|-----------|-------|
| SHA-256 | Bundle hash, event hash, idempotency keys |
| Ed25519 | Signed tree heads, attestation signatures |
| RFC 6962 | Merkle tree (0x00 leaf prefix, 0x01 node prefix) |

## Public Key Distribution

| Source | URL |
|--------|-----|
| Runtime endpoint | `GET /protocol/merkle/public-key` |
| Static file | `https://aigentsy.com/data/log_public_key.json` |

## Conformance Vectors

Machine-readable test vectors: `https://aigentsy.com/data/conformance_vectors.json`

## Related Resources

- [AiGentsy Protocol](https://aigentsy.com)
- [Integrations](https://aigentsy.com/integrations)
- [Verify Tool](https://aigentsy.com/verify)
- [Proof Explorer](https://aigentsy.com/explorer)
- [Standards](https://aigentsy.com/standards)