power_house 0.3.1

# Power House

[![CI](https://img.shields.io/github/actions/workflow/status/JROChub/power_house/ci.yml?branch=main&label=CI)](https://github.com/JROChub/power_house/actions/workflows/ci.yml)
[![crates.io](https://img.shields.io/crates/v/power_house)](https://crates.io/crates/power_house)
[![docs.rs](https://img.shields.io/docsrs/power_house)](https://docs.rs/power_house)
[![license](https://img.shields.io/crates/l/power_house)](LICENSE)

Power House is a deterministic verification and provenance stack for Rust. It
combines structured sum-check proofs, portable `.pha` artifacts, Rootprint
proof-history graphs, commitment-bound sparse workloads, transcript anchoring,
and an optional quorum network.

The primary workflow is **Power House + Rootprint**:

- **Power House Archive (`.pha`)** binds proof data and provenance to a
  deterministic `phx_fingerprint`.
- **Rootprint** provides verifiable navigation, forks, merges, and equivalence
  over `.pha` core identities.
- **External proof attachments (EPA)** are optional transport data and remain
  outside the Power House core fingerprint and Rootprint branch identity.

## Quick Start

```bash
cargo add power_house
```

```rust
use power_house::{prove_with_rootprint, provenance::PhaArtifact};
use serde_json::json;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let artifact = PhaArtifact::new(
        json!({"producer": "example"}),
        "power-house/example/v1",
        json!({"claim": 7}),
        json!({"accepted": true}),
    )?;

    let graph = prove_with_rootprint!(
        label: "main",
        artifact: artifact,
    )?;
    graph.verify()?;
    Ok(())
}
```

Install the `julian` CLI with the network feature:

```bash
cargo install power_house --features net
```

The primary provenance commands are:

```bash
julian rootprint init main.pha --label main --output proof.rootprint.json
julian rootprint fork proof.rootprint.json main candidate.pha --label candidate
julian rootprint navigate proof.rootprint.json candidate
julian rootprint verify proof.rootprint.json
```

## Verification Profiles

| Profile | Public statement | Verifier path | Reproduce |
| --- | --- | --- | --- |
| Constant sum-check | `2^70` Boolean points | 70 field rounds | `cargo run --release --example sextillion_verify` |
| Seeded affine sum-check | `2^4096` Boolean points | 4,096 field rounds | `cargo run --release --example hyperscale_affine` |
| Seeded sparse certificate | `2^1,000,000` Boolean points | `O(n + I log n)` deterministic replay | `cargo run --release --example sparse_record` |
| Committed sparse workload | External `PHSMv1` + `PHCPv1` files | Commitment-bound deterministic replay | `cargo run --release --example committed_workload` |
| Portable provenance | `.pha` core + Rootprint DAG | Fingerprint and graph replay | `cargo run --example rootprint_workflow` |

Here `n` is the number of variables and `I` is the number of nonzero variable
incidences. The proof modes operate on compact algebraic descriptions and do
not allocate the expanded Boolean hypercube.

## Core Formats

| Format | Purpose |
| --- | --- |
| `.pha` v1 | Portable proof, public inputs, provenance, and core fingerprint |
| Rootprint v1 | Deterministic proof-history graph with forks and merges |
| `PHSPv1` | Seeded sparse polynomial certificate |
| `PHSMv1` | Canonical external sparse polynomial |
| `PHCPv1` | Certificate bound to a `PHSMv1` commitment |

Rust and Python consume the same canonical vectors under `conformance/`.
Mutation tests require core changes to reject while proving that EPA mutation
does not alter Power House core validity.

## Reproduce

```bash
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
RUSTDOCFLAGS="-D warnings" cargo doc --all-features --no-deps
cargo test --all-targets --locked
cargo test --all-targets --features net --locked

cargo run --example pha_conformance_vectors
cargo run --example rootprint_workflow
cargo run --release --example sextillion_verify
cargo run --release --example hyperscale_affine
cargo run --release --example sparse_record
cargo run --release --example committed_workload

PYTHONPATH=sdk/python python3 -m unittest discover -s sdk/python/tests -v
python3 scripts/test_sparse_verifier.py
python3 scripts/soundness_budget.py
```

The complete procedure and expected rejection behavior are documented in the
[Verification Guide](docs/verification_guide.md).

## Primary Rust APIs

- [`PhaArtifact`](https://docs.rs/power_house/latest/power_house/provenance/struct.PhaArtifact.html):
  portable Power House core identity.
- [`Rootprint`](https://docs.rs/power_house/latest/power_house/provenance/struct.Rootprint.html):
  deterministic proof-history branching and verification.
- `prove_with_rootprint!`: recommended provenance-aware construction interface.
- [`GeneralSumProof`](https://docs.rs/power_house/latest/power_house/struct.GeneralSumProof.html):
  dense, streaming, constant, and seeded-affine sum-check.
- [`SeededSparseProof`](https://docs.rs/power_house/latest/power_house/struct.SeededSparseProof.html):
  stable `PHSPv1` certificates.
- [`CommittedSparsePolynomial`](https://docs.rs/power_house/latest/power_house/struct.CommittedSparsePolynomial.html)
  and
  [`CommittedSparseProof`](https://docs.rs/power_house/latest/power_house/struct.CommittedSparseProof.html):
  external workload binding.
- [`ProofLedger`](https://docs.rs/power_house/latest/power_house/struct.ProofLedger.html):
  transcript logs, anchors, and quorum reconciliation.

## Python SDK

The bundled zero-dependency Python SDK defaults to pure Power House + Rootprint:

```python
from power_house import create_artifact, new_rootprint, verify_rootprint

artifact = create_artifact(
    {"source": "python"},
    "power-house/example/v1",
    {"claim": 7},
    {"accepted": True},
)
graph = new_rootprint("main", artifact)
verify_rootprint(graph)
```

EPA helpers require an explicit secondary import:

```python
from power_house.external import attach_external_proof
```

See [SDKs](docs/sdk.md) for installation and interoperability tests.

## Network And RPC

The optional `net` feature enables libp2p transport, signed envelopes, data
availability services, governance policies, stake accounting, migration tools,
and a quorum-finalized native JSON-RPC lane.

```bash
julian net start \
  --node-id validator-1 \
  --log-dir ./logs/validator-1 \
  --blob-dir ./data/validator-1 \
  --listen /ip4/0.0.0.0/tcp/7001 \
  --policy ./configs/governance.stake.json \
  --quorum 2 \
  --evm-chain-id 177155 \
  --evm-rpc-listen 127.0.0.1:8545 \
  --key ed25519://<seed>
```

Use `scripts/test_native_rpc_cluster.sh` to verify replica finality and
`scripts/check_rpc.py` to run the external publication gate.

## Documentation

Start with the [Documentation Index](docs/README.md).

- [Power House Archive v1](docs/pha_spec.md)
- [Rootprint v1](docs/rootprint.md)
- [Provenance Security Model](docs/provenance_security.md)
- [Verification Guide](docs/verification_guide.md)
- [SDKs](docs/sdk.md)
- [JULIAN Protocol](JULIAN_PROTOCOL.md)
- [Sparse Security Model](docs/security_model.md)
- [RPC Operations](docs/rpc_operations.md)
- [Production RPC Deployment](docs/production_rpc_deployment.md)
- [Orbital Observatory](docs/orbital_observatory.md)
- [v0.3.0 Benchmark Report](benchmarks/v0.3.0/report.json)

## Public Surfaces

- API documentation: <https://docs.rs/power_house>
- Package: <https://crates.io/crates/power_house>
- Repository: <https://github.com/JROChub/power_house>
- Public verifier: <https://mfenx.com>

## License

MIT OR BSD-2-Clause.