# FoodBlock Technical Specification

**Version 0.5 | February 2026**

## Abstract

FoodBlock is a minimal, content-addressable data structure built on one axiom (identity is content), three fields (type, state, refs), and six base types that can represent any food industry operation. FoodBlocks are append-only, cryptographically signed, and form provenance chains through hash-linked references.

## The Primitive

A FoodBlock is a JSON object with three fields:

```json
{
  "type": "substance.product",
  "state": { "name": "Sourdough", "price": 4.50, "weight": { "value": 500, "unit": "g" } },
  "refs": { "seller": "a1b2c3...", "origin": "d4e5f6..." }
}
```

- **type**: A string from an open registry, using dot notation for subtypes
- **state**: A key-value object containing the block's data. Schemaless by default. Any valid JSON.
- **refs**: A key-value object mapping named roles to block hashes

The block's identity is derived from its content:

```
id = SHA-256(canonical(type + state + refs))
```

Where `canonical()` produces deterministic JSON: keys sorted lexicographically, no whitespace, no trailing zeros on numbers, NFC Unicode normalisation.

A FoodBlock is immutable. Once created, its hash is its permanent identity.

## Base Types

Six base types classify all food industry operations:

### Entities (things that exist)

- **actor**: Any participant in the food system (farmer, restaurant, retailer, regulator, consumer)
- **place**: Any location (farm, factory, store, warehouse, kitchen, vehicle)
- **substance**: Any food item or material (ingredient, product, meal, surplus, commodity)

### Actions (things that happen)

- **transform**: Any process that changes food (cooking, milling, fermenting, composting, harvesting)
- **transfer**: Any movement of food or value (sale, shipment, donation, subscription, booking)
- **observe**: Any record about food (review, inspection, certification, post, sensor reading)

Subtypes extend base types via dot notation. Examples: `actor.producer`, `place.warehouse`, `substance.product`, `transform.process`, `transfer.order`, `observe.review`, `observe.certification`.

## The Axiom

**A FoodBlock's identity is its content.**

```
id = SHA-256(canonical(type + state + refs))
```

This single principle determines every other protocol behaviour:

1. **Immutability**: If identity is content, then modifying a block changes its identity. Blocks are permanent the moment they are created.

2. **Determinism**: The same content always produces the same identity, regardless of when, where, or by whom it was created.

3. **Deduplication**: Identical content produces identical hashes. The same product listed by different systems resolves to one block.

4. **Tamper evidence**: Any modification produces a completely different hash. Tampering is detectable by anyone who can compute SHA-256.

5. **Offline validity**: Hashing requires no server, no network, no authority. Blocks are valid the moment they are created.

6. **Updates as new blocks**: Since a block cannot be modified, updates create a new block referencing the previous one: `refs: { updates: previous_hash }`.

7. **Provenance by reference**: Blocks reference other blocks by hash. These references form a directed acyclic graph, the provenance graph.

## Provenance Chains

FoodBlocks form provenance chains through refs. Example tracing a loaf of bread:

```
bread (substance.product)
  <- baking (transform.process)
    <- dough (substance.ingredient)
      <- flour (substance.ingredient)
        <- milling (transform.process)
          <- wheat (substance.ingredient)
            <- harvest (transform.harvest)
              <- farm (place.farm)
                <- organic_cert (observe.certification)
```

Each arrow is a ref. Following refs backwards reveals the complete history of any food item. Chain depth equals transparency depth.

## Authentication

Every block can be cryptographically signed by its author using Ed25519 digital signatures:

```json
{
  "foodblock": { "type": "...", "state": {...}, "refs": {...} },
  "author_hash": "abc123...",
  "signature": "def456...",
  "protocol_version": "0.5"
}
```

Any recipient can verify that a block genuinely originated from the claimed author without contacting any central authority.

## Visibility and Privacy

Not all data should be public. FoodBlock separates two distinct concerns:

- **Visibility** determines who can request a block (enforced at query layer through six levels: public, network, sector, chain, direct, private)
- **Cryptography** determines who can read its content (envelope encryption for sensitive fields)

For private content, a two-key envelope encryption scheme protects sensitive fields:
- A Content Key encrypts the block's sensitive fields and never changes
- A Master Key encrypts the Content Key and rotates on access revocation

The block's structural wrapper (type, references, signature) remains unencrypted and visible, allowing verification of existence, position in the provenance graph, and cryptographic signature without exposing confidential details.

## Agent Architecture

Autonomous systems are first-class actors in the FoodBlock protocol:

1. **Registration**: Autonomous systems register through signed actor FoodBlocks with Ed25519 keypairs and scoped capabilities
2. **Permissions**: Scoped by block type, amount caps, auto-approve thresholds, and rate limits
3. **Draft → Approve**: Low-value actions auto-approve. High-value actions queue for human confirmation
4. **Event subscriptions**: Subscribe to block type patterns. New blocks trigger handlers in real time
5. **Memory**: Preferences and learned state stored as append-only `observe.preference` blocks

## Token-Efficient Representation

AI agents process data as tokens. FoodBlock provides two layers:

1. **Integrity layer**: Uses 64-character content hashes, canonical JSON, and deterministic signing for tamper evidence

2. **Reasoning layer**: Provides compact representations optimised for how agents think. FoodBlock Notation (FBN) compresses multi-block responses where:
   - `@a1b2c3d4 = substance.product { name: "Sourdough", price: 4.50 } -> seller: @e5f6a7b8`
   - Short hash prefixes (eight characters instead of sixty-four)
   - Resolved references inline the type and name of every referenced block
   - Plain-English narrative generation available via comprehension operation

## Key Technical Properties

- **Immutability and append-only history**: Nothing is overwritten. Nothing is lost.
- **Offline validity**: A block's identity can be computed anywhere, by anyone, using only the SHA-256 algorithm.
- **Deterministic hashing**: Same data always produces same identity across different systems, languages, and platforms.
- **Verifiable authorship**: Every claim has a cryptographically verifiable author.
- **Selective disclosure**: Businesses control who sees what through visibility levels and encryption.
- **Continuous data streams**: Threshold events, periodic summaries, and cryptographic rollups for sensor data.
- **Data erasure without breaking chains**: Tombstone blocks for GDPR/CCPA compliance.
- **Schema validation**: Optional but verifiable. Protocol is schemaless by default.
- **No consensus mechanism**: Food data requires authenticity, traceability, and interoperability, not scarcity enforcement.

## Deployment Model

The protocol is **federated**, analogous to email:

- No single entity controls the network
- Any organisation can operate its own server
- Participants retain ownership of their data on their own infrastructure
- Blocks reference each other across organisational boundaries
- Discovery through direct exchange, registry listing, and referral
- `.well-known/foodblock` endpoint for peer discovery

## Implementation

Reference implementations available in:
- JavaScript/TypeScript
- Python
- Go
- Swift

Cross-language test vectors verify that all implementations produce identical hashes for identical inputs.

## Licence

FoodBlock is released under the **MIT licence** with no patents, no royalties, and no registration requirements.

---

**For complete technical details, see the full specification:**

- Full technical whitepaper (PDF): https://foodx.network/foodblock-technical-spec-v0.5.pdf
- Protocol documentation: https://foodx.network/protocol
- Reference implementations: https://github.com/FoodXDevelopment/foodblock
- Whitepaper: https://foodx.network/foodblock.md
- Website: https://foodx.network