Skip to content

Federation Root v1

Source schema: doc/schemas/federation-root.v1.schema.json

Data-dir-scoped root config file (the 'federation pack') loaded at daemon startup and merged into runtime configuration. It is the local, signed source of truth for exactly four daemon configuration surfaces: peer_discovery.seeds[], network.seed_directory[], network.seed_directory_trust[], and the sovereign identity-root surface (identity.sovereign_subject_refs[] plus the participant-only compatibility projection identity.sovereign_participant_ids[]). This is a config-registry artifact (same family as seed-directory-trust.v1), not a peer-to-peer wire envelope (contrast node-advertisement.v1), so it follows that family's snake_case field convention rather than the noun/attribute convention used by signed inter-node messages. A federation-root file that carries any field outside this schema MUST be rejected, not silently ignored.

Governing Basis

Project Lineage

Requirements

Stories

Fields

Field Required Shape Description
schema yes const: federation-root.v1 Schema discriminator.
federation_id yes string Network selector this pack describes (chain-id analogy: mainnet/testnet). Distinct from the wire-envelope federation/id used by node-advertisement.v1 and Corpus taxonomy records — see Proposal 076 Open Question 3. A running node has exactly one active federation_id, bound to its data-dir; it is never a multi-valued or per-request field here.
pack_version yes integer Monotonic revision counter for this federation's pack, analogous to node-advertisement.v1's sequence/no. A loader MUST reject a pack whose pack_version is lower than the last one it accepted for this federation_id, to prevent downgrade/replay of a revoked or superseded pack.
issued_at no string Optional timestamp when this pack revision was produced. Diagnostic only; pack_version is the authoritative ordering, not this timestamp.
attestation_roots yes array This federation's OWN canonical top-level anchor(s). NOT a copy of any relay's local Agora Authority authority_roots[] (Solution 021) — those are narrower, per-namespace, per-relay policy that MAY adopt an entry here as their namespace default, but are never required to equal this list.
bootstrap_seed_peers no array This federation's static WSS seed peers (Proposal 014's 'mandatory first bootstrap layer'), resolving to peer_discovery.seeds[]. Deliberately flat — one endpoint per entry, no priority/enabled toggle — to match today's DaemonSeedPeerConfig exactly; richer multi-endpoint peer entries would require enriching that struct first, which this schema does not assume.
seed_directory_bootstrap no array This federation's own canonical default trusted Seed Directories. Each entry fans out to two existing daemon config surfaces at load time: network.seed_directory[] (endpoint/node_id/passport) and network.seed_directory_trust[] (trust_level/weight/passport_ref/policy_ref/endorsement_refs/reputation_ref/enabled). The loader MUST fill network.seed_directory_trust[].federation_id from this pack's own top-level federation_id; it is not repeated per entry here.
federation_service_endorsement_revocations no array Optional signed federation-service-endorsement-revocation.v1 artifacts known at root-pack activation time. Loaders use these revocations when deciding whether inline Seed Directory bootstrap endorsements may confer federation-official status.
custody_policies no array Self-contained organization custody policies referenced by attestation_roots[].custody_policy_ref. MVP loaders resolve policy refs inside this same federation-root pack, so bootstrap does not depend on an external policy registry.
policy_ref no string Optional reference to the policy document governing this federation's root and bootstrap decisions.
endorsement_refs no array Optional references to endorsement facts supporting this pack's trust claims (for example community-elected public-service recognition), carried via the existing reputation-signal.v1 mechanism rather than a new primitive.
signatures yes array Signatures over the canonical payload (every field above, excluding signatures itself). A local, self-authored federation-root file is still signed by its own operator-held root key(s) — 'self-signed' is a valid case, 'unsigned' is not. Which keys and how many are required is governed by whatever custody mode/policy applies to this federation's attestation_roots[] entries (see Proposal 076 section 4 and its resolved custody-mode decision), not by this schema. Runtime threshold evaluation is over unique signing keys, not over externally asserted people or organizations.

Definitions

Definition Shape Description
AttestationRoot object
BootstrapSeedPeer object Mirrors DaemonSeedPeerConfig field-for-field (daemon/src/config.rs:761).
SeedDirectoryBootstrap object Fans out to DaemonSeedDirectoryConfig (daemon/src/config.rs:528) and DaemonSeedDirectoryTrustConfig (daemon/src/config.rs:551) at load time.
CustodyPolicy object
CustodyRule object
Signature object
FederationServiceEndorsement object Embedded form of federation-service-endorsement.v1 used only so a bootstrap Seed Directory can be verified before any directory is trusted. Runtime verification still enforces signature, custody, time, federation, node, and capability invariants.
FederationServiceEndorsementRevocation object Embedded startup-time endorsement revocation. Runtime Seed Directory verification remains authoritative for live feeds; this root-pack form lets startup bootstrap apply known withdrawals before trusting inline official-service proofs.
FederationServiceEndorsementSignature object
## Field Semantics

