Snevara Traceability Protocol — Specification v0.1 (Draft)

Status: Draft for pilot implementation. Published openly; feedback welcome. Date: June 11, 2026 License: Open license (final choice pending — intent is free implementation by anyone, including competitors).

The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted as described in RFC 2119.

0. Design goals and non-goals

Goals

1. Bind atoms to bits. Every digital claim about a physical good is traceable to a signed, timestamped event with stated evidence and a stated trust level.
2. Make fraud expensive, not impossible. No protocol prevents a determined liar at the moment of capture. This protocol makes lies inconsistent — they must survive countersignatures, mass-balance reconciliation, verifiable random lab sampling, and unannounced audits simultaneously.
3. State uncertainty. Every event, measurement, and lab result carries its method and trust class. Consumers of the data — including our own certification engine — never see “true,” only “attested by X, via device class Y, verified by Z.”
4. Interoperate. The event vocabulary aligns with GS1 EPCIS 2.0 (the standard underlying FSMA 204 tooling and most retailer systems). GS1 identifiers (GLN, GTIN, SSCC) are supported wherever identifiers appear.
5. Privacy by architecture. Commercial and personal data stay off-chain. Only salted commitments (hashes) are anchored publicly. Selective disclosure lets a party prove one fact without revealing its supplier graph.

Non-goals (v0.1)

• Decentralized governance of the protocol itself (Snevara operates the reference reconciliation engine and acts as the escrow oracle; §11.4 acknowledges this and sketches the path out).
• Per-item tracking of low-value units (the protocol tracks lots, containers, and logistics units; unit-level serialization happens only at final packaging).
• Consumer identity. Scans are anonymous; scan-anomaly detection uses location/time only.

1. Terminology

2. Identity and registration

2.1 Actors

• Each actor MUST hold an Ed25519 key pair. The public key, legal identity, and role(s) are registered with the protocol operator after verification (KYB for entities, ID verification for persons).
• Key rotation MUST be supported via a signed rotation event; compromised keys trigger a DEVICE_KEY_COMPROMISE exception (§9) covering all events signed after the declared compromise time.

2.2 Facilities

• A facility registration MUST include: operator actor, geolocation (point or polygon), facility type, and — where applicable — GLN.
• Origin facilities (farms, apiaries) MUST be geolocated to ≤ 100 m accuracy. (EUDR-covered categories require plot-level polygons; see category profiles.)

2.3 Devices

Every measurement-producing device is registered with a class:

• Each reading MUST carry: device id, device class, firmware/app version, calibration status (and last calibration date for measuring instruments).
• Class A devices MUST maintain a monotonic counter and local clock; offline readings are signed locally and synced later (§5.4).
• Certification tier eligibility depends on device class: see §10.2.

2.4 Seals

• Seals MUST be single-use, uniquely serialized, and registered to the issuing batch before distribution.
• A seal serial observed on more than one container, or observed after being recorded broken, MUST raise SEAL_DUPLICATE (critical, §9).

3. Cryptographic conventions

• Serialization: JSON, canonicalized per RFC 8785 (JCS) before hashing or signing.
• Hash: SHA-256. Signatures: Ed25519.
• Identifiers: UUIDv7 for events (time-ordered); artifact ids are URNs — urn:snevara:lot:…, or GS1 equivalents (urn:epc:id:sscc:…) where used.
• Timestamps: RFC 3339, UTC. Every event records both occurred_at (claimed physical time) and recorded_at (server receipt time); the gap between them is itself a monitored signal (§5.4).
• Commitments: A field-level commitment is SHA-256(salt ‖ canonical_field_value) with a per-field random 32-byte salt. Selective disclosure = revealing (salt, value) for chosen fields plus the Merkle path (§5.3).

4. The event model

4.1 Envelope (all events)

{
  "spec_version": "0.1",
  "event_id": "0190a1b2-…(uuidv7)",
  "event_type": "TransferEvent",
  "occurred_at": "2026-08-14T09:21:04Z",
  "recorded_at": "2026-08-14T09:21:11Z",
  "facility": "urn:snevara:facility:…",
  "geo": { "lat": 45.1234, "lon": 7.5678, "accuracy_m": 8, "source": "gnss" },
  "actor": "urn:snevara:actor:…",
  "subjects": ["urn:snevara:lot:…", "urn:snevara:seal:…"],
  "payload": { "…type-specific…": "…" },
  "evidence": [
    { "kind": "photo", "sha256": "…", "device_id": "…", "device_class": "B" },
    { "kind": "sensor_reading", "sha256": "…", "device_id": "…", "device_class": "A" }
  ],
  "prev": ["sha256-of-latest-prior-event-per-subject…"],
  "signatures": [
    { "actor": "urn:snevara:actor:…", "sig": "…" }
  ]
}

