AZ-022 — Concrete Genesis Package v1

Status

Acest document definește pachetul genesis concret pentru ATLAS ZERO.

AZ-016 a definit specificația genesis la nivel conceptual și normativ. AZ-018 până la AZ-021 au definit:

vault-ul securizat,
manifesturile,
atestările,
pipeline-ul de build și release.

AZ-022 răspunde la întrebarea: cum arată exact pachetul genesis care poate fi distribuit, verificat, admis în vault, inclus în release și încărcat de noduri pentru bootstrap de rețea?

Scopul documentului este să fixeze:

structura concretă a pachetului genesis;
lista fișierelor obligatorii;
manifesturile și atestările obligatorii;
regulile de derivare a hash-urilor și rădăcinilor;
regulile de validare înainte de bootstrap;
integrarea cu release package și validator bootstrap.

Acest document se bazează pe:

AZ-002 până la AZ-021, cu accent direct pe AZ-016, AZ-019, AZ-020 și AZ-021.

Termeni:

MUST = obligatoriu
MUST NOT = interzis
SHOULD = recomandat puternic
MAY = opțional

1. Obiectiv

AZ-022 răspunde la 10 întrebări precise:

Ce fișiere intră în pachetul genesis?
Care sunt obligatorii și care sunt opționale?
Cum se leagă între ele prin hash-uri și manifest?
Cum se dovedește că pachetul corespunde exact genesis_hash și chain_id?
Cum se leagă validator bootstrap de genesis?
Cum se leagă pachetul de release și mainnet approval?
Cum validează un nod pachetul înainte de start?
Cum se detectează coruperea, substituția sau amestecul de fișiere?
Cum se versionează și cum se supersedează un genesis package înainte de lansare?
Cum evităm ideea periculoasă de „genesis informal” răspândit în mai multe variante?

2. Principii

2.1 One package, one origin

Un pachet genesis concret MUST reprezenta o singură origine normativă de rețea.

2.2 Package identity is hash-bound

Identitatea pachetului MUST fi derivată din manifestul și artefactele sale canonice, nu din nume de arhivă sau din descrieri umane.

2.3 No partial truth

Un nod MUST NOT trata un subset de fișiere drept „suficient” dacă lipsesc componente obligatorii pentru validare.

2.4 Genesis package is a release-grade artifact

Pachetul genesis MUST fi tratat ca artefact TIER_4 / constituțional:

strict admission,
strict attestation,
strict manifest,
zero overwrite,
snapshot after publication.

2.5 Bootstrap must be reproducible

Orice operator conform SHOULD putea reconstrui:

genesis_hash
chain_id
derived roots
validator bootstrap view din același pachet.

3. Package classes

3.1 Allowed package classes

ATLAS ZERO SHOULD suporta:

GENESIS_PACKAGE_MAINNET
GENESIS_PACKAGE_PUBLIC_TESTNET
GENESIS_PACKAGE_PRIVATE_TESTNET
GENESIS_PACKAGE_DEVNET

3.2 Rule

Pachetul MUST ancora clar network_class. Un pachet de devnet MUST NOT fi confundabil cu unul de mainnet.

4. Package identity

4.1 Core identity

Fiecare pachet genesis MUST avea:

genesis_package_id
package_manifest_id
package_manifest_root
genesis_hash
chain_id

4.2 Derivation

genesis_package_id = H("AZ:GENESIS_PACKAGE:" || canonical_genesis_package_manifest)

4.3 Rule

Dacă două pachete au același genesis_hash, dar manifest/pachet diferit, aceasta SHOULD fi tratată ca anomalie severă până la clarificare.

5. Package top-level structure

5.1 Recommended physical layout

genesis_package/
  manifest/
  genesis/
  validators/
  parameters/
  registries/
  policies/
  machines/
  witnesses/
  attestations/
  docs/
  checksums/

5.2 Rule

Structura fizică poate varia doar dacă manifestul definește clar mapping-ul. V1 SHOULD prefera această structură pentru predictibilitate.

6. Mandatory package files

6.1 Minimum required files

Un pachet genesis MUST conține cel puțin:

