Northroot Proof Engine

Core proof computation and validation library for the Northroot Proof system.

Overview

The Northroot Proof Engine provides foundational cryptographic and validation primitives for the modular proof architecture:

• PoSH (Proof of Shape): Method transformation contracts
• PoX (Proof of Execution): Run evidence and commitments

Features

• Deterministic JSON canonicalization
• SHA-256 hash computation
• ed25519 signature handling
• Input validation functions
• Data shape hashing
• OTEL ID validation (legacy compatibility)

Usage

Add to your Cargo.toml:

[dependencies]
northroot-proof-engine = "0.3.0"

Quick Start

use northroot_proof_engine::{compute_sha256, validate_trace_id};

// Compute SHA-256 hash
let hash = compute_sha256("Hello, world!");
println!("Hash: {}", hash);

// Validate trace ID
match validate_trace_id("tr_01H1234567890") {
    Ok(_) => println!("Valid trace ID"),
    Err(e) => println!("Invalid: {}", e),
}

CLI Demo Tool

The engine includes a CLI tool for demonstrations and validation:

# Run end-to-end workflow demo
cargo run --bin northroot-cli -- demo workflow

# Benchmark hash operations
cargo run --bin northroot-cli -- bench hash

# Validate a proof JSON file
cargo run --bin northroot-cli -- validate tests/golden/pox_span_commitment.json

See CLI Guide for more details.

Example: Creating and Verifying a Span Commitment

use northroot_proof_engine::{
    compute_span_commitment_hash, sign_span_commitment, verify_span_commitment_signature,
    ArtifactRef, MethodRef, SpanCommitment, SpanStatus,
};
use ed25519_dalek::SigningKey;
use rand::rngs::OsRng;

// Create a span commitment
let commitment = SpanCommitment {
    schema_version: "proof.v2".to_string(),
    trace_id: "tr_01H1234567890".to_string(),
    span_id: "sp-0001".to_string(),
    method_ref: MethodRef { /* ... */ },
    data_shape_hash: "sha256:...".to_string(),
    span_shape_hash: "sha256:...".to_string(),
    inputs: vec![],
    outputs: vec![],
    start_time: "2025-11-06T12:00:00.000Z".to_string(),
    end_time: "2025-11-06T12:00:00.042Z".to_string(),
    status: SpanStatus::OK,
    meta: None,
};

// Sign the commitment
let mut csprng = OsRng;
let signing_key = SigningKey::generate(&mut csprng);
let signature = sign_span_commitment(&commitment, &signing_key, "did:key:zExecutor".to_string())?;

// Verify the signature
let verifying_key = signing_key.verifying_key();
let verified = verify_span_commitment_signature(
    &commitment,
    &signature,
    verifying_key.as_bytes(),
)?;

Performance

The engine is optimized for deterministic, fast hash computation and canonicalization. Typical performance characteristics:

• SHA-256: ~100K+ ops/sec (1KB input)
• Canonicalization: ~50K+ ops/sec
• Span Commitment Hash: ~30K+ ops/sec

Run benchmarks with:

cargo bench

Or use the CLI for quick performance testing:

cargo run --bin northroot-cli -- bench hash

See Benchmarks for detailed performance data.

CLI Reference

The northroot-cli tool provides several commands:

• demo workflow - Demonstrates end-to-end PoSH → PoX workflow
• bench hash - Benchmarks hash and canonicalization operations
• validate <file> - Validates proof JSON files

See CLI Guide for complete documentation.

Documentation

• 5W1H Executive Guide - Mathematical foundation and proof architecture
• PoSH Mini Spec - Proof of Shape specification
• PoX Mini Spec - Proof of Execution specification
• Recommended Types - Type recommendations for v0.2
• CLI Guide - Command-line tool usage
• Benchmarks - Performance characteristics and benchmarks

Current: v0.3.0

This version includes CLI tool, enhanced testing, and improved documentation. Breaking changes will require a major version bump.

Development

Setup

# Install git hooks (run once)
./scripts/setup-hooks.sh

Pre-commit Checks

Automatically runs on commit:

• Code formatting check (cargo fmt)

Pre-push Checks

Automatically runs before push:

• Clippy linting (cargo clippy)
• Full test suite (cargo test)
• Release build verification (cargo build --release)

Releasing

1. Update CHANGELOG.md with changes
2. Run the release script:

   ./scripts/release.sh <version>
   # Example: ./scripts/release.sh 0.2.1
   

3. Push the commit and tag:

   git push origin main
   git push origin v<version>
   

GitHub Actions will automatically:

• Run full CI checks
• Publish to crates.io
• Create a GitHub release

Note: You'll need to set the CRATES_IO_TOKEN secret in GitHub repository settings.

License

MIT License - see LICENSE file for details.