# 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](/products/custody/governance/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. ```json 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](/products/custody/governance/genesis/design-your-domains). For post-genesis domain operations, see [Manage domains](/products/custody/governance/domains/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. ```json 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](/products/custody/governance/genesis/plan-your-first-users). For the post-genesis user creation procedure, see [Manage users and roles](/products/custody/governance/users/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](/products/custody/governance/genesis/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](/products/custody/overview/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](/products/custody/operations-and-maintenance/backup-and-restore/register-a-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](/products/custody/deployment/reference/system-signed-intents). ## 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](/products/custody/governance/intents/intent-request-structure#system-signed-proposal-request-body). ## 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](/products/custody/reference/events-and-webhooks/event-payload-reference#genesis-event).