Genesis payload reference

Use this reference when you assemble the request body for the one-time Genesis API operation. For the design sequence that should come before the payload is finalized, see Design your genesis.

You can only run the Genesis operation once. The system has an anti-rewind mechanism that blocks any attempt to rerun it. Plan your initial domain structure, users, and policies carefully.

Genesis payload structure

Use this map to confirm the purpose of each section before you assemble the complete request body.

Payload section	Requirement	Purpose
`rootDomainSetup`	Mandatory top-level section	The `rootDomainSetup` object is the only mandatory top-level section. It creates the root domain and the initial governance state that must exist before normal authenticated workflows are available.
`id`, `alias`, `lock`, `governingStrategy`, `description`, `customProperties`	Fields in `rootDomainSetup`	Set the root domain identifier, alias, lock state, governing strategy, description, and custom properties.
`permissions.readAccess`	Part of `rootDomainSetup`	Use `permissions.readAccess` to define which roles can view each entity type in the domain.
`users`	Part of `rootDomainSetup`	Add the first users and roles that can satisfy the policies required at launch. Embedded genesis users do not include a `type` field.
`policies`	Part of `rootDomainSetup`	Add the policies that govern day-one administration, operations, fallback behavior, and recovery. Embedded genesis policies do not include a `type` field.
`descendants`	Optional in `rootDomainSetup`	Add launch-critical subdomains in `descendants`. Leave the array empty if all day-one governance state belongs in the root domain.
`cryptoSetup`	Optional top-level section	Use `cryptoSetup` to select the elliptic curves that the notary uses for API response signing, collection signing, and internal notary-to-vault messages.
`tickers`	Optional top-level section	Use `tickers` to define assets that must be available immediately after Genesis.
`ledgers`	Optional top-level section	Use `ledgers` to define ledger records that must be available immediately after Genesis. Each ledger entry includes `id`, `alias`, `parameters`, and `customProperties`.
`systemProperties`	Optional top-level section	Use `systemProperties` to include supported Genesis system properties. This example registers the state review authority public key used during anti-rewind file recovery.
`systemSignaturesPublicKey`	Optional top-level field	Use `systemSignaturesPublicKey` when system-signed API proposals must be available from launch with a pre-pinned key.

Complete Genesis payload example

The following example shows a complete, valid genesis request body. It does not include every optional top-level section.

Complete genesis request body

{
    "rootDomainSetup": {
        "id": "e7eb7b63-d63b-4c30-9cca-d3b1ea7e46ad",
        "alias": "Root domain",
        "lock": "Unlocked",
        "governingStrategy": "CoerceDescendants",
        "permissions": {
            "readAccess": {
                "domains": ["platform-admin", "auditor"],
                "users": ["platform-admin", "auditor"],
                "endpoints": ["platform-admin"],
                "policies": ["platform-admin", "policy-operator", "auditor"],
                "accounts": ["platform-admin", "auditor"],
                "transactions": ["platform-admin", "auditor"],
                "requests": ["platform-admin", "policy-operator", "auditor"],
                "events": ["platform-admin", "auditor"]
            }
        },
        "description": "A genesis payload for the creation of the root domain",
        "customProperties": {},
        "users": [
            {
                "id": "e1fe3431-f899-427b-9e67-a75fb9fe5e57",
                "alias": "platform-admin-1@example.com",
                "publicKey": "MFkw...NfPfw/q9YW74Q==",
                "roles": ["platform-admin", "policy-operator"],
                "loginIds": [
                    {"id": "platform-admin-1@example.com", "providerId": "harmonize"},
                    {"id": "platform-admin-1@example.com", "providerId": "azure-ad"}
                ],
                "lock": "Unlocked",
                "description": "Genesis platform administrator",
                "customProperties": {}
            }
        ],
        "policies": [
            {
                "id": "00000000-0000-0000-0000-000000000000",
                "alias": "root-catch-all",
                "rank": 20,
                "scope": "Self",
                "scriptingEngine": "Javascript_v0",
                "condition": {
                    "expression": "context.request.author.id == 'e1fe3431-f899-427b-9e67-a75fb9fe5e57'",
                    "type": "Expression"
                },
                "workflow": [
                    {"role": "platform-admin", "quorum": 1, "type": "RoleQuorum"}
                ],
                "lock": "Unlocked",
                "description": "Fallback policy for root-domain launch operations",
                "customProperties": {}
            }
        ],
        "descendants": []
    },
    "cryptoSetup": {
        "apiSigning": "Secp256r1",
        "collectionSigning": "Secp256r1",
        "messageSigning": "Ed25519"
    },
    "tickers": [
        {
            "id": "688b48e3-8ce1-4e01-b242-96f03ecb554a",
            "ledgerId": "bitcoin-testnet",
            "kind": "Native",
            "name": "Bitcoin testnet",
            "decimals": 8,
            "symbol": "tBTC",
            "ledgerDetails": {"properties": {"type": "Native"}, "type": "Bitcoin"},
            "lock": "Unlocked",
            "description": "Bitcoin testnet ticker",
            "customProperties": {}
        }
    ],
    "systemProperties": [
        {
            "value": {
                "publicKey": {
                    "value": "MFkw...HdVNyxTyl1plgAfh/Yg==",
                    "type": "PublicKey"
                }
            },
            "type": "StateReviewAuthorityProperty"
        }
    ],
    "systemSignaturesPublicKey": "MFkw...systemSigningPublicKey=="
}

