HolyAxiom Documentation

HolyAxiom is a system for creating cryptographic proofs of physical reality. A Moment is a sensor snapshot — time, location, media — sealed with a hardware-attested signature and anchored on-chain.

Architecture

Sensors (GPS, IMU, Camera, Audio, Clock)
  ↓
ha-chip (trust boundary — raw sensor data never leaves)
  ├── EntropyPool (256-byte XOR rolling pool)
  ├── SensorBus   (5 entropy streams)
  ├── AIAttestor  (7 anomaly detectors)
  └── ProofSealer (ECDSA P-256, IndexedDB key)
  ↓
HolyAxiomSession → MomentChain → ProofPackage
  ↓
Stele DSL → TypeChecker → Interpreter → Compiler
  ↓
Solidity require() → Base blockchain

Key concepts

Quickstart

1. Run ProofLens in browser

cd /Users/jc/Documents/ProofLens
npm run ha        # serves holyaxiom-app on port 4000

Open http://localhost:4000 — hit Record, let it run for 10+ seconds, stop. A ProofPackage is saved to localStorage.

2. Use the Stele playground

http://localhost:4000/language.html

Write a Stele proof, hit ▶ Run. TypeCheck, Interpret against a demo ProofPackage, and compile to Solidity — all in the browser.

3. Run the JavaScript API

import { stele } from './stele/index.js';

const source = `
  proof Session("demo") {
    requires L1
    at Time(1716422400000 ± 200ms) from Clock("system-clock")
    at Place(37.7749°N, 122.4194°W ± 50m) from GPS("gps-api")
    attested Score(85) by Chip("ha-chip-v1") level L1
  }
`;

// Run against a real ProofPackage
const result = stele.run(source, proofPackage);
console.log(result.valid);   // true/false
console.log(result.score);   // 0-100
console.log(result.passed);  // ClaimResult[]

// Compile to Solidity
import { proofToSolidity } from './stele/index.js';
const { solidity } = proofToSolidity(proofPackage);
console.log(solidity);       // Solidity source

The Moment — Properties A–E

Every Moment satisfies five cryptographic properties:

Stele — Introduction

Stele is HolyAxiom's formal language for expressing claims about physical reality. Hardware level is encoded in the type system, not checked at runtime. A proof that claims L2 but only provides L1 evidence is rejected at compile time.

The name comes from stone stelae — the ancient stone pillars used to record laws and events in permanent, public form. A Stele program is the cryptographic equivalent.

Stele Grammar

program     := proof_decl*

proof_decl  := 'proof' 'Session' '(' string ')' '{' statement* '}'

statement   := at_stmt
             | captures_stmt
             | attested_stmt
             | requires_stmt

at_stmt     := 'at' claim 'from' source
claim       := time_claim | place_claim
time_claim  := 'Time' '(' number '±' number 'ms' ')'
place_claim := 'Place' '(' lat ',' lon '±' number 'm' ')'
lat         := number '°' ('N' | 'S')
lon         := number '°' ('E' | 'W')

captures_stmt := 'captures' media 'signed' 'Device' '(' string ')'
media         := 'Video' '(' 'hash:' string ')' | 'Audio' '(' 'hash:' string ')'

attested_stmt := 'attested' 'Score' '(' number ')' 'by' 'Chip' '(' string ')' ['level' level]

requires_stmt := 'requires' level

source := ('Clock' | 'GPS' | 'CSAC' | 'NTP' | 'IMU') '(' string ')'
level  := 'L0' | 'L1' | 'L2' | 'L3'

Type System

The TypeChecker infers a minimum hardware level from the statements in the proof, then checks it against any requires declaration.

// Each statement raises the inferred level:
Time ± > 100ms             → L0
Time ± ≤ 100ms             → L1  (warning if system clock)
Time ± ≤ 1ms from CSAC    → L2

Place ± ≥ 20m              → L0
Place ± 5-20m              → L1
Place ± < 5m               → L2  (warning: RTK GPS required)

Device("ha-chip-*")        → L1
attested … level L2        → L2

// RequiresStatement asserts the minimum:
requires L1
// → type error if inferred level < L1

Stele Compiler

The compiler generates Solidity require() statements from a typechecked Stele AST.

import { compile, parse, typecheck } from './stele/index.js';

const decls      = parse(source);
const typeResult = typecheck(decls);
const solidity   = compile(decls, typeResult);

// Or use the shortcut:
import { proofToSolidity } from './stele/index.js';
const { solidity, stele, level, warnings } = proofToSolidity(proofPackage);

The generated Solidity function can be dropped into any verifier contract:

// Generated output:
function verifyProof_sanFranciscoSunrise(
    uint256 timestamp,    // unix milliseconds
    int256  lat,          // latitude ×1e6
    int256  lon,          // longitude ×1e6
    uint32  accuracyM,    // GPS accuracy in metres
    bytes32 mediaHash,    // SHA-256 of recording
    address deviceKey,    // signer public key
    uint8   trustScore,   // 0-100
    uint8   hardwareLevel // 0=L0 1=L1 2=L2 3=L3
) public pure returns (bool) {
    require(hardwareLevel >= 1, "SteleRequires: L1 required");
    require(timestamp >= 1716422200000 && timestamp <= 1716422600000, "SteleTime: ...");
    require(lat >= 37724800 && lat <= 37824800 && lon >= -122469400 && lon <= -122369400, "StelePlace: ...");
    require(trustScore >= 85, "SteleAttest: trust score below threshold");
    return true;
}

HolyAxiomSession API

import { HolyAxiomSession } from './holyaxiom-core/index.js';

const session = new HolyAxiomSession();

// Start recording
await session.start();  // requests camera + mic

// ... recording runs, moments are created every second ...

// Stop and get proof
const pkg = await session.stop();
// pkg: ProofPackage

console.log(pkg.sessionId);       // string
console.log(pkg.momentCount);     // number
console.log(pkg.recordingHash);   // SHA-256 hex string
console.log(pkg.chain);           // MomentChain

// Export
const json    = pkg.exportJSON();
const payload = pkg.blockchainPayload();
pkg.saveLocal();                  // saves to localStorage

ha-chip — Trust Boundary

The ha-chip module enforces the core security invariant: raw sensor data never reaches the application CPU. All entropy mixing, anomaly detection, and signing happen inside the chip boundary.

import { HolyAxiomChip, ChipRefusalError } from './ha-chip/chip.js';

const chip = new HolyAxiomChip();
await chip.boot('my-session-id');  // 1500ms entropy warmup

try {
  const bundle = await chip.captureBundle(mediaHash);
  // bundle: { signature, hash, publicKeyHex, trustScore, flags, ... }
} catch (err) {
  if (err instanceof ChipRefusalError) {
    console.log('Chip refused:', err.attestation.flags);
    // SPOOFED_GPS, REPLAY_ATTACK, LOW_ENTROPY, etc.
  }
}

// Upgrade to hardware (when ATECC608B is connected)
chip.upgradeToHardware('atecc608b');