# AITBC Receipt Specification (Draft)

## Overview

This document defines the canonical schema and serialization rules for receipts generated by the AITBC network after miners complete compute jobs. Receipts serve as tamper-evident evidence tying compute usage to token minting events.

## Receipt Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `version` | string | yes | Receipt schema version (e.g., `"1.0"`). |
| `receipt_id` | string | yes | Unique identifier for this receipt. SHOULD be globally unique (UUID or hash). |
| `job_id` | string | yes | Identifier of the coordinator job this receipt references. |
| `provider` | string | yes | Miner address/account that executed the job. |
| `client` | string | yes | Client address/account that requested the job. |
| `units` | number | yes | Compute units earned by the miner (token minting basis). |
| `unit_type` | string | yes | Unit denomination (e.g., `"gpu_seconds"`, `"token_ops"`). |
| `price` | number | optional | Price paid by the client for the job (same unit as `units` if applicable). |
| `model` | string | optional | Model or workload identifier (e.g., `"runwayml/stable-diffusion-v1-5"`). |
| `prompt_hash` | string | optional | Hash of user prompt or workload input to preserve privacy. |
| `started_at` | integer | yes | Unix timestamp (seconds) when the job started. |
| `completed_at` | integer | yes | Unix timestamp when the job completed. |
| `duration_ms` | integer | optional | Milliseconds elapsed during execution. |
| `artifact_hash` | string | optional | SHA-256 hash of the result artifact(s). |
| `coordinator_id` | string | optional | Coordinator identifier if multiple coordinators exist. |
| `nonce` | string | optional | Unique nonce to prevent replay/double minting. |
| `chain_id` | integer | optional | Target chain/network identifier. |
| `metadata` | object | optional | Arbitrary key/value pairs for future extensions. |
| `signature` | object | conditional | Signature object (see below). |

### Signature Object

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `alg` | string | yes | Signature algorithm (e.g., `"Ed25519"`, `"secp256k1"`). |
| `key_id` | string | yes | Identifier of signing key (e.g., `"miner-ed25519-2025-09"`). |
| `sig` | string | yes | Base64url-encoded signature over the canonical receipt bytes. |

Receipts SHOULD be signed by either the miner, coordinator attester, or both depending on trust model. Multiple signatures can be supported by storing them in `metadata.signatures` array.

## Canonical Serialization

1. Construct a JSON object containing all fields except `signature`.
2. Remove any fields with null/undefined values.
3. Sort keys lexicographically at each object level.
4. Serialize using UTF-8 without whitespace (RFC 8785 style).
5. Compute hash as `sha256(serialized_json)` for Ed25519 signing.
6. Attach `signature` object containing algorithm, key ID, and base64url signature over the hash.

## Validation Rules

- `completed_at >= started_at`.
- `units >= 0` and `price >= 0` when present.
- `signature.alg` MUST be one of the network approved algorithms (initially `Ed25519`).
- `chain_id` SHOULD match the target blockchain network when provided.
- Reject receipts older than network-defined retention period.

## Example Receipt (unsigned)

```json
{
  "version": "1.0",
  "receipt_id": "rcpt-20250926-000123",
  "job_id": "job-abc123",
  "provider": "ait1minerxyz...",
  "client": "ait1clientabc...",
  "units": 1.9,
  "unit_type": "gpu_seconds",
  "price": 4.2,
  "model": "runwayml/stable-diffusion-v1-5",
  "prompt_hash": "sha256:cf1f...",
  "started_at": 1695720000,
  "completed_at": 1695720002,
  "artifact_hash": "sha256:deadbeef...",
  "coordinator_id": "coord-eu-west-1",
  "nonce": "b7f3d10b",
  "chain_id": 12345
}
```

Signed form includes:

```json
"signature": {
  "alg": "Ed25519",
  "key_id": "miner-ed25519-2025-09",
  "sig": "Fql0..."
}
```

## Future Extensions

- Multi-signature receipts (miner + coordinator attestations).
- ZK-proof metadata for privacy-preserving verification.
- On-chain receipt anchors with Merkle proofs.