manifest/genesis_package_manifest.json sau canonical equivalent
genesis/genesis_spec.blob
genesis/derived_roots_commitment.blob
genesis/chain_identity.blob
validators/genesis_validator_set.blob
parameters/genesis_parameter_state.blob
registries/genesis_registry_bundle.blob
policies/genesis_policy_bundle.blob
attestations/genesis_attestation_bundle.blob
checksums/package_checksums.blob

6.2 Conditional mandatory files

Dacă feature-uri relevante sunt active la launch, package MUST include și:

machines/genesis_machine_bundle.blob
witnesses/genesis_witness_bundle.blob

6.3 Rule

Dacă un câmp din GenesisSpec referă un bundle, acel bundle MUST exista în package.

7. Optional package files

7.1 Allowed optional files

Pachetul MAY include:

human-readable manifest
operator notes
launch instructions
validator onboarding docs
provenance notes
duplicate checksum formats for external tooling

7.2 Rule

Fișierele opționale MUST NOT schimba identitatea normativă a package-ului. Norma rămâne în manifest + fișierele canonice.

8. Genesis package manifest

8.1 Canonical structure

GenesisPackageManifest {
  version_major
  version_minor

  package_class
  package_id
  target_network_class
  target_chain_name_hash
  target_genesis_hash
  target_chain_id

  included_artifacts_root
  required_artifact_entries
  package_scope_hash
  compatibility_hash
  attestation_root
  notes_hash?
}

8.2 RequiredArtifactEntry

RequiredArtifactEntry {
  artifact_role_class
  artifact_id
  content_hash
  canonical_hash
  required
}

8.3 artifact_role_class examples

genesis_spec
derived_roots_commitment
chain_identity
validator_set
parameter_state
registry_bundle
policy_bundle
attestation_bundle
machine_bundle
witness_bundle
checksum_bundle

8.4 Rule

The package manifest MUST list every normative package component exactly once per role where uniqueness is expected.

9. Genesis spec blob

9.1 Purpose

Acesta este fișierul normativ central care encodează GenesisSpec din AZ-016.

9.2 Rule

genesis/genesis_spec.blob MUST be canonical, self-consistent and sufficient to derive:

genesis_hash
chain_id
initial state derivation inputs

9.3 Rule

Any secondary human-readable copy is advisory only.

10. Derived roots commitment blob

10.1 Purpose

Conține DerivedRootsCommitment din AZ-016.

10.2 Rule

Acest fișier MUST include:

genesis_hash
parameter_root
validator_root
asset_root
allocation_root
policy_root
machine_root
witness_root
governance_root
feature_flag_root
initial_state_root

10.3 Rule

Nodul MUST recompute these roots and compare exactly.

11. Chain identity blob

11.1 Purpose

Conține forma canonicală a ChainIdentity.

11.2 Rule

This blob MUST match:

chain_id derived from genesis spec
target_chain_id in package manifest
any release scope lock used for launch

12. Validator set bundle

12.1 Purpose

Conține intrările validatorilor inițiali și, dacă permis, bootstrap committee data.

12.2 Structure

GenesisValidatorSetBundle {
  bundle_version
  validator_entries_root
  validator_entries
  bootstrap_committee_entries?
}

12.3 validator_entries

Fiecare entry MUST include:

validator_id
identity_policy_ref
role key refs
stake amount
role flags
eligibility flags

12.4 Rule

The bundle MUST reconcile exactly with validator state derivable from genesis_spec.

13. Parameter state bundle

13.1 Purpose

Conține view explicit al parameter state active at genesis.

13.2 Structure

GenesisParameterStateBundle {
  bundle_version
  protocol_version
  consensus_parameter_entries
  economic_parameter_entries
  bvm_parameter_entries
  witness_parameter_entries
  governance_parameter_entries
  agent_control_parameter_entries
  feature_flag_entries
  parameter_root
}

13.3 Rule

This bundle MUST be consistent with:

genesis_spec
derived_roots_commitment
registry bundle where parameter classes/types are referenced

14. Registry bundle

14.1 Purpose

Pachetul inițial de registries normative.