Rules:

• prev MUST reference, for every subject artifact, the hash of that artifact’s most recent prior event. This makes each artifact’s history a hash-linked chain; a fork (two events claiming the same predecessor) raises STREAM_FORK (critical).
• Evidence blobs (photos, raw sensor logs, documents) are stored off-chain; only their hashes enter the event.
• geo.source MUST be one of gnss, network, declared. Events with declared geo are device class C regardless of capturing device.
• An event is final once anchored (§5.3). Corrections are made by appending a CorrectionEvent referencing the original — never by mutation. Both remain visible.

4.2 Event types

EPCIS 2.0 mapping shown in parentheses.

4.3 Countersignatures

TransferEvent and IntakeEvent MUST carry signatures from both parties (releasing and receiving actor). The receiving party’s signature attests, at minimum: seal serials sighted and their intact/broken status, and the measured weight. A transfer left un-countersigned for more than 24 h raises UNCOUNTERSIGNED_TRANSFER (major). Disagreement between the parties’ attestations (e.g., giver says sealed, receiver says broken) auto-raises the corresponding seal exception rather than blocking the event — the protocol records conflicts; it does not paper over them.

5. Storage, anchoring, and offline capture

5.1 Off-chain storage

Events and evidence live in the operator’s database, replicated per facility stream. Each actor MAY export their own stream in full at any time (data portability). Nothing in this layer is secret from the artifact’s supply-chain participants; commercial confidentiality boundaries are between different supply chains.

5.2 What goes on-chain

Only: epoch Merkle roots, the seal-registry root, the actor/device registry root, and escrow contract state (§8). No personal data, no commercial quantities, no supplier graphs, on-chain, ever. This is the GDPR boundary: erasure requests can be honored off-chain while anchored commitments (salted hashes) reveal nothing.

5.3 Anchoring

• Events are leaves in a per-epoch Merkle tree, ordered by (facility, recorded_at, event_id).
• Epoch length: 24 h for the pilot; target 1 h at scale. The root is written to a public L2 (chain selection is a §13 open decision; the protocol is chain-agnostic and MUST keep anchoring migratable).
• The operator MUST serve inclusion proofs (event hash → epoch root → chain transaction) via public API. Anyone can verify any disclosed event’s existence and time without operator cooperation beyond the proof.

5.4 Offline and late capture

Rural reality: devices will be offline.

• Class A/B devices MUST sign events locally at capture with their device key and a monotonic counter; occurred_at comes from device time.
• Events synced within 72 h of occurred_at are timely. Later sync raises LATE_SYNC (minor) ≤ 7 days, LATE_SYNC_EXCESSIVE (major) beyond.
• Late events are accepted (history is real even when connectivity isn’t) but: they are flagged on the fact sheet’s evidence trail, they cannot retroactively satisfy escrow release conditions already timed out, and persistently late facilities draw increased sampling (§10.4).

6. Claims and the custody-model algebra

6.1 Claim vectors

A lot’s claim vector is a list of (origin_class, fraction) entries with fractions summing to ≤ 1.0. The remainder, if any, is implicitly unverified.

Origin classes are hierarchical: facility:apiary-17 ⊂ region:X ⊂ country:IN. A claim at a deeper level entails all ancestors. Fact sheets and regulatory exports (e.g., Honey Directive percentages, which are country-level) are projections of the claim vector onto the relevant level.

6.2 Claim creation

Only an OriginEvent at a registered origin facility creates a non-empty claim vector, and only at the granularity that facility’s registration and device class support (§10.2). Everything downstream can only preserve or dilute claims — never strengthen them. This is the protocol’s central asymmetry.

6.3 Custody models

For a TransformEvent with inputs $i$ of quantity $q_i$ and claim vector $C_i$:

• IP (identity preserved): exactly one input lot permitted (plus registered non-provenance additives where the category profile allows, e.g., nothing for honey). $C_{out} = C_{in}$. Output remains IP.
• SG (segregated): all inputs MUST have fully verified claim vectors (sum = 1.0). $C_{out} = \frac{\sum_i q_i C_i}{\sum_i q_i}$. Output is SG: “100% from these N verified origins, in these proportions.”
• MB (mass balance): inputs may mix verified and unverified. Same weighted formula; output carries e.g. “41% verified-origin content” and the fact sheet MUST label it as a facility-level accounting claim, not a per-unit content claim.

The custody model of an output is the weakest model among its inputs (IP > SG > MB). Model upgrades are impossible; downgrades are automatic.