Root domain setup

This section is the only mandatory section. The rootDomainSetup section resembles a standard new domain creation payload. You specify the read permissions, users, and policies to create in the new Ripple Custody instance.

For design guidance, see Design your domains. For post-genesis domain operations, see Manage domains.

Governing strategy

During domain creation, you choose between these governing strategies:

CoerceDescendants: The domain ignores the policies of its subdomains.
ConsiderDescendants: The domain considers the policies of its subdomains.

This field is optional. If you do not specify a governing strategy during domain creation, the domain defaults to a ConsiderDescendants strategy. Once created, you cannot change the governing strategy for the domain.

To execute a coercive intent within a locked domain, you must unlock the domain first.

Permissions

This access management section specifies the user roles that can view different entity types in the domain.

Users

This section is similar to a standard new user creation payload. Create enough users, with appropriate roles, to fulfill the defined policies.

Embedded genesis users do not include a type field. Role names in roles, read-access lists, and workflow steps must use lowercase letters, digits, and hyphens.

Users follow these identifier guidelines:

Users within the same domain cannot have the same alias.
Users that have the same public key in different domains must have the same alias.

Example user with four roles and Azure AD SSO

"users": [
    {
        "id": "e1fe3431-f899-427b-9e67-a75fb9fe5e57",
        "alias": "operator@ripple.com",
        "publicKey": "MFkw...NfPfw/q9YW74Q==",
        "roles": ["platform-admin", "policy-operator", "compliance", "auditor"],
        "loginIds": [
            {"id": "op1@company.com", "providerId": "harmonize"},
            {"id": "op1@company.com", "providerId": "azure-ad"}
        ],
        "lock": "Unlocked",
        "description": "A user",
        "customProperties": {}
    }
]

For user planning guidance, see Plan your first users. For the post-genesis user creation procedure, see Manage users and roles.

Policies

This section is similar to a standard new policy creation payload. Genesis policies are embedded in a domain's policies array and do not include a type field. If a policy should match all user-signed proposal types, omit intentTypes; do not set it to null. Include a breakglass policy. For more information, see Design your policies.

Descendants

This section is optional. Specify subdomains as an array of domain objects inside the descendants property. For each subdomain, specify the same information as for the root domain.

Crypto setup

This optional section specifies the cryptographic methods (elliptic curves) that the notary uses to create and verify signatures.

You can specify different elliptic curves for different operations:

apiSigning: The curve used to sign payloads returned to users following a GET request.
collectionSigning: The curve for signing the roots of all collections' Merkle trees. This guarantees tamper-proof storage of the information. For more information, see Security model.
messageSigning: The curve used to sign internal messages from the notary to the vault.

For all types of operations you can choose between Secp256r1, Secp256k1, and Ed25519 elliptic curves.

Tickers

This optional section includes a list of tickers and other assets available for blockchain ledgers. Use this section to provide a list of pre-validated tickers.

Ledgers

This optional section includes ledger records that must be available immediately after Genesis. Each ledger entry includes an id, alias, ledger-specific parameters, and customProperties.

System properties

This optional section includes supported Genesis system properties. Use StateReviewAuthorityProperty to register the public key of the state review authority. Use a public key in a standard Ripple Custody accepted format: secp256k1, secp256r1, or Ed25519. Represent it as a Base64-encoded string.

The state review authority acts as a trusted party to confirm the authenticity of the system state if you need to recover the anti-rewind file (ARF).

If you do not specify this information during Genesis, register it as soon as possible afterwards. This allows you to recover your system in a disaster recovery scenario. For more information, see Register the state review authority public key.

System-signed intent enablement property

The system properties model also includes NOTARY_SYSTEM_SIGNED_INTENTS_ENABLED, whose value contains an enabled boolean. This property controls runtime processing of system-signed intents.

Create or update this property only when the deployment is configured for system-signed intent processing, the Gateway system signing public key is registered, and the required policies are in place. System-signed intent configuration is enabled by default at deployment level, but processing remains disabled until this runtime property is set to enabled: true. For the operational sequence, see System-signed intent configuration.

System signatures public key

The optional top-level systemSignaturesPublicKey field registers the public key used by the platform to verify system-signed intent proposals.

Use this field when system-signed API proposals must be available from launch with a pre-pinned key. In the default post-genesis path, Gateway mints the system signing keypair on first boot. Retrieve the active public key with GET /v1/system-signing/info, then register it after launch with the v0_RegisterTrustedPublicKey intent and purpose: "SystemSignatures".

The system signing key is separate from user API signing keys, Notary collection signing keys, and messaging signing keys. For the request shape used by system-signed proposals, see Intent request structure.

Genesis events

When you run the Genesis operation, Ripple Custody includes two properties in the GenesisSucceeded event:

genesis: A data structure holding the notary-signed original Genesis payload.
createdEntitiesReferences: Key information on the data created.

For more information, see Event management > Genesis event.