schema

  • Required: yes
  • Shape: const: federation-root.v1

Schema discriminator.

federation_id

  • Required: yes
  • Shape: string

Network selector this pack describes (chain-id analogy: mainnet/testnet). Distinct from the wire-envelope federation/id used by node-advertisement.v1 and Corpus taxonomy records — see Proposal 076 Open Question 3. A running node has exactly one active federation_id, bound to its data-dir; it is never a multi-valued or per-request field here.

pack_version

  • Required: yes
  • Shape: integer

Monotonic revision counter for this federation's pack, analogous to node-advertisement.v1's sequence/no. A loader MUST reject a pack whose pack_version is lower than the last one it accepted for this federation_id, to prevent downgrade/replay of a revoked or superseded pack.

issued_at

  • Required: no
  • Shape: string

Optional timestamp when this pack revision was produced. Diagnostic only; pack_version is the authoritative ordering, not this timestamp.

attestation_roots

  • Required: yes
  • Shape: array

This federation's OWN canonical top-level anchor(s). NOT a copy of any relay's local Agora Authority authority_roots[] (Solution 021) — those are narrower, per-namespace, per-relay policy that MAY adopt an entry here as their namespace default, but are never required to equal this list.

bootstrap_seed_peers

  • Required: no
  • Shape: array

This federation's static WSS seed peers (Proposal 014's 'mandatory first bootstrap layer'), resolving to peer_discovery.seeds[]. Deliberately flat — one endpoint per entry, no priority/enabled toggle — to match today's DaemonSeedPeerConfig exactly; richer multi-endpoint peer entries would require enriching that struct first, which this schema does not assume.

seed_directory_bootstrap

  • Required: no
  • Shape: array

This federation's own canonical default trusted Seed Directories. Each entry fans out to two existing daemon config surfaces at load time: network.seed_directory[] (endpoint/node_id/passport) and network.seed_directory_trust[] (trust_level/weight/passport_ref/policy_ref/endorsement_refs/reputation_ref/enabled). The loader MUST fill network.seed_directory_trust[].federation_id from this pack's own top-level federation_id; it is not repeated per entry here.

federation_service_endorsement_revocations

  • Required: no
  • Shape: array

Optional signed federation-service-endorsement-revocation.v1 artifacts known at root-pack activation time. Loaders use these revocations when deciding whether inline Seed Directory bootstrap endorsements may confer federation-official status.

custody_policies

  • Required: no
  • Shape: array

Self-contained organization custody policies referenced by attestation_roots[].custody_policy_ref. MVP loaders resolve policy refs inside this same federation-root pack, so bootstrap does not depend on an external policy registry.

policy_ref

  • Required: no
  • Shape: string

Optional reference to the policy document governing this federation's root and bootstrap decisions.

endorsement_refs

  • Required: no
  • Shape: array

Optional references to endorsement facts supporting this pack's trust claims (for example community-elected public-service recognition), carried via the existing reputation-signal.v1 mechanism rather than a new primitive.

signatures

  • Required: yes
  • Shape: array

Signatures over the canonical payload (every field above, excluding signatures itself). A local, self-authored federation-root file is still signed by its own operator-held root key(s) — 'self-signed' is a valid case, 'unsigned' is not. Which keys and how many are required is governed by whatever custody mode/policy applies to this federation's attestation_roots[] entries (see Proposal 076 section 4 and its resolved custody-mode decision), not by this schema. Runtime threshold evaluation is over unique signing keys, not over externally asserted people or organizations.

Definition Semantics

$defs.AttestationRoot

  • Shape: object

$defs.BootstrapSeedPeer

  • Shape: object

Mirrors DaemonSeedPeerConfig field-for-field (daemon/src/config.rs:761).

$defs.SeedDirectoryBootstrap

  • Shape: object

Fans out to DaemonSeedDirectoryConfig (daemon/src/config.rs:528) and DaemonSeedDirectoryTrustConfig (daemon/src/config.rs:551) at load time.

$defs.CustodyPolicy

  • Shape: object

$defs.CustodyRule

  • Shape: object

$defs.Signature

  • Shape: object

$defs.FederationServiceEndorsement

  • Shape: object

Embedded form of federation-service-endorsement.v1 used only so a bootstrap Seed Directory can be verified before any directory is trusted. Runtime verification still enforces signature, custody, time, federation, node, and capability invariants.

$defs.FederationServiceEndorsementRevocation

  • Shape: object

Embedded startup-time endorsement revocation. Runtime Seed Directory verification remains authoritative for live feeds; this root-pack form lets startup bootstrap apply known withdrawals before trusting inline official-service proofs.

$defs.FederationServiceEndorsementSignature

  • Shape: object