6.4 Registered processes

Every transformation a facility performs MUST be pre-registered as a process with an expected yield interval $[y_{min}, y_{max}]$ (e.g., honey blending: $[0.985, 1.002]$; the small loss is residue, the small gain is measurement noise). Unregistered process = UNREGISTERED_PROCESS exception (major). Yield intervals are set per category profile and tightened from observed data over time.

7. Mass-balance invariants (normative)

The reconciliation engine MUST evaluate these continuously, on every event, for every facility. Violations raise exceptions per §9 with the listed severity.

I-1 — Transform conservation (critical) For every TransformEvent: $\;\; y_{min} \cdot \sum q_{in} \;\le\; \sum q_{out} \;\le\; y_{max} \cdot \sum q_{in}$ using the registered process’s yield interval.

I-2 — Claim conservation (critical) For every TransformEvent and every origin class $o$: $\;\; \sum_{out} q \cdot C(o) \;\le\; \sum_{in} q \cdot C(o) \cdot y_{max}$ Provenance content can never exceed what came in. This is the single rule most provenance fraud dies on.

I-3 — Transit conservation (major at tolerance breach; critical at 3× tolerance) For every transport leg: $\;|w_{intake} - w_{transfer}| \le \tau_{transit} \cdot w_{transfer}$, with $\tau_{transit}$ from the category profile (honey: 0.5%).

I-4 — Serialization bound (critical) For every PackEvent: units packed × unit size ≤ remaining unpacked quantity of the batch lot. A lot’s serialized output can never exceed its mass.

I-5 — Rolling facility conservation (critical) For every facility, origin class $o$, and rolling window $W$ (category profile; honey: 90 days): $\;\; \text{out}_W(o) + \text{inv}_{end}(o) \;\le\; \text{in}_W(o) + \text{inv}_{start}(o) + \varepsilon$ Inventory figures are the facility’s running declarations; physical stock counts at audits (§10.3) MUST reconcile against declared inventory — this closes the loop I-1..I-4 can’t close alone (slow leakage via falsified inventory).

I-6 — Temporal sanity (major) No event may have occurred_at in the future (> 5 min skew); no event on an artifact before its creating event; transport legs must satisfy plausible speed between geolocations (profile parameter; default ≤ 110 km/h ground average).

I-7 — Seal continuity (critical) Every container MUST have an unbroken alternation: sealed → (transfers with seal sighted intact) → seal recorded broken at intake → optionally resealed with a new serial. Any gap (movement of a sealed container without seal attestation, or contents accessed without a recorded break) is a violation.

Quantities compare in a single unit of measure per category (honey: kg). All tolerances ($y$, $\tau$, $\varepsilon$, $W$) live in category profiles, never hard-coded, and every tolerance value is public.

8. Escrow protocol

Purpose: pay upstream suppliers fast on verified delivery — the incentive that recruits the first mile.

The protocol separates the release decision (an attestation computed against anchored events — identical in every jurisdiction) from settlement (how money actually moves — a pluggable profile chosen per deployment).

8.1 Settlement profiles

Under fiat-rails, the on-chain layer records the PO commitment hash and the release attestation — never the funds. Suppliers receive ordinary bank money; no party is required to hold, receive, or understand tokens.

8.2 Lifecycle

1. Funding. Buyer funds the escrow (per the active settlement profile) referencing a purchase order: supplier actor, expected quantity ± tolerance, price, delivery window, and the hash of the agreed terms.
2. Release condition. The reconciliation engine (acting as oracle) attests release when ALL hold:
   • a countersigned IntakeEvent references the PO;
   • all expected seal serials reported intact;
   • $|w_{intake} - w_{PO}| \le$ PO tolerance;
   • intake within the delivery window;
   • no open critical exception on the delivered lots.
3. Payout. On attestation, settlement executes per profile. Target: ≤ 48 h from physical intake (UPI/IMPS settles in seconds once instructed; the pilot measures end-to-end time).
4. Settlement finality. The payout confirmation (e.g., bank UTR / transaction reference) is hashed into a SettlementEvent appended to the stream — payment promises are auditable against anchored data like everything else.
5. Timeout. No qualifying intake within the window + grace → buyer may reclaim escrowed funds per the escrow agreement.
6. Partial/exception path. Broken seal or out-of-tolerance weight does NOT auto-forfeit: the affected delivery enters the dispute flow (§9.3); escrow holds funds until a ResolutionEvent (mutual signature or operator arbitration per the parties’ agreement).
7. Oracle honesty (v0.1 limitation). The operator is the sole oracle. Mitigations now: every attestation embeds the hashes of the events that satisfied the condition, so any party can audit any release against anchored data. Path later: multi-party attestation, then threshold oracles.