14.2 Included registries SHOULD include

statement type registry
proof type registry
governance parameter registry
capability tier registry
fault family registry
runbook/risk registry roots if protocol-relevant
BVM family/feature registry refs if needed

14.3 Structure

GenesisRegistryBundle {
  bundle_version
  registry_entries: [RegistryEntry]
  registry_root
}

14.4 Rule

Any registry referenced by genesis parameter state MUST be present or referenced canonically here.

15. Policy bundle

15.1 Purpose

Conține politicile inițiale critice.

15.2 Included policies SHOULD include

treasury policy
recovery reserve policy
governance bootstrap policy
emergency bootstrap policy if present
genesis asset policies
any protocol-native witness issuer policies
validator identity policies if packaged inline

15.3 Structure

GenesisPolicyBundle {
  bundle_version
  policy_entries
  policy_root
}

15.4 Rule

Policy root MUST reconcile with genesis-derived state.

16. Machine bundle

16.1 Conditionality

Mandatory only if genesis deploys machines.

16.2 Included entries

For each machine:

machine_id
code_hash
abi_hash
initial_state_root
permission surface
bounds summary
rent/prepay state
policy refs

16.3 Structure

GenesisMachineBundle {
  bundle_version
  machine_entries
  machine_root
}

16.4 Rule

No machine may appear in derived roots unless machine bundle and genesis spec agree.

17. Witness bundle

17.1 Conditionality

Mandatory only if genesis includes witness records.

17.2 Structure

GenesisWitnessBundle {
  bundle_version
  witness_entries
  witness_root
}

17.3 Rule

Witness entries MUST follow normal witness canonical rules. No special hidden genesis-only witness semantics allowed.

18. Attestation bundle

18.1 Purpose

Carries the release-grade attestations for the package.

18.2 SHOULD include at minimum

hash confirmation for package-critical artifacts
security review attestation
approved_for_release attestation
approved_for_mainnet attestation for mainnet package
genesis custodian approval where policy requires
optional reproducibility/provenance references

18.3 Structure

GenesisAttestationBundle {
  bundle_version
  attestation_entries
  attestation_root
}

18.4 Rule

For mainnet genesis package, missing final approval attestations MUST be blocker.

19. Checksum bundle

19.1 Purpose

Operational convenience layer for verifying package integrity quickly.

19.2 Rule

Checksum bundle is auxiliary and MUST NOT override canonical artifact identity records.

19.3 Structure

PackageChecksumBundle {
  bundle_version
  checksum_entries: [PackageChecksumEntry]
}

PackageChecksumEntry {
  artifact_role_class
  artifact_id
  content_hash
  byte_size
}

19.4 Rule

Any checksum mismatch is severe, but canonical verification still depends on artifact identity and manifest.

20. Human-readable docs

20.1 Allowed docs

May include:

docs/package_manifest_human.md
docs/validator_bootstrap_notes.md
docs/operator_verification_guide.md

20.2 Rule

These docs MUST be clearly marked advisory. They MUST NOT be required to derive normative truth.

21. Package manifest root derivation

21.1 Required artifacts root

required_artifact_entry_hash_i =
  H("AZ:GENESIS_PACKAGE_ARTIFACT_ENTRY:" || canonical_required_artifact_entry_i)

included_artifacts_root = MerkleRoot(required_artifact_entry_hash_0 ... hash_n)

21.2 attestation_root

Derived from canonical attestation entry hashes or attestation bundle root reference, depending on packaging choice.

21.3 package_scope_hash

SHOULD bind:

network class
chain_id
genesis_hash
package_class

21.4 Rule

Two package manifests with different included artifacts MUST NOT produce same package identity.

22. Package validation pipeline

22.1 A node or operator MUST validate in this order:

decode package manifest
verify manifest type/version
load required artifact entries
verify physical presence of required files
recompute content_hash and canonical_hash for each
verify artifact role uniqueness rules
validate genesis spec blob
recompute genesis_hash
validate chain identity blob against genesis_hash
validate derived roots commitment and recompute roots
validate validator set bundle and root
validate parameter state bundle and root
validate registry and policy bundles
validate machine/witness bundles if present
validate attestation bundle
verify package manifest roots
verify package scope lock consistency
derive final package verification verdict

