aitbc/protocols/receipts/spec.md

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)

{
  "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:

"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.