On-chain, the record is only: PO hash, actor identifiers, window, and attestation/settlement hashes (plus, under onchain profile only, the funds). Prices and quantities stay off-chain in the PO document (hash-committed).

9. Exceptions, quarantine, and disputes

9.1 Taxonomy

LAB_SUSPICIOUS is deliberately major, not critical: screening methods produce suspicion, not proof (§0.3). A suspicious screen MUST trigger a confirmatory second method on a fresh sample before any LAB_ADULTERATION_CONFIRMED is recorded.

9.2 Quarantine semantics

A quarantined lot, and every downstream lot whose claim vector inherits from it, MUST NOT be packed, and already-packed units’ fact sheets MUST show suspended status in real time. Quarantine is lifted only by a ResolutionEvent.

9.3 Disputes

• Any party to an event may open a dispute on it; the operator may open one on any exception.
• Process: evidence window (7 days, both sides submit) → operator determination, published with reasoning → appeal to the independent reviewer (per certification scheme rules) within 14 days.
• All dispute outcomes are public on the affected artifacts’ history. Dollar disputes on escrow follow the parties’ contract; protocol-status disputes (was the seal broken? does the claim survive?) follow this section.

9.4 Scan anomalies

A unit serial scanned in two locations such that no plausible travel connects them, or a serial scanned with high frequency across many locations, raises SCAN_ANOMALY_CLUSTER against the batch — the counterfeit-label detector. The fact sheet for affected serials shows a warning while under investigation.

10. Certification semantics

10.1 Tiers (normative requirements)

The certificate states tier × custody model (e.g., T4-IP). A certificate is a continuously evaluated status over the rolling window, not an annual snapshot: it is active iff no unresolved critical exceptions touch its scope and all tier requirements held throughout the window.

10.2 Device class gates

• T3+ origin events: class B minimum.
• Condition claims (e.g., “never above 40 °C”): class A telemetry only.
• Class C (manual) data can never raise a tier; it can appear as supplementary context, labeled as such.

10.3 Audit program

• Facility audit: annual, scheduled, full-scope, includes physical inventory count reconciled against declared inventory (closes I-5).
• Origin spot audits: unannounced, on a verifiable random sample (§10.4) of active origin facilities: ≥ 20%/year for T4 scopes, ≥ 10% for T3.
• Auditors MUST NOT have compensation tied to the client’s retention; audit findings enter the stream as AuditEvents like any other evidence.

10.4 Verifiable random sampling

Sampling (lab lots and audit sites) MUST be selected by deterministic public randomness so neither the operator nor the client can predict or steer selection:

seed   = block_hash(anchor_tx of epoch E)          # unknowable before epoch close
score  = HMAC-SHA256(seed, artifact_id)
select = (score / 2^256) < rate

Anyone can recompute the selection after the fact; no one can know it before the anchor transaction confirms. Baseline rates come from the category profile (honey: Appendix B); rates double for 2 windows after any critical exception in scope, decaying after two clean windows.

10.5 Suspension and revocation

• Critical exception → suspended (automatic, ≤ 24 h, public) — suspension is reversible upon resolution.
• Revocation (permanent for the scope) follows the certification scheme’s published procedure: confirmed adulteration, demonstrated falsification of events, or repeated suspension (≥ 3 in 12 months) for the same root cause.
• The registry serves a machine-readable status feed; every fact sheet shows live status and full status history. There is no quiet de-listing.

11. Registry and fact-sheet data contract

11.1 Per-unit fact sheet (public, on scan)

MUST display: tier × custody model; live status + history; claim vector projected to the consumer-relevant level (with percentages); custody chain summary (counts, dates, “all seals intact” or the exceptions); lab tests performed with method and confidence class (including inconclusive — never hidden); last/next audit dates; the “NOT VERIFIED” section enumerating what the certificate does not cover; links to methodology and to the raw inclusion proofs.

MUST NOT display: scores, rankings, adjectives, or any content the brand can purchase.

11.2 Selective disclosure

Supply-chain participants see their own chains fully. Third parties (retailers, regulators) receive disclosure bundles: chosen fields + salts + Merkle paths to anchored roots — provable without exposing the rest of the graph. Regulatory exports (Honey Directive origin percentages; EUDR due-diligence data; FSMA 204 KDE/CTE extracts) are standard projections of this mechanism.

11.3 Privacy

Natural persons appear in public data only as role + registered identifier, never by name unless they opt in. Scan events store coarse location (city-level) and no device identifiers beyond what anomaly detection needs (rotating salted fingerprints, 90-day retention).

