{"templateId":"markdown","versions":[{"version":"v1.40","label":"v1.40 STS","link":"/products/custody/governance/genesis/design-your-policies","default":true,"active":false,"folderId":"c15a2701"},{"version":"v1.39","label":"v1.39 STS","link":"/products/custody/v1.39/governance/genesis/design-your-policies","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.38","label":"v1.38 STS","link":"/products/custody/v1.38/governance/genesis/design-your-policies","default":false,"active":true,"folderId":"c15a2701"},{"version":"v1.34","label":"v1.34 LTS","link":"/products/custody/v1.34/governance/genesis/design-your-policies","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.26","label":"v1.26 LTS","link":"/products/custody/v1.26/governance/genesis/design-your-policies","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.19","label":"v1.19 LTS","link":"/products/custody/v1.19/governance/genesis/design-your-policies","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.15","label":"v1.15 LTS","link":"/products/custody/v1.15/governance/genesis/design-your-policies","default":false,"active":false,"folderId":"c15a2701"}],"sharedDataIds":{"sidebar":"sidebar-products/custody/@v1.15/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Design your policies","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"design-your-policies","__idx":0},"children":["Design your policies"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Design the policies that must exist when your environment first starts. A strong genesis does not rely on future policy changes to make basic governance safe."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"start-with-workflows","__idx":1},"children":["Start with workflows"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["List the workflows that must operate on day one:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Workflow area"},"children":["Workflow area"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Coverage to design"},"children":["Coverage to design"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Root administration"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Domain, user, role, policy, vault, and platform-level operations."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["User management"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Creating users, changing roles, locking users, and unlocking users."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Policy management"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Creating, updating, locking, and unlocking policies."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Domain operations"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Creating, updating, locking, and unlocking domains."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transaction operations"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transfer creation, amount thresholds, trusted endpoints, and exceptions."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Compliance and screening"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Quarantine release, screening exceptions, and compliance escalation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Breakglass and recovery"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Emergency remediation with stronger approval."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fallback"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Catch unexpected workflows without weakening specific controls."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"policy-coverage-matrix","__idx":2},"children":["Policy coverage matrix"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a matrix before writing JSON:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Workflow"},"children":["Workflow"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Intent types"},"children":["Intent types"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Domain scope"},"children":["Domain scope"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Maker role"},"children":["Maker role"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Approval workflow"},"children":["Approval workflow"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Condition"},"children":["Condition"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Fallback"},"children":["Fallback"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["User management"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v0_CreateUser"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v0_UpdateUser"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Root or admin domain"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["User admin"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Second user admin plus compliance if needed"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Author role or target role"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Low-rank catch-all"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Policy management"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v0_CreatePolicy"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v0_UpdatePolicy"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Root or policy domain"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Policy operator"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Strong policy quorum"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Author role"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Emergency recovery"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transfer operations"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v0_CreateTransactionOrder"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Operational domains"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transaction operator"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Amount and risk-based workflow"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Amount, ledger, destination, trust score"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["High-control fallback"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Quarantine release"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v0_ReleaseQuarantinedTransfers"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Compliance domain"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Compliance"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Compliance quorum"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Screening or quarantine state"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Manual review"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For any workflow that will use API-only system-signed proposals, record the policy ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["intentOrigin"]},", service submitter role or subject, allowed intent types, and whether the proposal should auto-approve or still require user approvals."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"rank-and-fallback-strategy","__idx":3},"children":["Rank and fallback strategy"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Specific policies should outrank generic policies. Catch-all and fallback policies should be low rank and high control."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Policy type"},"children":["Policy type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Rank guidance"},"children":["Rank guidance"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Specific high-risk operation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Higher than the generic policy for the same intent type."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Routine operation"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Standard rank for the workflow."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Catch-all fallback"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Low rank so specific policies are selected first."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Breakglass"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["High rank only for explicit emergency intent types and scope."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Avoid high-rank policies with no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["intentTypes"]}," unless that is the deliberate emergency design and quorum can be satisfied."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"breakglass-and-recovery","__idx":4},"children":["Breakglass and recovery"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Breakglass is part of a good genesis design when the organization needs an emergency path for court orders, urgent freezes, lost access, or remediation. It should have:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Explicit intent types."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Deliberate domain scope."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["High quorum."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Independent approvers."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A documented operating runbook."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Breakglass should not become a generic way to bypass normal workflows."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"compliance-and-screening","__idx":5},"children":["Compliance and screening"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If compliance screening is part of launch, map:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Compliance domains."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Compliance users and read access."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Quarantine release policies."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Exception workflows."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Escalation paths for high-risk results."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"genesis-policy-examples","__idx":6},"children":["Genesis policy examples"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Policies embedded in the genesis payload use the same fields as policy creation, but they are embedded in a domain's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["policies"]}," array and do not include a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," field. For post-genesis policy creation, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/governance/policies/manage-policies#create-a-policy-with-the-api"},"children":["Manage policies"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By default, policies match user-signed proposals. Add ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["intentOrigin: \"SystemSigned\""]}," only for policies that should match API-only system-signed proposals."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"policy-governance","__idx":7},"children":["Policy governance"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use a policy-governance policy to control creation, updates, locking, and unlocking of other policies."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"5b440ba5-d013-11eb-8cd0-dcfb48cfb3cb\",\n  \"alias\": \"policy-governance\",\n  \"rank\": 700,\n  \"intentTypes\": [\n    \"v0_CreatePolicy\",\n    \"v0_UpdatePolicy\",\n    \"v0_LockPolicy\",\n    \"v0_UnlockPolicy\"\n  ],\n  \"scope\": \"Self\",\n  \"scriptingEngine\": \"Javascript_v0\",\n  \"condition\": {\n    \"expression\": \"context.references.users[context.request.author.id].roles.includes('policy-operator')\",\n    \"type\": \"Expression\"\n  },\n  \"workflow\": [\n    {\n      \"left\": {\n        \"role\": \"policy-operator\",\n        \"quorum\": 2,\n        \"type\": \"RoleQuorum\"\n      },\n      \"right\": {\n        \"role\": \"compliance\",\n        \"quorum\": 1,\n        \"type\": \"RoleQuorum\"\n      },\n      \"type\": \"And\"\n    }\n  ],\n  \"lock\": \"Unlocked\",\n  \"description\": \"Controls policy lifecycle operations.\",\n  \"customProperties\": {}\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"high-value-transfer","__idx":8},"children":["High-value transfer"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use a high-value transfer policy to require compliance approval above a threshold."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"0efa137d-5f59-4d3e-b720-06185c48ebbe\",\n  \"alias\": \"high-value-ethereum-transfer\",\n  \"rank\": 500,\n  \"intentTypes\": [\"v0_CreateTransactionOrder\"],\n  \"scope\": \"SelfAndDescendants\",\n  \"scriptingEngine\": \"Javascript_v0\",\n  \"condition\": {\n    \"expression\": \"context.references.users[context.request.author.id].roles.includes('transaction-operator') && context.references.accounts[context.request.payload.accountId].ledgerId == 'ethereum-testnet' && context.request.payload.hasOwnProperty('parameters') && context.request.payload.parameters != null && context.request.payload.parameters.hasOwnProperty('amount') && BigInt(context.request.payload.parameters.amount) >= 5000000000000000000n\",\n    \"type\": \"Expression\"\n  },\n  \"workflow\": [\n    {\n      \"left\": {\n        \"role\": \"transaction-operator\",\n        \"quorum\": 1,\n        \"type\": \"RoleQuorum\"\n      },\n      \"right\": {\n        \"role\": \"compliance\",\n        \"quorum\": 2,\n        \"type\": \"RoleQuorum\"\n      },\n      \"type\": \"And\"\n    }\n  ],\n  \"lock\": \"Unlocked\",\n  \"description\": \"Escalates high-value Ethereum transfers.\",\n  \"customProperties\": {}\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"catch-all-fallback","__idx":9},"children":["Catch-all fallback"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use a low-rank fallback policy to catch legitimate workflows that were not covered by more specific policies. Omit ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["intentTypes"]}," only when a catch-all policy is intentional."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"ed6a0b68-d18c-4d14-8ad6-0e9e595fa0d6\",\n  \"alias\": \"fallback-governance\",\n  \"rank\": 10,\n  \"scope\": \"SelfAndDescendants\",\n  \"scriptingEngine\": \"Javascript_v0\",\n  \"condition\": {\n    \"expression\": \"context.references.users[context.request.author.id].roles.includes('platform-admin') || context.references.users[context.request.author.id].roles.includes('policy-operator') || context.references.users[context.request.author.id].roles.includes('transaction-operator')\",\n    \"type\": \"Expression\"\n  },\n  \"workflow\": [\n    {\n      \"left\": {\n        \"left\": {\n          \"role\": \"platform-admin\",\n          \"quorum\": 1,\n          \"type\": \"RoleQuorum\"\n        },\n        \"right\": {\n          \"role\": \"policy-operator\",\n          \"quorum\": 1,\n          \"type\": \"RoleQuorum\"\n        },\n        \"type\": \"Or\"\n      },\n      \"right\": {\n        \"role\": \"transaction-operator\",\n        \"quorum\": 1,\n        \"type\": \"RoleQuorum\"\n      },\n      \"type\": \"Or\"\n    },\n    {\n      \"role\": \"compliance\",\n      \"quorum\": 2,\n      \"type\": \"RoleQuorum\"\n    }\n  ],\n  \"lock\": \"Unlocked\",\n  \"description\": \"Low-rank fallback for unexpected governed workflows.\",\n  \"customProperties\": {}\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"output","__idx":10},"children":["Output"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By the end of this step, you should have:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Initial policy set."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Coverage matrix."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Rank strategy."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Fallback policy."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Breakglass and recovery policy design."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Compliance policy design, if applicable."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For implementation examples, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/governance/policies/examples"},"children":["Policy examples"]},". For policy fields, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/custody/v1.38/governance/policies/reference"},"children":["Policy reference"]},"."]}]},"headings":[{"value":"Design your policies","id":"design-your-policies","depth":1},{"value":"Start with workflows","id":"start-with-workflows","depth":2},{"value":"Policy coverage matrix","id":"policy-coverage-matrix","depth":2},{"value":"Rank and fallback strategy","id":"rank-and-fallback-strategy","depth":2},{"value":"Breakglass and recovery","id":"breakglass-and-recovery","depth":2},{"value":"Compliance and screening","id":"compliance-and-screening","depth":2},{"value":"Genesis policy examples","id":"genesis-policy-examples","depth":2},{"value":"Policy governance","id":"policy-governance","depth":3},{"value":"High-value transfer","id":"high-value-transfer","depth":3},{"value":"Catch-all fallback","id":"catch-all-fallback","depth":3},{"value":"Output","id":"output","depth":2}],"frontmatter":{"seo":{"title":"Design your policies"}},"lastModified":"2026-07-27T10:10:43.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/custody/v1.38/governance/genesis/design-your-policies","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}