# The Genesis block

Executive summary
**The *genesis block* is the immutable, cryptographically-signed configuration that establishes the initial state of your custody platform. It can never be changed after deployment.**

- Defines your root domain, initial users, and baseline policies.
- Creates the "root of trust" for the entire platform's security model.
- All subsequent changes are chained to this initial state via a Merkle tree.
- Cannot be re-loaded or modified. State changes happen through governed intents.


Why this matters
The genesis block is the foundation of your platform's security and auditability. Every user permission, policy, and configuration traces back to this immutable root. This design makes it cryptographically impossible for attackers (or even administrators) to retroactively grant themselves permissions or alter the audit trail.

It's important to get your genesis configuration right before deployment — errors require redeploying the platform.

**For architects and operators**: Plan your genesis configuration carefully with stakeholders from security, compliance, and operations. Include enough initial users and policies to bootstrap operations, but not so many that you're locked into rigid structures. Remember: you can add users and policies later through governance, but you cannot change the genesis block.

Prerequisites
Before reading this page, you should understand:

- [Governance framework](/products/custody/v1.34/overview/governance) - Domains, intents, and policies
- [Data integrity](/products/custody/v1.34/concepts/data-integrity) - Merkle trees and anti-rewind protection


The genesis block is a cryptographically-signed configuration file that defines the immutable, foundational state of your Ripple Custody platform.

It is loaded once, when the platform is first initialized, to establish the "root of trust." From that moment forward, every change to the platform's state (like adding a user or changing a policy) is a new, auditable transaction chained back to this initial state.

## The core principle: Immutable root of trust

The genesis block is the starting point for the platform's blockchain-inspired security model.

1. The "first block": At first-time setup, the *governance engine* (or *notary*) loads the genesis block to create the "first block," or root, of the platform's state Merkle Tree.
2. Immutable state: The governance engine signs this initial state and protects it with the *anti-rewind file* (ARF).
3. Enforced audit trail: From this point on, the genesis block *cannot* be re-loaded or changed for this Ripple Custody instance. The only way to modify the platform's state (like adding a new user) is to submit a new, signed intent (a change request). The governance engine validates this intent against its policies, and if approved, creates a new, signed "block" in the Merkle tree, preserving a perfect, immutable audit trail.


This design makes it cryptographically impossible for an attacker to tamper with the database and secretly grant themselves permissions. The governance engine would instantly detect the invalid state.

## The system-update flow in practice

This flow shows how the governance engine (the *trusted* component) uses the Merkle Tree and ARF to validate every change, ensuring the *untrusted* database cannot be tampered with.

| Step | Action | Description |
|  --- | --- | --- |
| 1 | Merkle tree validation | The governance engine receives a user-signed intent to change the system state. It then: (1) Extracts the current state from the (untrusted) database; (2) Verifies the state's Merkle tree version against its *local*, secure version counter (from the ARF) to prevent replay attacks; (3) Validates the Merkle root's signature to ensure the state data has not been tampered with; (4) Checks the user's signature on the intent against the public key stored in that *verified* state. If any check fails, the request is rejected. |
| 2 | State mutation | Once validated, the governance engine approves the intent and updates the state by adding or modifying the entities (e.g., creating the new user). |
| 3 | Merkle-proofed generation | The Merkle tree is updated with the hash of the new/changed entity. This generates a new Merkle root. |
| 4 | Commit and signature | The governance engine: (1) Signs the new Merkle root; (2) Updates its local, secure version counter in the anti-rewind file (ARF); (3) Atomically signs each new entity (e.g., the user object) to ensure its individual integrity and provide proof of notarization. |


This process makes it cryptographically impossible for an attacker to tamper with the database (e.g., by changing a policy) and have the system accept it. The governance engine would instantly detect the invalid state and reject the operation.

## Critical distinction: Genesis block vs. values.yaml

These are the two major places where you can make changes to your Ripple Custody instance but they control different things:

* *values.yaml* (Helm config): This is the blueprint for your Ripple Custody instance. It defines the database connection, the message broker and message queue, and the KMS type. You change this file when you need to change one of these connections.
* Genesis file (Governance config): It defines the actions a user can take on the Ripple Custody instance once it's initialised (i.e. governance), it manages the first admin user, the root domain, and the first policies. You never change the genesis file; you add new auditable amendments (Intents) to it.


| Feature | *values.yaml* (Helm configuration) | Genesis block (Governance configuration) |
|  --- | --- | --- |
| Purpose | Configures infrastructure and connectivity. | Configures application-level governance. |
| "What it answers" | "How does the platform connect to the database, MQ, and KMS? What's its hostname?" | "Who is the first admin user? What are the initial domains? What are the root policies?" |
| When is it used? | On every Helm install or Helm upgrade. | Loaded ONCE during the initial, first-time boot of the platform. |
| Mutability | Mutable. You change this file frequently to manage your infrastructure. | Immutable. Once loaded, its state cannot be changed. All changes are via new intents. |


## Next steps

- [Governance framework](/products/custody/v1.34/overview/governance): Understand the overall governance model
- [Policies](/products/custody/v1.34/concepts/governance/policies): Learn how policies work
- [Policy design](/products/custody/v1.34/get-started/design/policies): Design and create policies for your environment