power_house 0.3.4

Deterministic proofs, portable .pha provenance, Rootprint graphs, and optional quorum networking.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

# Power House Archive (`.pha`) v1

## Status

Normative for Power House v0.3.4.

This document defines the portable Power House Archive v1 JSON format. The
schema identifier is:

```text
power-house/pha/v1
```

A `.pha` artifact has one authoritative Power House core. Optional external
proof attachments may travel with that core, but they do not participate in
Power House identity, proof validity, branching, or equivalence.

## Top-level object

```json
{
  "schema": "power-house/pha/v1",
  "provenance": {},
  "embedded_proof": {
    "protocol": "power-house/sumcheck/v1",
    "public_inputs": {},
    "proof": {}
  },
  "phx_fingerprint": "sha256:<64 lowercase hex characters>"
}
```

| Field | Required | Meaning |
|---|---:|---|
| `schema` | yes | Must equal `power-house/pha/v1`. |
| `provenance` | yes | JSON provenance committed by the core fingerprint. |
| `embedded_proof` | yes | Power House protocol identifier, public inputs, proof, and optional attachments. |
| `phx_fingerprint` | yes | Domain-separated SHA-256 identity of core fields. |

## Embedded proof

`embedded_proof` contains:

| Field | Required | Core-bound |
|---|---:|---:|
| `protocol` | yes | yes |
| `public_inputs` | yes | yes |
| `proof` | yes | yes |
| `external_proof_attachments` | no | **no** |

The Rust field is declared with:

```rust
#[serde(default, skip_serializing_if = "Option::is_none")]
pub external_proof_attachments: Option<Vec<ExternalProofAttachment>>
```

Artifacts that do not use EPA therefore serialize exactly without the field.

## External proof attachment

```json
{
  "id": "external-proof-1",
  "proof_system": "example/external-proof/v1",
  "payload": {},
  "payload_sha256": "sha256:<64 lowercase hex characters>",
  "verifier_hint": "optional verifier name or URI",
  "metadata": {}
}
```

`verifier_hint` and `metadata` are optional and omitted when absent.
`payload_sha256` is SHA-256 over the compact canonical JSON serialization of
`payload`. Built-in attachment verification checks structure and payload
integrity. Cryptographic verification of an external proof system is performed
only by an explicitly supplied external verifier.

Canonical JSON objects use lexicographically sorted keys, UTF-8, and no
insignificant whitespace. JSON numbers in fingerprinted core fields and EPA
payloads must be signed or unsigned integers. Floating-point values are
rejected so independent implementations cannot disagree about number
serialization.

## Core fingerprint

`phx_fingerprint` is:

```text
sha256(
  "power-house:pha:v1:phx-fingerprint\0" ||
  canonical_json({
    "embedded_proof": {
      "proof": embedded_proof.proof,
      "protocol": embedded_proof.protocol,
      "public_inputs": embedded_proof.public_inputs
    },
    "provenance": provenance,
    "schema": schema
  })
)
```

The following are excluded:

- `phx_fingerprint` itself
- `embedded_proof.external_proof_attachments`
- every EPA payload, digest, verifier hint, and metadata value

Adding, removing, reordering, or mutating EPA data cannot change the core
fingerprint. Mutating a core field must change it.

## Verification modes

`PhaArtifact::verify()` validates only the Power House core schema and
fingerprint. It does not read EPA data.

`PhaArtifact::verify_external_proof_attachments()` first validates the core,
then explicitly checks EPA structure and payload integrity.

`PhaArtifact::verify_external_proof_attachments_with(...)` additionally invokes
a caller-supplied verifier for external proof semantics.

No Power House workflow is permitted to require EPA verification for core
validity.

## Conformance

Canonical valid vectors are stored in `conformance/pha-v1`:

- `core-valid.pha`
- `core-with-epa.pha`
- `rootprint-valid.json`
- `manifest.json`

Regenerate and verify them with:

```bash
cargo run --example pha_conformance_vectors
PYTHONPATH=sdk/python python3 -m unittest discover -s sdk/python/tests -v
```

See [Rootprint v1](rootprint.md) for graph identity and
[SDKs](sdk.md) for cross-language interfaces. Security assumptions and
mutation behavior are defined in the
[Provenance Security Model](provenance_security.md).