11.4 Operator honesty

v0.1 trusts the operator for: event storage, reconciliation execution, oracle attestations, and sampling computation. Every one of these is verifiable after the fact by any party holding the data (anchored roots, public seeds, published methodology) — the design goal is an operator who can be caught, which is the same property we sell to brands. Multi-party oracles and third-party reconciliation auditors are the v0.2+ decentralization path.

12. Versioning and governance

• Spec versions are SemVer; events embed spec_version. Breaking changes require a major version and a published migration note.
• Category profiles version independently (Appendix B is honey/0.1).
• Changes are proposed publicly, with a comment window, and logged. While Snevara is sole maintainer, all adopted changes and their rationale are published — same transparency rule as everything else.

13. Open items for v0.2

1. Anchor chain selection (founder decision; protocol is migratable by design).
2. EUDR plot-polygon schema for the coffee profile (coffee/0.1) — Indian estates/exporters supplying EU buyers.
3. Threshold/multi-party escrow oracle design.
4. ZK-proof selective disclosure (current Merkle scheme leaks structure size; acceptable for v0.1).
5. Device class A reference hardware list and attestation ceremony.
6. Carbon/condition telemetry summarization standard for TransportEvent (currently free-form digest).
7. Reference integrations for fiat-rails settlement providers (India: bank escrow APIs, RBI-regulated payment-aggregator payout APIs); at least two providers to avoid dependency.

Appendix A — Example events (honey pilot)

A.1 OriginEvent — extraction at apiary

{
  "spec_version": "0.1",
  "event_id": "01909f00-7c1a-7d3e-9f00-3a5b1c000001",
  "event_type": "OriginEvent",
  "occurred_at": "2026-12-12T07:42:10Z",
  "recorded_at": "2026-12-12T16:03:48Z",
  "facility": "urn:snevara:facility:apiary-17",
  "geo": { "lat": 30.9010, "lon": 75.8573, "accuracy_m": 6, "source": "gnss" },
  "actor": "urn:snevara:actor:beekeeper-singh",
  "subjects": ["urn:snevara:lot:2026-12-117"],
  "payload": {
    "method": "extraction",
    "quantity": { "value": 184.2, "uom": "KGM" },
    "claim_vector": [{ "origin_class": "facility:apiary-17", "fraction": 1.0 }],
    "device_readings": [
      { "metric": "weight", "value": 184.2, "uom": "KGM", "device_id": "scale-b12", "device_class": "B" }
    ]
  },
  "evidence": [
    { "kind": "photo", "sha256": "9f3c…", "device_id": "app-singh-pixel", "device_class": "B" }
  ],
  "prev": [],
  "signatures": [{ "actor": "urn:snevara:actor:beekeeper-singh", "sig": "…" }]
}

(Note recorded_at − occurred_at ≈ 8 h: offline capture at the apiary, synced in town — timely under §5.4.)

A.2 TransformEvent — blend at packer

{
  "event_type": "TransformEvent",
  "facility": "urn:snevara:facility:packer-malwa",
  "payload": {
    "process_id": "urn:snevara:process:packer-malwa:blend-01",
    "inputs": [
      { "lot": "urn:snevara:lot:2026-12-117", "quantity": { "value": 180.1, "uom": "KGM" } },
      { "lot": "urn:snevara:lot:2026-12-121", "quantity": { "value": 240.0, "uom": "KGM" } }
    ],
    "outputs": [
      { "lot": "urn:snevara:lot:2027-01-204", "quantity": { "value": 418.9, "uom": "KGM" },
        "claim_vector": [
          { "origin_class": "facility:apiary-17", "fraction": 0.429 },
          { "origin_class": "facility:apiary-04", "fraction": 0.571 }
        ],
        "custody_model": "SG" }
    ]
  }
}

(Checks: I-1 — 418.9 ∈ [0.985, 1.002]·420.1 ✓; I-2 — claim fractions are the quantity-weighted inputs ✓; output model SG because two IP inputs pooled.)

Appendix B — Category profile: honey/0.1

Chain template: OriginEvent (extraction) → SealEvent (drum) → TransferEvent → TransportEvent → IntakeEvent (packer) → TransformEvent (blend) → PackEvent (jars) → ScanEvents.

Honey-specific plausibility bound (I-8h): a registered apiary’s seasonal OriginEvent total MUST NOT exceed hives × max_yield_per_hive (regional parameter, public). Prevents the classic laundering move — declaring bought syrup as own harvest. Violation: major; repeated: critical.

End of specification v0.1. Companion documents: Certification Scheme Rules (auditor independence, appeals, and the revocation procedure referenced in §10.5) and the Fee Schedule.