22.2 Rule

Failure at any mandatory step MUST prevent package acceptance.

23. Package acceptance verdicts

23.1 Standard verdicts

PACKAGE_VALID
PACKAGE_VALID_WITH_NOTES
PACKAGE_INVALID
PACKAGE_INSUFFICIENT
PACKAGE_SCOPE_MISMATCH
PACKAGE_ATTESTATION_INSUFFICIENT
PACKAGE_CORRUPTED
PACKAGE_SUPERSEDED
PACKAGE_REVOKED

23.2 Rule

Mainnet bootstrap SHOULD require PACKAGE_VALID only.

24. Package scope lock

24.1 Need

Pachetul trebuie ancorat la exact network scope.

24.2 Scope-lock fields

target_network_class
target_chain_id
target_genesis_hash
package_class

24.3 Rule

A package approved for one mainnet scope MUST NOT be silently accepted for another chain or release scope.

25. Relation to release package

25.1 Need

Genesis package is usually part of a broader release package.

25.2 Rule

The final release manifest SHOULD reference the exact genesis_package_id and exact genesis_hash.

25.3 Rule

Changing genesis package after release approval creates a new release candidate, not a patch-in-place.

26. Mainnet-specific attestation requirements

26.1 For `GENESIS_PACKAGE_MAINNET`, SHOULD require:

AT_HASH_CONFIRMED on critical artifacts
AT_SECURITY_REVIEWED
AT_APPROVED_FOR_RELEASE
AT_APPROVED_FOR_MAINNET
genesis custodian or equivalent constitutional approval if policy requires

26.2 Rule

A mainnet genesis package without explicit final launch-scope approval MUST NOT be used.

27. Pre-launch supersession

27.1 Need

A genesis package may be replaced before launch.

27.2 Rule

Pre-launch replacement MUST happen by:

new package_id
new manifest
explicit supersession record/manifest
explicit invalidation or supersession of older approvals where needed

27.3 Rule

Old and new package MUST remain distinguishable forever.

28. Post-publication revocation

28.1 Need

A published genesis package candidate may later be found invalid before launch.

28.2 Rule

Revocation MUST be explicit and SHOULD include:

affected package_id
reason hash
severity
replacement package_id if known
scope and effective time

28.3 Rule

Revocation by deleting files or reuploading corrected files under same identity is forbidden.

29. Validator bootstrap verification guide (normative summary)

29.1 Every validator SHOULD confirm before startup:

package manifest hash
package_id
genesis_hash
chain_id
validator set root
parameter root
policy root
attestation sufficiency
release scope compatibility

29.2 Rule

A validator that cannot confirm package integrity SHOULD NOT join the network.

30. Operator distribution package

30.1 Recommended distribution unit

The operator-facing package MAY be:

raw folder tree
canonical tar/zip equivalent
signed vault snapshot subset

30.2 Rule

Distribution container format is secondary. Normative truth remains in manifest + artifact hashes + attestations.

30.3 Rule

Repackaging for transport MUST NOT alter canonical file bytes of normative artifacts.

31. Physical container normalization

31.1 Need

Archive formats can inject ambiguity.

31.2 Rule

If using archive container, packaging policy SHOULD normalize:

file order
timestamps
permissions metadata if relevant
compression determinism if required
path normalization

31.3 Rule

The package container SHOULD itself be admitted as an artifact, but must not replace the internal canonical artifact identities.

32. Recovery of a genesis package

32.1 Need

If local copy is corrupted, operator must recover safely.

32.2 Recovery steps

fetch package from trusted distribution source
verify package manifest
verify all required artifact hashes
verify attestation bundle
recompute genesis_hash and roots
compare with previously trusted values
replace corrupted local copy only after successful verification

32.3 Rule

Never “repair” genesis package by hand-editing files.

33. Quarantine rules for package components

33.1 Components MUST be quarantined if:

