LensMint POC (Raspberry Pi Focus)

LensMint is a Raspberry Pi-oriented proof of concept that combines:

• deterministic Ed25519 device key generation,
• an Axum API server for mint-related operations,
• and a Slint touch UI for a 3.5-inch Raspberry Pi display (default window 320×240 in ui/main.slint, matching common SPI / small panels).

This README starts with how to run the project, then explains the implementation in this order:

1. key generation mechanism,
2. server and mint pipeline,
3. Slint UI flow on Raspberry Pi.

Clone and Run

1) Clone

git clone https://github.com/anurag-p6/lensmint-poc
cd lensmint-poc

2) Environment setup

Create a .env file in the project root. Minimum required values are chain/operator values:

cp .env.example .env

Then edit .env:

LENS_MINT_RPC_URL=<rpc_url>
LENS_MINT_CHAIN_ID=<chain_id>
LENS_MINT_DEVICE_REGISTRY_ADDRESS=<device_registry_contract>
LENS_MINT_ERC1155_ADDRESS=<erc1155_contract>
LENS_MINT_OPERATOR_KEY=<operator_private_key>

Optional but commonly used:

LENS_MINT_API_PORT=3000
LENS_MINT_API_BIND_HOST=127.0.0.1
LENS_MINT_UI_LIVE_PREVIEW=1
# On Raspberry Pi with hwrng enabled:
# LENS_MINT_ENTROPY_DEVICE=/dev/hwrng

3) Build and run

cargo run

4) Verify

• API health:

  curl http://127.0.0.1:3000/health

• UI:
  • Slint camera interface should open.
  • On Pi + camera, live preview should update when LENS_MINT_UI_LIVE_PREVIEW=1.

---

Implementation Overview

System Architecture

---

1) Key Generation Mechanism

Keygen Diagram

Why this exists

The device needs a stable cryptographic identity so each minted frame can be signed by the same Ed25519 keypair across reboots.

How it works in code

• Startup resolves the key path using ed25519_secret_path(data_dir).
• Default persisted key path:
  • ~/.lensmint/data/ed25519_secret_key.bin
  • or <LENS_MINT_DATA_DIR>/data/ed25519_secret_key.bin when overridden.
• If the key file exists:
  • it must be exactly 32 bytes,
  • secret key is loaded,
  • public key is deterministically re-derived.
• If the key file does not exist:
  • a new signing key is generated from configured entropy,
  • secret key bytes are persisted,
  • public key is derived and stored in runtime state.

Raspberry Pi entropy notes

• Default entropy source: /dev/urandom
• Pi hardware RNG option:
  • LENS_MINT_ENTROPY_DEVICE=/dev/hwrng

This keeps device identity persistent while allowing Pi-specific entropy configuration.

---

2) Server and Mint Pipeline

Startup sequence

main.rs performs:

1. load .env (if present),
2. read config from environment,
3. load/create Ed25519 keypair,
4. initialize chain clients,
5. start Axum API server thread,
6. optionally run API-only mode (LENS_MINT_API_ONLY=1),
7. otherwise start preview thread and Slint UI.

Main endpoints

• GET /health
  simple readiness check.

• POST /mint
  executes the main pipeline:

  1. capture frame bytes,
  2. compute SHA-256 frame hash,
  3. sign hash with device Ed25519 secret key,
  4. derive deterministic demo proof and tx hash values,
  5. return MintResponse with hashes/signature/public key metadata.

Additional endpoints:

• POST /v1/nft/prepare
• POST /v1/chain/register-device
• POST /v1/chain/mint-original
• POST /v1/chain/mint-edition

Frame capture fallback logic

For /mint, capture tries in this order:

1. webcam via nokhwa,
2. Raspberry Pi rpicam-still / libcamera-still,
3. synthetic JPEG frame,
4. final deterministic byte fallback.

This layered fallback keeps the server functional even when camera hardware is missing or temporarily unavailable.

Raspberry Pi server deployment notes

• Prefer running directly on Raspberry Pi OS for reliable camera access.
• Ensure rpicam-still or libcamera-still exists.
• For LAN access:
  • set LENS_MINT_API_BIND_HOST=0.0.0.0,
  • consume API via http://<pi-ip>:<port>.

---

3) Slint UI Flow on Raspberry Pi

Slint Camera UI Preview

Display target

• 3.5-inch touch display. The Slint root LensMintApp uses a fixed 320×240 window (preferred- / min- / max- width and height) so the layout fits compact panels (see ui/main.slint). If your framebuffer differs, change those values and adjust rail widths if needed.
• Camera-style UX:
  • left control rail,
  • center viewfinder,
  • right capture rail.

Runtime flow

• Preview loop pushes RGBA frames to the UI.
• Preview source order:
  1. webcam frame stream,
  2. low-latency libcamera JPEG preview,
  3. synthetic animated preview (if enabled and no camera source).
• UI modes:
  • hero-image mode (default when live preview is disabled),
  • live viewfinder mode (LENS_MINT_UI_LIVE_PREVIEW=1).

Interaction wiring

• Shutter action updates UI hash state based on latest frame.
• Mint action triggers backend call to /mint.
• Status text and hash metadata are updated from API responses.
• Settings sheet allows editing camera_id and NFT title used in requests.

Pi display behavior guidance

• Prefer landscape fullscreen or kiosk mode on the 3.5-inch panel. Match the 320×240 logical size in ui/main.slint, or scale at the OS if the hardware reports another mode.
• Run fullscreen/kiosk so Slint fills the display cleanly.
• Use large touch targets (already reflected in the UI icon rails and capture controls).

---

Frequently Used Environment Variables

• LENS_MINT_API_PORT (default: 3000)
• LENS_MINT_API_BIND_HOST (default: 127.0.0.1)
• LENS_MINT_API_BASE_URL (default: http://127.0.0.1:<port>)
• LENS_MINT_API_ONLY (1 => run server only)
• LENS_MINT_DATA_DIR (override base data dir for persisted key material)
• LENS_MINT_ENTROPY_DEVICE (default /dev/urandom, Pi option /dev/hwrng)
• LENS_MINT_UI_LIVE_PREVIEW (1 => live preview in Slint viewfinder)
• LENS_MINT_SYNTHETIC_PREVIEW (0 => disable synthetic fallback animation)
• LENS_MINT_WEBCAM_INDEX (prioritized webcam index in dev environments)