# Animica Chains — Canonical Chain Metadata

**Version:** 1.0  
**Status:** Active  
**Audience:** Node operators, wallet/explorer authors, SDKs, CI

This directory is the single source of truth for **machine-readable chain metadata** for Animica networks (mainnet, testnet, localnet). Tools consume these JSON files to discover RPC endpoints, P2P bootstrap info, address rules, PQ suites, VM/DA params, and more.

---

## What’s here

- `chains/animica.mainnet.json` — reserved (placeholders until launch)
- `chains/animica.testnet.json` — public testnet defaults
- `chains/animica.localnet.json` — developer/local profile
- `chains/registry.json` — index of all chains (ids, names, paths, checksums)
- `chains/checksums.txt` — SHA-256 for each JSON (regenerated by CI)
- `chains/schemas/*.json` — authoritative JSON Schemas
- `chains/bootstrap/*` — seed hosts & bootnodes
- `chains/icons/*` — brand assets for wallets/explorers
- `chains/signatures/*` — detached signatures & maintainer key bundle
- `chains/bindings/*` — tiny loaders (TypeScript/Python)
- `chains/scripts/*` — validation, checksum, sync helpers
- `chains/tests/*` — sanity tests

---

## Versioning & Compatibility

- **Semver for schema:** bump `chains/schemas/chain.schema.json` using `MAJOR.MINOR.PATCH`.
  - **Major**: breaking structural changes (fields removed/renamed).
  - **Minor**: new optional fields.
  - **Patch**: constraints/description fixes only.
- **Chain JSONs** carry a `schemaVersion` and a self-`checksum` field that must match `chains/checksums.txt`.
- **Backwards compatibility goal:** loaders should accept the last **two** minor schema versions.

---

## Trust & Integrity

1. Compute `chains/checksums.txt` (deterministic ordering).  
2. Sign it with the **release signing key** → `chains/signatures/registry.sig`.  
3. Verifiers:
   ```bash
   gpg --verify chains/signatures/registry.sig chains/checksums.txt
   shasum -a 256 chains/animica.testnet.json | awk '{print $1}'
   grep animica.testnet.json chains/checksums.txt
Public keys live in chains/signatures/maintainers.asc (or governance/keys/gpg/maintainers.asc).

JSON structure (summary)
Every chain JSON conforms to chains/schemas/chain.schema.json. Field overview:

name, chainId, network (mainnet|testnet|localnet), status, testnet (bool)

nativeCurrency { name, symbol, decimals }

rpc { http: string[], ws: string[] }

explorers [{ name, url }]

faucets [{ name, url }] (testnet/localnet)

p2p { protocols: string[], port: number, seeds: string[], bootnodes: string[] }

addresses { format: "bech32m", hrp: "am", pubkeyTypes: string[] }

pq { sigDefault: string, kex: string, policyVersion: string }

vm { lang: "python", version: string, gasModel: string }

da { maxBlobSizeBytes: number, nmtNamespaceBytes: number, rsRate: string }

randomness { method: "vdf+qrng", contract?: string, params?: object }

genesis { hash: string, timestamp: string, initialHeight: number }

governance { site?: string, votingPeriodDays: number }

links { website?: string, studio?: string, explorer?: string, docs?: string }

features string[] (e.g., ["poies","pq","ai","quantum","da","vm_py"])

checksum string (must match checksums.txt)

See the schema for required/optional markers and formats.

How tools consume these files
Wallets / Frontends
Load via bindings or direct JSON:

TypeScript: chains/bindings/typescript/index.ts validates against the schema and exports typed objects.

Python: chains/bindings/python/animica_chains/ exposes a Pydantic model.

Pick default RPC/WS from rpc.http[0] / rpc.ws[0] unless the user overrides.

Render icons from chains/icons/* keyed by name.

Nodes / CLIs
Use p2p.seeds and p2p.bootnodes to bootstrap.

Enforce address rules from addresses.*.

Guide VM/DA sizing from vm and da sections (within hard bounds from governance).

Explorers / Indexers
Display network labels using name, chainId, status.

Link to community resources from links.*.

CI & Scripts
Validate all files:

bash
Copy code
python chains/scripts/validate.py
Regenerate checksums:

bash
Copy code
python chains/scripts/generate_checksums.py
Sync to website (minified bundle):

bash
Copy code
python chains/scripts/sync_to_website.py
Endpoint health check report (optional):

bash
Copy code
python chains/scripts/check_endpoints.py
Tests live in chains/tests/ and should run in CI.

Authoring guidelines
Prefer HTTPS RPC endpoints; include at least one WS if available.

Keep testnet faucets/explorers current; remove dead links.

When PQ defaults change, bump pq.policyVersion and cross-link the governance proposal.

Keep genesis.hash stable; if re-genesis occurs on testnet, bump initialHeight and document in CHANGELOG.md.

Example snippet
json
Copy code
{
  "schemaVersion": "1.2.0",
  "name": "Animica Testnet",
  "chainId": 2,
  "network": "testnet",
  "status": "active",
  "testnet": true,
  "nativeCurrency": { "name": "Animica", "symbol": "ANM", "decimals": 18 },
  "rpc": { "http": ["https://rpc.testnet.animica.org"], "ws": ["wss://ws.testnet.animica.org"] },
  "explorers": [{ "name": "Animica Explorer", "url": "https://explorer.testnet.animica.org" }],
  "faucets": [{ "name": "Faucet", "url": "https://faucet.testnet.animica.org" }],
  "p2p": {
    "protocols": ["animica/1"],
    "port": 30303,
    "seeds": ["seed1.testnet.animica.org", "seed2.testnet.animica.org"],
    "bootnodes": []
  },
  "addresses": { "format": "bech32m", "hrp": "am", "pubkeyTypes": ["ed25519","secp256k1","dilithium3"] },
  "pq": { "sigDefault": "dilithium3", "kex": "kyber-768", "policyVersion": "2025-10" },
  "vm": { "lang": "python", "version": "0.5.0", "gasModel": "v1" },
  "da": { "maxBlobSizeBytes": 2097152, "nmtNamespaceBytes": 8, "rsRate": "10/16" },
  "randomness": { "method": "vdf+qrng", "params": { "tau": 1024 } },
  "genesis": { "hash": "0x...", "timestamp": "2025-10-01T00:00:00Z", "initialHeight": 0 },
  "governance": { "site": "https://gov.animica.dev", "votingPeriodDays": 7 },
  "links": { "website": "https://animica.dev", "docs": "https://docs.animica.dev" },
  "features": ["poies","pq","da","vm_py"],
  "checksum": "<sha256-from-checksums.txt>"
}
FAQ
Why duplicate the checksum inside each JSON?
Convenience for light clients; the signed checksums.txt remains the source of truth.

Can third parties mirror these files?
Yes. They must reproduce checksums.txt and carry the detached signature or point back here.

How do I add a new chain profile?
Add JSON + update registry.json; run validation & tests; regenerate checksums; open a PR.

Change Log
1.0 (2025-10-31): Initial README with structure, trust model, scripts, and schema overview.
