96 lines
4.1 KiB
Markdown
96 lines
4.1 KiB
Markdown
# 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.
|