hash mismatch
role mismatch
missing mandatory artifact
attestation insufficiency
derived root mismatch
duplicate conflicting chain identity
malformed bundle structure

33.2 Rule

A package with any quarantined mandatory component is invalid.

34. Anti-duplication and anti-shadow rules

34.1 Rule

The package MUST NOT contain:

two files claiming same role with different identities unless explicitly multi-entry class
shadow copies of critical artifacts in advisory paths
same normalized filename mapped to conflicting critical artifacts

34.2 Examples forbidden

two genesis_spec artifacts
one real genesis and one edited “copy” in docs folder that looks normative
multiple validator set bundles with no scope distinction

35. Concrete package manifest example roles

35.1 Minimal mainnet role set

genesis_spec
chain_identity
derived_roots_commitment
validator_set
parameter_state
registry_bundle
policy_bundle
attestation_bundle
checksum_bundle

35.2 Extended mainnet role set

Plus:

machine_bundle
witness_bundle
operator_verification_guide
release_linkage_manifest

36. Release linkage manifest

36.1 Optional but recommended

This small artifact links genesis package into broader release set.

36.2 Structure

GenesisReleaseLinkage {
  linkage_id
  genesis_package_id
  release_candidate_id
  release_manifest_id
  target_network_class
  target_chain_id
}

36.3 Rule

If present, it SHOULD be included in release candidate validation.

37. Package artifact policy matrix

37.1 Recommended policy

For GENESIS_PACKAGE_MAINNET, the policy SHOULD require:

all critical artifacts TIER_4
strict vault admission
no overwrite
snapshot after admission
scope-locked approvals
exact hash confirmation
mainnet approval attestation
explicit supersession if replaced

37.2 Rule

Relaxed policy SHOULD be reserved only for devnet/private testing scopes.

38. Security considerations

38.1 Dangerous anti-patterns

Systems SHOULD avoid:

distributing genesis as loose files without package manifest
publishing only human-readable genesis summary
multiple “equivalent” genesis zips with different internal bytes
chain_id in docs but not matching genesis blob
validator set file not reconciling with derived roots
package approval not scope-locked to exact genesis_hash
replacing one file after approval instead of regenerating package
archive timestamps or container noise altering perceived package identity
shipping optional shadow files that look normative
trusting checksum list without full manifest and attestation validation

38.2 Rule

Genesis package handling MUST be conservative, boring and explicit.

39. Formal goals

AZ-022 urmărește aceste obiective:

39.1 Package completeness

The package contains all mandatory artifacts required to validate genesis scope.

39.2 Package determinism

The same package bytes and manifest produce the same package identity, genesis identity and derived roots.

39.3 Package provenance

Critical package artifacts carry sufficient attestation and approval chain.

39.4 Bootstrap safety

Nodes can reject incomplete, corrupted, mismatched or wrongly scoped genesis packages before network participation.

40. Formula documentului

Concrete Genesis Package = strict manifest + exact genesis artifacts + derived roots + validator/parameter bundles + scope-locked attestations + release linkage

41. Relația cu restul suitei

AZ-016 definește genesis logic.
AZ-020 definește atestările.
AZ-021 definește build/release pipeline.
AZ-022 definește forma concretă a pachetului genesis care trece prin toate acestea.

Pe scurt: AZ-016 spune ce trebuie să existe la time zero; AZ-022 spune exact cum livrezi și verifici acel time zero în practică.

42. Ce urmează

După AZ-022, documentul corect este:

AZ-023 — Reference Implementation Milestone Map

Acolo trebuie fixate:

ordinea concretă de implementare,
milestone-urile,
dependențele dintre subsisteme,
ce se construiește întâi,
ce este minim pentru devnet, testnet și mainnet-candidate.

Închidere

Genesis nu trebuie să existe ca „fișier important undeva”. Trebuie să existe ca pachet verificabil, cu roluri clare, hash-uri clare, rădăcini clare, aprobări clare și suficiente reguli încât orice nod serios să poată spune fie: „da, acesta este exact genesis-ul rețelei” fie „nu, acest pachet este incomplet, corupt sau greșit scoped”.

Acolo începe bootstrap-ul verificabil real.