Ports and Secrets Contract
Production chain guides must document two contracts before deployment: host-network ports and Vault/ExternalSecret paths.
Port governance
Cosmos-style validators in chain deployment repository use hostNetwork: true; port collisions happen at the node level, not only inside Kubernetes. The repo therefore uses a canonical base plus per-chain offset model.
| Chain | Offset / note | Operational implication |
|---|---|---|
| Sei production | Offset 0 | Uses the base Cosmos/Horcrux allocation. |
| Initia production | Offset 200 | Avoids collisions with other host-network validators. |
| Stable production | Offset 300 | Includes Cosmos API/gRPC plus Stable EVM RPC/WebSocket surfaces. |
| Canton | Exempt | Not modeled as host-network validator ports in the same registry. |
| Walrus test environment | Exemption note in registry | Treat public exposure separately from validator host-port governance. |
For every new chain guide, include a port table with: P2P, RPC, REST/API, gRPC, WebSocket, Prometheus, signer, cosigner, and any chain-specific EVM or service ports.
ExternalSecret contract
Vault is the default secret source. The chart templates materialize Kubernetes secrets through ExternalSecret resources.
Cosmos-style chains share the chain-templates.cosmosSecrets contract:
| Secret class | Used by | Required when |
|---|---|---|
| Node key | Validator/full node | Node has persistent identity. |
| Local priv-validator key/state | Validator | signerMode: local. |
| Horcrux shard + ECIES key | Horcrux signer | signerMode: horcrux or signer overlay. |
| Horcrux sign-state | Recovery flow | Sign-state restoration/cutover. |
The standardized Horcrux sign-state path format is:
<protocol>/<network>/horcrux/sign-state/<chain-id>/shards/<ordinal>
The signer-set ID format is:
<protocol>/<network>/<chain-id>/horcrux
Fail-closed rules
- A missing Vault key should block rollout; do not generate placeholder signing material.
- A signer or cosigner path mismatch is an incident, not a warning.
- Ambiguous validator activity should result in no validator signing rather than two validators signing.
- ExternalSecret deletion policy should retain backing secret material unless an explicit key-rotation runbook says otherwise.