Welcome to the Cardano World Repository
Cardano is a decentralized third-generation proof-of-stake blockchain platform and home to the ada cryptocurrency. It is the first blockchain platform to evolve out of a scientific philosophy and a research-first driven approach.
Cardano World Repository
This repository is a work-in-progress effort to bundle all Cardano related development & documentation in a single "portal"-repository.
The target audience are people who work with Cardano on a daily basis or just started exploring.
Things you'll find here:
Source Code
How is Cardano implemented? → ./src
.
A growing number of source projects will be merged soon.
Building & Packaging
Is Cardano built and packaged reproducibly? → Ofc. 😎
Where? → ./nix/cardano
.
Operations
How is Cardano operated @ IOG? → ./nix/cloud
.
Do you have automation in place? → Sure. See: ./nix/automation
.
Documentation
Where can I find the documentation? → ./docs
.
No, I mean rendered? → The Cardano Book.
The documentation is structured around these axes:
For Study | For Work | |
---|---|---|
The Practice | Tutorials | How-To Guides |
The Theory | Explanation | Reference |
Licenses
What licenses are used? → ./.reuse/dep5
.
And the usual copies? → ./LICENSES
.
Releases
You may find releases on the GitHub Release Page of this repository.
--
Packaging Principles
All Cardano software is packaged according to the following principles.
- Reproducibility
- Uncompromising GitOps
- The 4 Layers of Packaging
Reproducibility
All Cardano software published via this repository is built in a reproducible manner. That means, given a specific checkout of this repository, anyone will be able with time and knowledge to reproduce byte-equivalent artifacts compared to the ones that we publish as releases.
This reproducibility is such that it percolates the entire build stack and up to the most fundamental bootstrapping of the compiler toolchain.
Reproducability produces high-integrity build artifacts and is the only route to sensible software supply chain auditing. → We build Cardano with the same rigor as we write it.
Additional Resources
-
If this is new to you, see: https://reproducible-builds.org/
-
And for even more mind-blow, see: https://bootstrappable.org/
-
Make sure to also read up the legendary Ken Thompson's "Reflections on Trusting Trust".
Uncompromising GitOps
Building on the previous principle, all our build instructions are code. That means
with a simple checkout, a single system dependency on nix
and simple
nix
commands, you can do one or all of the following things (and more):
- Build a binary (and also publish it)
- Build an entrypoint
- Build an OCI-Image (and also publish it)
- Build the scheduler spec (and also deploy it)
The 4 Layer of Packaging
Based on the previous principles, to get a runnable shipped, we look at 4 layers of packaging:
- The binary packaging (
nix/cardano/packages/default.nix
) - The entrypoint packaging (
nix/cardano/entrypoints.nix
) - The OCI image packaging (
nix/cardano/oci-images.nix
) - The scheduler packaging (
nix/cardano/nomadJob/default.nix
)
You can consume any of those artifacts according to your deployment scenario, but usually using our published OCI-images ("docker") might be a good start.
Environments
The official Cardano Environment configuration files:
Throw-away Devnets
Usage: Hard fork testing, Testing new release functionality that needs public involvement
These can be spun up/torn down at any time by release manager for specific tests, such as hard forks.
These are shared with the community for early involvment before a release candidate is mature.
Recieves updates for official releases, release candidates and occasionally custom tags that aren't candidates for release
Upgrade Strategy: Deploy all nodes with every request
Changes Requested by: Release Manager Approvals Required: SRE Director or SRE Resident Manager
Responsible: SRE Accountable: SRE Director Consulted: Release Manager Informed: Cardano Core Tribe
Shelley-QA (Internal Only)
Usage: Testing all new functionality. Ideally automatically deployed off of master on every commit
Ideally, stays long running to build up history, although the nature of early testing can potentially break it. In the past we have disaster recoveried it since we control all the keys.
Upgrade Strategy: Deploy all nodes with every request
Changes Requested by: QA Team Approvals Required: SRE Director or SRE Resident Manager
Responsible: SRE Accountable: SRE Director/QA Manager Consulted: Release Manager Informed: QA Team
- Node Config
- DB Sync Config
- Submit API Config
- Node Topology
- Byron Genesis
- Shelley Genesis
- Alonzo Genesis
- Conway Genesis
Preview Testnet
Usage: Testing release candidates and mainnet releases. Leads mainnet hard forks by at least 4 weeks.
Ideally stays long running. Only if an issue is found after it forks that's breaking should it be respun.
Epoch length of 1 day. Development flags allowed in configuration files.
Upgrade Strategy:
- Release Candidates - 1/3 of nodes
- Official Releases - 2/3 of nodes
- Hard forks - all nodes
- Community requested to only deploy release candidates and official releases
Changes Requested by: Release Squad Lead Approvals Required: SRE Tribe Lead, Cardano Head of Engineering, Cardano Head of Architecture
Responsible: IOG SRE Accountable: Head of SRE/Release Squad Lead Consulted: SPOs Informed: Cardano Core Tribe, COO, Director of Engineering
- Node Config
- DB Sync Config
- Submit API Config
- Node Topology
- Byron Genesis
- Shelley Genesis
- Alonzo Genesis
- Conway Genesis
Pre-Production Testnet
Usage: Testing release candidates and mainnet releases. Forks at approximately same time as mainnet (within an epoch of each other).
Long running. Since this parallels mainnet, if a bug occurs here, it needs fixed properly and can not be respun.
Upgrade Strategy:
- Release Candidates - 1/3 of nodes
- Official Releases - 2/3 of nodes
- Hard forks - all nodes
- Community requested to only deploy release candidates and official releases
Changes Requested by: Release Squad Lead Approvals Required: SRE Tribe Lead, Cardano Head of Engineering, Cardano Head of Architecture, CF Representative
Responsible: IOG SRE Accountable: Head of SRE/Release Squad Lead Consulted: SPOs, IOG Tribes Informed: Cardano Core Tribe, COO, Director of Engineering, VP Community
- Node Config
- DB Sync Config
- Submit API Config
- Node Topology
- Byron Genesis
- Shelley Genesis
- Alonzo Genesis
- Conway Genesis
Production (Mainnet)
Usage: Live Production. Only gets official mainnet releases.
Upgrade Strategy:
- Official Releases - Deploy 1 pool and it's relays every 24 hours
- Community requested to only deploy official releases
Changes Requested by: Release Squad Lead Approvals Required: SRE Tribe Lead, IOG Executive Team, CF Executive Team
Responsible: IOG SRE Accountable: Head of SRE/Release Squad Lead Consulted: SPOs, IOG Tribes, IOG Executive Team Informed: Cardano Core Tribe, COO, IOG Director of Engineering, IOG VP Community
- Node Config
- DB Sync Config
- Submit API Config
- Node Topology
- Node Topology (P2P - SPOs only!)
- Byron Genesis
- Shelley Genesis
- Alonzo Genesis
- Conway Genesis
Plutus Cost Model
Environments:
- Mainnet
- Preprod
- Preview
Environments:
- Preview
Environments:
- Mainnet
- Preprod