# Enigma Witness Vault

Enigma is a provider-agnostic AI memory custody and proof layer: local vault state is canonical, provider-native memory is cache, and receipts/proof bundles verify Enigma-controlled lifecycle events offline.

Enigma Witness Vault is a small, 3D-printable edge appliance for running that local memory-custody workflow on commodity hardware. It is designed around a Raspberry Pi Zero 2 W, an ATECC608A secure-element sidecar, and a 0.96 in SSD1306 OLED status display, with an optional PN532 NFC reader for local pairing or demo taps.

The box is not a new trust oracle. It is a physical custody and witness surface for Enigma-controlled state: a user can point to a dedicated device that holds the local vault bundle, keeps supported witness/key material on a sidecar where the software path uses it, displays short verification state, and optionally advertises/pairs by NFC. The cryptographic claims still come from Enigma receipts, checkpoints, and offline verifier output.

## Why Raspberry Pi Zero 2 W wins

Pi Zero 2 W is the default platform because Enigma is already a local Node/CLI/MCP/verifier system. The Pi gives the hardware package a real Linux host without forcing a firmware rewrite.

| Option | Why it was considered | Why it is not the default |
| --- | --- | --- |
| Raspberry Pi Zero 2 W | 65 x 30 mm Linux computer with quad-core Arm Cortex-A53, 512 MB RAM, Wi-Fi/BLE, microSD, USB OTG, and a 40-pin header footprint. | Wins: runs Enigma CLI/MCP/verifier directly, supports local files, can drive I2C sidecars, fits the enclosure, and stays inside the $50-$100 commodity build target. |
| ESP32-class MCU | Cheap, small, low-power Wi-Fi/Bluetooth MCU. | Loses for this package: Enigma would need a separate embedded implementation, storage design, verifier port, and operational UI. Good future companion, not the build-ready vault host. |
| NFC-only tag/token | Very cheap and phone-friendly. | Loses as the vault: a tag can carry a URL, pairing nonce, device id, or token metadata pointer, but it cannot run the local vault, emit receipts, verify bundles, or protect local signing flows by itself. |
| Verifier dongle only | Attractive as a small USB accessory. | Loses as the top-level product: it can attest or display status, but it does not provide a durable always-on vault host, local MCP endpoint, or enclosure space for display/NFC/user feedback. |

## What it does with Enigma

The Witness Vault is intended to:

1. Host an Enigma local vault bundle on a dedicated Pi filesystem.
2. Run the local Enigma CLI and, when desired, the MCP server for nearby clients.
3. Store or mediate device witness identity material with the ATECC608A sidecar where the software integration supports it.
4. Show short operational state on the OLED: device ready, vault path present, last receipt/checkpoint status, pairing mode, and error state.
5. Optionally expose NFC for tap-to-pair, tap-to-open-local-docs, or tap-to-reference a public coordination artifact.
6. Export Enigma proof bundles that can be verified offline using Enigma verifier tooling.

Recommended local software path, matching the repository docs:

```sh
cd enigma
enigma init --bundle ./.enigma/bundle.json --subject local-user --display-name "Local user"
enigma remember --bundle ./.enigma/bundle.json --text "Prefers concise technical answers." --purpose user_memory --tags preference
enigma context --bundle ./.enigma/bundle.json --query "technical answers" --purpose local_context --out ./.enigma/context-pack.json
enigma export --bundle ./.enigma/bundle.json --out ./.enigma/export.json
enigma verify --bundle ./.enigma/export.json
```

## What it does not prove

Do not claim more than the hardware and Enigma proof model can support.

The Witness Vault does not prove:

- A model provider deleted internal copies.
- A model forgot training, fine-tuning, hidden personalization, telemetry, or cache state.
- A memory statement is true in the real world.
- Imported provider exports are complete unless the source proves completeness.
- The enclosure is tamper-proof.
- The Pi is free of side channels.
- NFC or token metadata creates custody by itself.
- A relay, gateway, browser, desktop, or cloud service saw no plaintext unless that exact path is instrumented and verified by Enigma receipts/policy.

Honest claim: the device raises local custody and witness assurance for Enigma-controlled state. It makes custody visible, portable, and easier to demo; it does not extend Enigma's proof boundary into unobserved provider systems.

## Hardware package files

Top-level package:

- `README.md` — product concept, claim boundary, package map, and quick build path.
- `RESEARCH_DECISION.md` — source-grounded platform decision and enclosure constraints.
- `BOM.md` — budgeted core and optional NFC bills of materials.
- `WIRING.md` — GPIO/I2C wiring map and sidecar notes.
- `ASSEMBLY.md` — print preparation, hardware assembly, and bring-up sequence.
- `SOFTWARE_INTEGRATION.md` — Pi OS, Enigma install, OLED/NFC/secure-element integration path.
- `DEMO_SCRIPT.md` — demo operator runbook for a live Witness Vault.
- `DEVICE_CLAIMS.md` — approved external language and red-line claims.
- `BUYING_GUIDE.md` — sourcing notes and acceptable substitutions.
- `cad/enigma_witness_vault.scad` — parametric enclosure source.
- `cad/generate_witness_vault_stl.py` — STL generation helper.
- `cad/stl/` — generated printable STL outputs.
- `cad/README_CAD.md`, `cad/bambu_profile_notes.md`, and `cad/BAMBU_STUDIO_VERIFICATION.md` — CAD usage, Bambu X1 Carbon print notes, and local Bambu Studio import evidence.

## Enclosure target

Two enclosure lengths are planned:

- NFC-capable: 86 W x 102 L x 28 H mm.
- No-NFC: 86 W x 78 L x 28 H mm.

The Pi mounts in the lower-left of the NFC variant at `[10.5, 64]`. Pi hole offsets from the Pi origin are `[3.5, 3.5]`, `[61.5, 3.5]`, `[3.5, 26.5]`, and `[61.5, 26.5]`. Use PETG or ASA on the Bambu X1 Carbon. Avoid conductive or carbon-filled filament near the Pi antenna or NFC antenna.

## Quick build path

1. Buy the core BOM first: Pi Zero 2 W, 16-32 GB microSD, ATECC608A breakout, 0.96 in SSD1306 OLED, short I2C cables/wire, micro USB power, M2.5 hardware, and PETG/ASA.
2. Skip NFC on the first build unless the demo requires tap interaction; the no-NFC variant is cheaper, shorter, and simpler.
3. Read `cad/README_CAD.md`, then print the no-NFC STL from `cad/stl/` in PETG or ASA using `cad/bambu_profile_notes.md`.
4. Assemble the printed case using `ASSEMBLY.md`.
5. Wire the Pi, OLED, and ATECC608A using `WIRING.md`; verify address separation: ATECC608A at `0x60`, OLED commonly at `0x3C` or `0x3D`.
6. Install Enigma on the Pi and create a local vault bundle using `SOFTWARE_INTEGRATION.md`.
7. Run a local remember/export/verify flow and use `DEMO_SCRIPT.md` for the operator-facing demo.
8. Add PN532 NFC only after the core vault flow works.

Budget expectation: core commodity build lands around $52-$89 depending on display, power supply, and hardware choices. Optional compact PN532 NFC adds roughly $11-$27 when using a commodity compact module and tags, keeping a careful build near $64-$99; premium large NFC development boards can push the build over $100.