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

# Signed Validator Registry

Release scope: Power House v0.3.4.

The validator registry replaces hardcoded monitoring totals with signed,
policy-admitted, live identity checks. It controls monitoring discovery and
public health reporting. It does not rewrite an existing chain's persisted
consensus set or quorum.

## Security Model

A validator registration contains:

- chain ID
- node ID, operator, and region
- Ed25519 public key
- libp2p peer ID and address
- validator and system metrics endpoints
- issue and expiration times
- an Ed25519 signature from the validator identity

Verification requires all of the following:

1. The registration schema and chain ID are correct.
2. The peer ID is derived from the registered Ed25519 public key.
3. The libp2p address ends in that peer ID.
4. The signature covers every registration field.
5. The registration has not expired.
6. The public key appears in the active validator policy.
7. Node ID, peer ID, public key, and metrics endpoint are unique.
8. The live metrics endpoint reports the same node ID, peer ID, public key,
   and chain ID.

An ordinary connected peer cannot increase the validator count. A signed but
unadmitted identity cannot increase it either.

## Create A Registration

Run this on a protected operator machine with the validator key:

```bash
julian validator-registry create \
  --key /etc/powerhouse/validator-4.key \
  --node-id validator-4 \
  --operator "Example Operator" \
  --region fra1 \
  --p2p-address /dns4/validator-4.example/tcp/7001/p2p/<peer-id> \
  --metrics-url http://validator-4.internal:9100/metrics \
  --system-metrics-url http://validator-4.internal:9101/metrics \
  --output validator-4.registration.json
```

The output contains no private key. Keep metrics endpoints restricted to the
monitoring network.

## Assemble And Verify

```bash
julian validator-registry assemble \
  --registration validator-1.registration.json \
  --registration validator-2.registration.json \
  --registration validator-3.registration.json \
  --policy /etc/powerhouse/native-validators.json \
  --output /etc/powerhouse/validator-registry.json

julian validator-registry verify \
  /etc/powerhouse/validator-registry.json \
  --policy /etc/powerhouse/native-validators.json
```

The production cluster generator performs these steps automatically.

## Reconciliation

`powerhouse-validator-registry.timer` runs every 15 seconds. Its reconciler:

- verifies every signature and policy admission before changing discovery
- probes validators concurrently
- checks the live identity metric against the signed registration
- writes Prometheus file-discovery and public status state atomically
- preserves the last known-good discovery files if registry verification fails

The public API reports dynamic `validators_healthy`, `validators_total`,
`peer_connections`, and `validator_registry` fields. `peer_connections`
remains a link observation count and is not used as validator membership.

## Adding A Validator

Validator admission is a controlled protocol operation:

1. Approve the validator identity through the network membership process.
2. Apply the compatible consensus-set transition to every validator.
3. Obtain and verify the new validator's signed registration.
4. Assemble and deploy the updated registry.
5. Confirm live identity and health before advertising the new total.

Do not add an identity only to the monitoring registry and call it a consensus
validator. Current finalized state must remain compatible with the admitted
validator set.