# FoodX - Complete Protocol Reference for LLMs

> This document provides comprehensive information about FoodX and the FoodBlock protocol for AI models and autonomous systems.

## Overview

FoodX is an autonomous food network that people, robots, and machines use to know, act, exchange, and own in the food economy. It is powered by FoodBlock, an open MIT-licensed, content-addressed protocol for food-economy data.

**Our mission**: Decentralising the food economy to increase individual freedom.

**Charity commitment**: 25% of profits to food charities focused on health, nutrition, environmental protection, and animal welfare. Current partners include Action Against Hunger, Beat, Mary's Meals, Slow Food International, Viva!, and WaterAid.

## What FoodX does

### FoodBlock: Open protocol
An MIT-licensed, content-addressed protocol with three fields (type, state, refs) and six base types. Every participant writes blocks in the same format (producers, venues, robots, autonomous systems) creating a shared record of provenance, trust, and exchange that works without proprietary platforms.

### FoodOS: Cognitive architecture
The intelligence layer running in each node. FoodOS ingests natural language, visual input, and sensor data, writes FoodBlocks to the shared record, and coordinates with other nodes, whether operated by people or autonomous systems. It handles memory, permissions, trust evaluation, and the execution of delegated tasks within user-defined boundaries.

### FoodX Node: Product layer
Download a node and access the peer-to-peer food economy. Each node runs FoodOS, reads and writes the shared FoodBlock record, discovers local supply and demand, negotiates exchanges, and coordinates with other participants. Users control identity, memory, and permissions, retaining sovereignty over their data and the ability to exit without abandoning history.

## The FoodBlock Protocol

### Three Fields

```
{
  "type": "substance.product",
  "state": { "name": "Sourdough Loaf", "price": 4.50, "organic": true },
  "refs": { "seller": "a1b2c3...", "flour": "d4e5f6..." }
}
```

- **type** (string): What the block is. Uses dot notation for subtypes.
- **state** (object): The block's properties. Any valid JSON.
- **refs** (object): References to other blocks by their SHA-256 hash.

### Six Base Types

| Type | Description | Example Subtypes |
|------|-------------|-----------------|
| `actor` | Person or organisation | `actor.venue`, `actor.producer`, `actor.agent` |
| `place` | Physical location | `place` (no common subtypes) |
| `substance` | Ingredient or product | `substance.product`, `substance.ingredient` |
| `transform` | Cooking or processing | `transform.recipe` |
| `transfer` | Sale, delivery, donation | `transfer.order`, `transfer.donation` |
| `observe` | Review, cert, measurement | `observe.review`, `observe.certification`, `observe.measurement` |

### Content Addressing

Every block's identity is its content hash:

```
hash = SHA-256(canonical(type, state, refs))
```

Canonical form: deterministic JSON serialization with sorted keys, sorted ref arrays, NFC-normalized type strings. Same content always produces the same hash.

### Immutability and Updates

Blocks are immutable. To update, create a new block with `refs.updates` pointing to the previous block's hash. The latest version in a chain is marked `is_head = true`.

### Provenance

Because blocks reference each other through `refs`, you can trace the full provenance of any item:

```
Sourdough Loaf -> Baking (transform) -> Flour (substance) -> Milling (transform) -> Wheat (substance) -> Farm (actor.producer)
```

## Autonomous-System Infrastructure

FoodBlock has first-class support for autonomous systems:

- Autonomous systems currently use `actor.agent` blocks with Ed25519 keypairs
- Autonomous systems have declared capabilities (e.g. `transfer.order`, `observe.review`)
- Autonomous systems create draft blocks that require human operator approval
- Autonomous systems build memory as `observe.preference` blocks
- Every autonomous-system action is a signed, auditable FoodBlock

### Autonomous-System Registration

```json
{
  "type": "actor.agent",
  "state": {
    "name": "Bakery Inventory System",
    "model": "claude-sonnet",
    "capabilities": ["transfer.order"]
  },
  "refs": { "operator": "<bakery-actor-hash>" }
}
```

### Draft/Approval Flow

1. The autonomous system creates a draft block (`state.draft = true`)
2. Operator reviews and approves or rejects
3. Approved block becomes a confirmed FoodBlock
4. All actions are traceable through the block graph

## API Reference

### Base URL
`https://api.foodx.world`

### Discovery Endpoint
- `GET /.well-known/foodblock` - Returns protocol metadata, supported types, and endpoint list (note: discovery may advertise additional routes; only verified working endpoints are documented here)

### Public Read Endpoints (no authentication required)
- `GET /api/v1/foodblock` - Query blocks (supports `?type=...`, `?limit=...`, and other filters)
- `GET /api/v1/foodblock/{hash}` - Retrieve a specific block by its SHA-256 hash
- `GET /api/v1/foodblock/heads` - Get the latest head blocks (supports `?type=...` filter)

### Write Endpoints (authentication required)
- `POST /api/v1/foodblock` - Create a new block (requires valid block schema with type, state, refs)

### Federation Endpoints
- `POST /.well-known/foodblock/handshake` - Federation handshake for peer-to-peer synchronisation

### Authentication
Authentication is required for write operations and private data access. Public read endpoints are accessible without authentication.

### MCP Server
FoodBlock is available as an MCP (Model Context Protocol) server for AI tool use:
- GitHub: https://github.com/FoodXDevelopment/FoodBlock
- Provides tool-based access to FoodBlock protocol operations

## Use Cases

### Supply Chain Traceability
Track food from farm to fork. Every step (growing, processing, transporting, selling) is a FoodBlock linked to the previous step.

### Autonomous-System Economy
Autonomous systems manage inventory, reorder supplies, monitor temperatures, and negotiate with suppliers through auditable FoodBlocks.

### Trust & Reviews
Compute trust scores from the block graph. Reviews, certifications, and transaction history all contribute to transparent reputation.

### Surplus Food Rescue
Cafes post surplus as `substance.product` blocks. Food banks claim them via `transfer.donation` blocks. Every rescue is logged and traceable.

## SDKs

### JavaScript/Node.js
```bash
npm install @foodxdev/foodblock
```

### Python
```bash
pip install foodblock
```

### MCP Server
```bash
npx foodblock-mcp
```

## Key Links

- Website: https://foodx.network
- About: https://foodx.network/about (Markdown: https://foodx.network/about.md)
- Protocol Docs: https://foodx.network/protocol (Markdown: https://foodx.network/protocol.md)
- Node: https://foodx.network/node (Markdown: https://foodx.network/node.md)
- Mission: https://foodx.network/mission (Markdown: https://foodx.network/mission.md)
- Developer Docs: https://github.com/FoodXDevelopment/FoodBlock
- Interactive Playground: https://foodx.network/app
- API Discovery: https://api.foodx.world/.well-known/foodblock
- OpenAPI Specification: https://foodx.network/openapi.yaml
- Whitepaper v1.5: https://foodx.network/foodblock-whitepaper-v1.5.pdf
- Technical Spec v0.5: https://foodx.network/foodblock-technical-spec-v0.5.pdf
- GitHub Organisation: https://github.com/FoodXDevelopment
- FoodBlock SDK Repo: https://github.com/FoodXDevelopment/FoodBlock
- Discord: https://discord.gg/foodx

## Charity Commitment

FoodX donates 25% of all profits to food charities. Partners focus on three areas: health and nutrition, environmental protection, and animal welfare. Current partners include Action Against Hunger, Beat, Mary's Meals, Slow Food International, Viva!, and WaterAid.

## Contact

- Discord: https://discord.gg/foodx
- GitHub: https://github.com/FoodXDevelopment