FoodBlock

1# FoodBlock
2 
3A content-addressable protocol for universal food data.
4 
5One axiom. Three fields. Six base types. Every food industry operation.
6 
7```json
8{
9  "type": "substance.product",
10  "state": { "name": "Sourdough", "price": 4.50, "allergens": { "gluten": true } },
11  "refs": { "seller": "a1b2c3...", "inputs": ["flour_hash", "water_hash", "yeast_hash"] }
12}
13```
14 
15`id = SHA-256(canonical(type + state + refs))`
16 
17## Why
18 
19The food industry spans 14 sectors — farming, processing, distribution, retail, hospitality, regulation, sustainability, and more. Every sector models food data differently. There is no shared primitive.
20 
21FoodBlock is that primitive. One data structure that can represent a farm harvest, a restaurant menu item, a food safety certification, a cold chain reading, a grocery order, or a consumer review. Same three fields. Same hashing. Same protocol.
22 
23## The Primitive
24 
25Every FoodBlock has exactly three fields:
26 
27| Field | Type | Description |
28|-------|------|-------------|
29| `type` | string | What kind of block (dot-notated subtypes) |
30| `state` | object | The block's data (schemaless, any valid JSON) |
31| `refs` | object | Named references to other blocks by hash |
32 
33Identity is derived from content: `SHA-256(canonical(type + state + refs))`. Same content always produces the same hash, regardless of where or when the block is created.
34 
35## Six Base Types
36 
37**Entities** — things that exist:
38- **actor** — farmer, restaurant, retailer, regulator, consumer, device
39- **place** — farm, factory, store, warehouse, kitchen, vehicle
40- **substance** — ingredient, product, meal, surplus, commodity
41 
42**Actions** — things that happen:
43- **transform** — cooking, milling, harvesting, fermenting, composting
44- **transfer** — sale, shipment, donation, booking, subscription
45- **observe** — review, certification, inspection, post, sensor reading
46 
47Subtypes via dot notation: `actor.producer`, `substance.product`, `observe.review`, `transfer.order`.
48 
49## Install
50 
51```bash
52npm install foodblock
53```
54 
55## Quick Start — `fb()`
56 
57The fastest way to use FoodBlock. Describe food in plain English, get structured blocks back.
58 
59```javascript
60const { fb } = require('foodblock')
61 
62fb("Sourdough bread, $4.50, organic, contains gluten")
63// => { type: 'substance.product', state: { name: 'Sourdough bread', price: { value: 4.5, unit: 'USD' }, organic: true, allergens: { gluten: true } }, blocks: [...] }
64 
65fb("Amazing pizza at Luigi's, 5 stars")
66// => { type: 'observe.review', state: { name: "Luigi's", rating: 5, text: "..." }, blocks: [...] }
67 
68fb("Green Acres Farm, 200 acres, organic wheat in Oregon")
69// => { type: 'actor.producer', state: { name: 'Green Acres Farm', acreage: 200, crop: 'organic wheat', region: 'Oregon' }, blocks: [...] }
70 
71fb("Walk-in cooler temperature 4 celsius")
72// => { type: 'observe.reading', state: { temperature: { value: 4, unit: 'celsius' } }, blocks: [...] }
73 
74fb("Ordered 50kg flour from Stone Mill")
75// => { type: 'transfer.order', state: { weight: { value: 50, unit: 'kg' } }, blocks: [...] }
76```
77 
78No types to memorize. No schemas to configure. No API calls — `fb()` is pure pattern matching, runs locally, costs nothing.
79 
80## Programmatic API
81 
82```javascript
83const fb = require('foodblock')
84 
85// Create a farm
86const farm = fb.create('actor.producer', { name: 'Green Acres Farm' })
87// => { hash: 'e3b0c4...', type: 'actor.producer', state: {...}, refs: {} }
88 
89// Create a product with provenance
90const wheat = fb.create('substance.ingredient', { name: 'Organic Wheat' }, { source: farm.hash })
91const flour = fb.create('substance.product', { name: 'Stoneground Flour' }, { source: wheat.hash })
92const bread = fb.create('substance.product', {
93  name: 'Sourdough',
94  price: 4.50
95}, {
96  seller: bakery.hash,
97  inputs: [flour.hash, water.hash, yeast.hash]
98})
99 
100// Update (creates new block, old one preserved)
101const updated = fb.update(bread.hash, 'substance.product', {
102  name: 'Sourdough',
103  price: 5.00
104}, { seller: bakery.hash })
105// updated.refs.updates === bread.hash
106 
107// Sign and verify
108const keys = fb.generateKeypair()
109const signed = fb.sign(bread, farm.hash, keys.privateKey)
110// signed.protocol_version === '0.4.0'
111const valid = fb.verify(signed, keys.publicKey) // true
112 
113// Provenance chain
114const history = await fb.chain(updated.hash, resolve)
115// [{ price: 5.00 }, { price: 4.50 }] — newest to oldest
116 
117// Validate against schema
118const errors = fb.validate(bread)  // [] if valid
119 
120// Tombstone (GDPR erasure)
121const ts = fb.tombstone(bread.hash, user.hash, { reason: 'gdpr_erasure' })
122 
123// Offline queue
124const queue = fb.offlineQueue()
125queue.create('transfer.order', { total: 12.00 }, { seller: farmHash })
126await queue.sync('https://api.example.com/foodblock')
127 
128// --- Human Interface ---
129 
130// Aliases: use @names instead of hashes
131const reg = fb.registry()
132const myFarm = reg.create('actor.producer', { name: 'Green Acres' }, {}, { alias: 'farm' })
133const myWheat = reg.create('substance.ingredient', { name: 'Wheat' }, { source: '@farm' })
134// '@farm' resolves to myFarm.hash automatically
135 
136// FoodBlock Notation: one-line text format
137const blocks = fb.parseAll(`
138@farm = actor.producer { "name": "Green Acres Farm" }
139@wheat = substance.ingredient { "name": "Wheat" } -> source: @farm
140`)
141 
142// Explain: human-readable narrative from graph
143const story = await fb.explain(bread.hash, resolve)
144// "Sourdough ($4.50). By Green Acres Bakery. Made from Organic Flour (Green Acres Farm)."
145 
146// URIs: shareable block references
147fb.toURI(bread)                          // 'fb:a1b2c3...'
148fb.toURI(bread, { alias: 'sourdough' })  // 'fb:substance.product/sourdough'
149 
150// --- Templates ---
151 
152// Use built-in templates for common patterns
153const chain = fb.fromTemplate(fb.TEMPLATES['supply-chain'], {
154  farm: { state: { name: 'Green Acres Farm' } },
155  crop: { state: { name: 'Organic Wheat' } },
156  processing: { state: { name: 'Stone Milling' } },
157  product: { state: { name: 'Flour', price: 3.20 } }
158})
159// Returns 5 blocks in dependency order, with @alias refs auto-resolved
160 
161// Create custom templates
162const myTemplate = fb.createTemplate('Bakery Review', 'Review a bakery product', [
163  { type: 'actor.venue', alias: 'bakery', required: ['name'] },
164  { type: 'substance.product', alias: 'item', refs: { seller: '@bakery' } },
165  { type: 'observe.review', alias: 'review', refs: { subject: '@item' }, required: ['rating'] }
166])
167 
168// --- Federation ---
169 
170// Discover another FoodBlock server
171const info = await fb.discover('https://farm.example.com')
172// { protocol: 'foodblock', version: '0.4.0', types: [...], count: 142 }
173 
174// Resolve blocks across multiple servers
175const resolve = fb.federatedResolver([
176  'http://localhost:3111',
177  'https://farm.example.com',
178  'https://market.example.com'
179])
180const block = await resolve('a1b2c3...')  // tries each server in order
181```
182 
183## Sandbox
184 
185Try it locally with zero setup:
186 
187```bash
188cd sandbox
189node server.js
190```
191 
192```bash
193# List all blocks
194curl localhost:3111/blocks
195 
196# Filter by type
197curl localhost:3111/blocks?type=substance.product
198 
199# Get head blocks only (latest versions)
200curl localhost:3111/blocks?type=substance.product&heads=true
201 
202# Provenance chain
203curl localhost:3111/chain/<hash>
204 
205# Create a block
206curl -X POST localhost:3111/blocks \
207  -H "Content-Type: application/json" \
208  -d '{"type":"observe.review","state":{"rating":5,"text":"Amazing"},"refs":{"subject":"<product_hash>"}}'
209 
210# Batch create (offline sync)
211curl -X POST localhost:3111/blocks/batch \
212  -H "Content-Type: application/json" \
213  -d '{"blocks":[...]}'
214 
215# Tombstone (content erasure)
216curl -X DELETE localhost:3111/blocks/<hash>
217 
218# Federation discovery
219curl localhost:3111/.well-known/foodblock
220 
221# List templates
222curl localhost:3111/blocks?type=observe.template
223 
224# Natural language entry point
225curl -X POST localhost:3111/fb \
226  -H "Content-Type: application/json" \
227  -d '{"text":"Sourdough bread, $4.50, organic, contains gluten"}'
228 
229# Forward traversal (what references this block?)
230curl localhost:3111/forward/<hash>
231 
232# Natural language → blocks
233curl -X POST localhost:3111/fb \
234  -H "Content-Type: application/json" \
235  -d '{"text":"Sourdough bread, $4.50, organic, contains gluten"}'
236 
237# List vocabularies
238curl localhost:3111/blocks?type=observe.vocabulary
239```
240 
241The sandbox ships preloaded with 47 blocks modelling a complete bakery supply chain — from farm to consumer, including certifications, shipments, cold chain readings, reviews, and operational vocabularies.
242 
243## API
244 
245### `fb(text) → { blocks, primary, type, state, text }`
246 
247The natural language entry point. Pass any food-related text, get FoodBlocks back. Detects intent (product, review, farm, order, certification, reading, process, venue, ingredient), extracts quantities (price, weight, volume, temperature, rating), flags (organic, gluten-free, kosher, etc.), and relationships ("from X", "at Y", "by Z"). No LLM — pure regex pattern matching against built-in vocabularies.
248 
249### `create(type, state, refs) → block`
250 
251Create a new FoodBlock. Returns `{ hash, type, state, refs }`.
252 
253### `update(previousHash, type, state, refs) → block`
254 
255Create an update block that supersedes a previous version. Automatically adds `refs.updates`.
256 
257### `hash(type, state, refs) → string`
258 
259Compute the SHA-256 hash without creating a block object.
260 
261### `chain(hash, resolve, opts) → block[]`
262 
263Follow the update chain backwards. `resolve` is `async (hash) => block | null`.
264 
265### `tree(hash, resolve, opts) → { block, ancestors }`
266 
267Follow ALL refs recursively to build the full provenance tree.
268 
269### `head(hash, resolveForward) → string`
270 
271Find the latest version in an update chain.
272 
273### `sign(block, authorHash, privateKey) → wrapper`
274 
275Sign a block with Ed25519. Returns `{ foodblock, author_hash, signature, protocol_version }`.
276 
277### `verify(wrapper, publicKey) → boolean`
278 
279Verify a signed block wrapper.
280 
281### `generateKeypair() → { publicKey, privateKey }`
282 
283Generate a new Ed25519 keypair for signing.
284 
285### `encrypt(value, recipientPublicKeys) → envelope`
286 
287Encrypt a value for multiple recipients using envelope encryption (Section 7.2).
288 
289### `decrypt(envelope, privateKey, publicKey) → value`
290 
291Decrypt an encryption envelope.
292 
293### `validate(block, schema?) → string[]`
294 
295Validate a block against its declared schema or a provided schema. Returns an array of error messages (empty = valid).
296 
297### `tombstone(targetHash, requestedBy, opts?) → block`
298 
299Create a tombstone block for content erasure (Section 5.4).
300 
301### `offlineQueue() → Queue`
302 
303Create an offline queue for local-first block creation with batch sync.
304 
305### `query(resolve) → Query`
306 
307Fluent query builder:
308 
309```javascript
310const results = await fb.query(resolver)
311  .type('substance.product')
312  .byRef('seller', bakeryHash)
313  .whereLt('price', 10)
314  .latest()
315  .limit(20)
316  .exec()
317```
318 
319### `registry() → Registry`
320 
321Alias registry for human-readable references. Use `@name` in refs instead of hashes.
322 
323### `parse(line) → { alias, type, state, refs }`
324 
325Parse a single line of FoodBlock Notation (FBN).
326 
327### `parseAll(text) → block[]`
328 
329Parse multiple lines of FBN.
330 
331### `format(block, opts?) → string`
332 
333Format a block as FBN text.
334 
335### `explain(hash, resolve) → string`
336 
337Generate a human-readable narrative from a block's provenance graph.
338 
339### `toURI(block, opts?) → string`
340 
341Convert a block to a `fb:` URI. `toURI(block)` → `fb:<hash>`, `toURI(block, { alias: 'name' })` → `fb:<type>/<alias>`.
342 
343### `fromURI(uri) → object`
344 
345Parse a `fb:` URI into `{ hash }` or `{ type, alias }`.
346 
347### `createTemplate(name, description, steps, opts?) → block`
348 
349Create a template block (`observe.template`) that defines a reusable workflow pattern.
350 
351### `fromTemplate(template, values) → block[]`
352 
353Instantiate a template into real blocks. `values` maps step aliases to `{ state, refs }` overrides. `@alias` references between steps are resolved automatically.
354 
355### `TEMPLATES`
356 
357Built-in templates: `supply-chain`, `review`, `certification`.
358 
359### `discover(serverUrl, opts?) → info`
360 
361Fetch a server's `/.well-known/foodblock` discovery document.
362 
363### `federatedResolver(servers, opts?) → resolve`
364 
365Create a resolver that tries multiple servers in priority order. Returns `async (hash) => block | null` with optional caching.
366 
367### `createVocabulary(domain, forTypes, fields, opts?) → block`
368 
369Create a vocabulary block (`observe.vocabulary`) defining canonical field names, types, and natural language aliases for a domain.
370 
371### `mapFields(text, vocabulary) → { matched, unmatched }`
372 
373Extract field values from natural language text using a vocabulary's aliases. Returns matched fields and unmatched terms.
374 
375### `VOCABULARIES`
376 
377Built-in vocabulary definitions: `bakery`, `restaurant`, `farm`, `retail`, `lot`, `units`, `workflow`.
378 
379### `quantity(value, unit, type?) → { value, unit }`
380 
381Create a quantity object. Validates unit against the `units` vocabulary if `type` is provided (e.g. `'weight'`, `'volume'`, `'temperature'`).
382 
383### `transition(from, to) → boolean`
384 
385Validate a workflow state transition against the `workflow` vocabulary's transition map (e.g. `draft→order` is valid, `draft→shipped` is not).
386 
387### `nextStatuses(status) → string[]`
388 
389Get valid next statuses for a given workflow status.
390 
391### `localize(block, locale, fallback?) → block`
392 
393Extract locale-specific text from multilingual state fields. Fields using `{ en: "...", fr: "..." }` nested objects are resolved to the requested locale.
394 
395### `forward(hash, resolveForward) → { referencing, count }`
396 
397Find all blocks that reference a given hash. Returns blocks grouped by ref role.
398 
399### `recall(sourceHash, resolveForward, opts?) → { affected, depth, paths }`
400 
401Trace contamination/recall paths downstream via BFS. Starting from a source block, follows all forward references recursively. Supports `types` and `roles` filters.
402 
403### `downstream(ingredientHash, resolveForward) → block[]`
404 
405Find all downstream substance blocks that use a given ingredient (convenience wrapper around `recall`).
406 
407### `merkleize(state) → { root, leaves, tree }`
408 
409Build a Merkle tree from a state object for selective disclosure.
410 
411### `selectiveDisclose(state, fieldNames) → { disclosed, proof, root }`
412 
413Reveal only specific fields with a Merkle proof that they belong to the block.
414 
415### `verifyProof(disclosed, proof, root) → boolean`
416 
417Verify a selective disclosure proof.
418 
419### `merge(hashA, hashB, resolve, opts?) → block`
420 
421Create a merge block resolving a fork between two update chain heads.
422 
423### `attest(targetHash, attestorHash, opts?) → block`
424 
425Create an attestation block confirming a claim. `opts.confidence`: `verified`, `probable`, `unverified`.
426 
427### `dispute(targetHash, disputerHash, reason) → block`
428 
429Create a dispute block challenging a claim.
430 
431### `trustScore(hash, allBlocks) → number`
432 
433Compute net trust score: attestations minus disputes.
434 
435### `createSnapshot(blocks, opts?) → block`
436 
437Summarize a set of blocks into a snapshot with a Merkle root for archival verification.
438 
439## The Axiom
440 
441**A FoodBlock's identity is its content:** `SHA-256(canonical(type + state + refs))`.
442 
443Everything follows from this:
444- **Immutability** — change content, change identity
445- **Determinism** — same content, same hash, anywhere
446- **Deduplication** — identical products resolve to one block
447- **Tamper evidence** — any modification is detectable
448- **Offline validity** — no server needed to create blocks
449- **Provenance** — refs form a directed graph of history
450 
451Seven operational rules govern the protocol's use:
452 
4531. A FoodBlock has exactly three fields: `type`, `state`, `refs`.
4542. Authentication: `{ foodblock, author_hash, signature, protocol_version }` using Ed25519.
4553. Encrypted state: `_` prefixed keys contain envelope-encrypted values.
4564. Author-scoped updates: only the original author or approved actor may create successors.
4575. Tombstones erase content while preserving graph structure.
4586. Schema declarations are optional.
4597. The protocol is open. No permission required.
460 
461## Canonical JSON
462 
463Deterministic hashing requires deterministic serialization. Aligns with [RFC 8785 (JSON Canonicalization Scheme)](https://tools.ietf.org/html/rfc8785) for number formatting and key ordering:
464 
465- Keys sorted lexicographically at every nesting level
466- No whitespace between tokens
467- Numbers: no trailing zeros, no leading zeros. `-0` normalized to `0`.
468- Strings: Unicode NFC normalization
469- Arrays in `refs`: sorted lexicographically (set semantics)
470- Arrays in `state`: preserve declared order (sequence semantics)
471- Null values: omitted
472- Booleans: `true` or `false`
473 
474## Database Schema
475 
476```sql
477CREATE TABLE foodblocks (
478    hash             VARCHAR(64) PRIMARY KEY,
479    type             VARCHAR(100) NOT NULL,
480    state            JSONB NOT NULL DEFAULT '{}',
481    refs             JSONB NOT NULL DEFAULT '{}',
482    author_hash      VARCHAR(64),
483    signature        TEXT,
484    protocol_version VARCHAR(10) DEFAULT '0.3',
485    chain_id         VARCHAR(64),
486    is_head          BOOLEAN DEFAULT TRUE,
487    created_at       TIMESTAMP DEFAULT NOW()
488);
489```
490 
491Full schema with indexes, author-scoped head trigger, and tombstone trigger: [`sql/schema.sql`](sql/schema.sql)
492 
493## Cross-Language Test Vectors
494 
495[`test/vectors.json`](test/vectors.json) contains 30 known inputs and expected hashes — including tombstone blocks, schema references, vocabulary blocks, attestation blocks, merge blocks, RFC 8785 number edge cases, and more. Any SDK in any language must produce identical hashes for these inputs. If JavaScript and Python disagree, the protocol is broken.
496 
497## Project Structure
498 
499```
500foodblock/
501├── spec/whitepaper.md           Protocol specification (v0.4)
502├── sdk/javascript/              JavaScript SDK (reference implementation)
503│   ├── src/                     block, chain, verify, encrypt, validate, offline, tombstone,
504│   │                            alias, notation, explain, uri, template, federation,
505│   │                            vocabulary, forward, merge, merkle, snapshot, attestation
506│   └── test/                    Test suite (104 tests)
507├── sdk/python/                  Python SDK
508│   ├── foodblock/               block, chain, verify, validate, tombstone,
509│   │                            alias, notation, explain, uri, template, federation,
510│   │                            vocabulary, forward, merge, merkle, snapshot, attestation
511│   └── tests/                   Test suite (80 tests)
512├── sdk/go/                      Go SDK
513│   └── foodblock.go             block, chain, sign/verify, tombstone
514├── sdk/swift/                   Swift SDK
515│   └── Sources/                 block, tombstone
516├── mcp/                         MCP server for AI agent integration (15 tools)
517├── sandbox/                     Local sandbox server
518│   ├── server.js                Zero-dependency HTTP API + federation discovery
519│   └── seed.js                  47-block bakery chain + templates + vocabularies
520├── sql/schema.sql               Postgres schema + triggers
521├── test/vectors.json            Cross-language test vectors (30 vectors)
522└── LICENSE                      MIT
523```
524 
525## Sector Coverage
526 
527The six base types cover all fourteen food industry sectors:
528 
529| Sector | Key Types |
530|--------|-----------|
531| Primary Production | `actor.producer`, `place.farm`, `transform.harvest` |
532| Processing | `actor.maker`, `transform.process`, `observe.inspection` |
533| Distribution | `actor.distributor`, `transfer.shipment`, `observe.reading` |
534| Retail | `substance.product`, `transfer.order` |
535| Hospitality | `actor.venue`, `transfer.booking`, `observe.review` |
536| Food Service | `observe.plan`, `transform.process` |
537| Waste & Sustainability | `actor.sustainer`, `substance.surplus`, `transfer.donation` |
538| Regulation | `actor.authority`, `observe.certification` |
539| Education & Media | `actor.creator`, `observe.post` |
540| Community | `actor.group`, `observe.event` |
541| Health & Nutrition | `actor.professional`, `observe.assessment` |
542| Finance | `transfer.investment`, `observe.market` |
543| Cultural Food | `observe.certification`, `place.region` |
544| Food Technology | `actor.innovator`, `observe.experiment` |
545 
546## License
547 
548MIT — use it however you want.
549 
550## Links
551 
552- [Whitepaper](spec/whitepaper.md) ([PDF](spec/whitepaper.pdf))
553- [Technical Specification](spec/technical-whitepaper.md) ([PDF](spec/technical-whitepaper.pdf))
554- [Test Vectors](test/vectors.json)
555- [Schema](sql/schema.sql)
556- [MCP Server](mcp/README.md)
557