# Design your policies

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.

## Start with workflows

List the workflows that must operate on day one:

| Workflow area | Coverage to design |
|  --- | --- |
| Root administration | Domain, user, role, policy, vault, and platform-level operations. |
| User management | Creating users, changing roles, locking users, and unlocking users. |
| Policy management | Creating, updating, locking, and unlocking policies. |
| Domain operations | Creating, updating, locking, and unlocking domains. |
| Transaction operations | Transfer creation, amount thresholds, trusted endpoints, and exceptions. |
| Compliance and screening | Quarantine release, screening exceptions, and compliance escalation. |
| Breakglass and recovery | Emergency remediation with stronger approval. |
| Fallback | Catch unexpected workflows without weakening specific controls. |


## Policy coverage matrix

Create a matrix before writing JSON:

| Workflow | Intent types | Domain scope | Maker role | Approval workflow | Condition | Fallback |
|  --- | --- | --- | --- | --- | --- | --- |
| User management | `v0_CreateUser`, `v0_UpdateUser` | Root or admin domain | User admin | Second user admin plus compliance if needed | Author role or target role | Low-rank catch-all |
| Policy management | `v0_CreatePolicy`, `v0_UpdatePolicy` | Root or policy domain | Policy operator | Strong policy quorum | Author role | Emergency recovery |
| Transfer operations | `v0_CreateTransactionOrder` | Operational domains | Transaction operator | Amount and risk-based workflow | Amount, ledger, destination, trust score | High-control fallback |
| Quarantine release | `v0_ReleaseQuarantinedTransfers` | Compliance domain | Compliance | Compliance quorum | Screening or quarantine state | Manual review |


For any workflow that will use API-only system-signed proposals, record the policy `intentOrigin`, service submitter role or subject, allowed intent types, and whether the proposal should auto-approve or still require user approvals.

## Rank and fallback strategy

Specific policies should outrank generic policies. Catch-all and fallback policies should be low rank and high control.

| Policy type | Rank guidance |
|  --- | --- |
| Specific high-risk operation | Higher than the generic policy for the same intent type. |
| Routine operation | Standard rank for the workflow. |
| Catch-all fallback | Low rank so specific policies are selected first. |
| Breakglass | High rank only for explicit emergency intent types and scope. |


Avoid high-rank policies with no `intentTypes` unless that is the deliberate emergency design and quorum can be satisfied.

## Breakglass and recovery

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:

- Explicit intent types.
- Deliberate domain scope.
- High quorum.
- Independent approvers.
- A documented operating runbook.


Breakglass should not become a generic way to bypass normal workflows.

## Compliance and screening

If compliance screening is part of launch, map:

- Compliance domains.
- Compliance users and read access.
- Quarantine release policies.
- Exception workflows.
- Escalation paths for high-risk results.


## Genesis policy examples

Policies embedded in the genesis payload use the same fields as policy creation, but they are embedded in a domain's `policies` array and do not include a `type` field. For post-genesis policy creation, see [Manage policies](/products/custody/v1.36/governance/policies/manage-policies#create-a-policy-with-the-api).

By default, policies match user-signed proposals. Add `intentOrigin: "SystemSigned"` only for policies that should match API-only system-signed proposals.

### Policy governance

Use a policy-governance policy to control creation, updates, locking, and unlocking of other policies.


```json
{
  "id": "5b440ba5-d013-11eb-8cd0-dcfb48cfb3cb",
  "alias": "policy-governance",
  "rank": 700,
  "intentTypes": [
    "v0_CreatePolicy",
    "v0_UpdatePolicy",
    "v0_LockPolicy",
    "v0_UnlockPolicy"
  ],
  "scope": "Self",
  "scriptingEngine": "Javascript_v0",
  "condition": {
    "expression": "context.references.users[context.request.author.id].roles.includes('policy-operator')",
    "type": "Expression"
  },
  "workflow": [
    {
      "left": {
        "role": "policy-operator",
        "quorum": 2,
        "type": "RoleQuorum"
      },
      "right": {
        "role": "compliance",
        "quorum": 1,
        "type": "RoleQuorum"
      },
      "type": "And"
    }
  ],
  "lock": "Unlocked",
  "description": "Controls policy lifecycle operations.",
  "customProperties": {}
}
```

### High-value transfer

Use a high-value transfer policy to require compliance approval above a threshold.


```json
{
  "id": "0efa137d-5f59-4d3e-b720-06185c48ebbe",
  "alias": "high-value-ethereum-transfer",
  "rank": 500,
  "intentTypes": ["v0_CreateTransactionOrder"],
  "scope": "SelfAndDescendants",
  "scriptingEngine": "Javascript_v0",
  "condition": {
    "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",
    "type": "Expression"
  },
  "workflow": [
    {
      "left": {
        "role": "transaction-operator",
        "quorum": 1,
        "type": "RoleQuorum"
      },
      "right": {
        "role": "compliance",
        "quorum": 2,
        "type": "RoleQuorum"
      },
      "type": "And"
    }
  ],
  "lock": "Unlocked",
  "description": "Escalates high-value Ethereum transfers.",
  "customProperties": {}
}
```

### Catch-all fallback

Use a low-rank fallback policy to catch legitimate workflows that were not covered by more specific policies. Omit `intentTypes` only when a catch-all policy is intentional.


```json
{
  "id": "ed6a0b68-d18c-4d14-8ad6-0e9e595fa0d6",
  "alias": "fallback-governance",
  "rank": 10,
  "scope": "SelfAndDescendants",
  "scriptingEngine": "Javascript_v0",
  "condition": {
    "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')",
    "type": "Expression"
  },
  "workflow": [
    {
      "left": {
        "left": {
          "role": "platform-admin",
          "quorum": 1,
          "type": "RoleQuorum"
        },
        "right": {
          "role": "policy-operator",
          "quorum": 1,
          "type": "RoleQuorum"
        },
        "type": "Or"
      },
      "right": {
        "role": "transaction-operator",
        "quorum": 1,
        "type": "RoleQuorum"
      },
      "type": "Or"
    },
    {
      "role": "compliance",
      "quorum": 2,
      "type": "RoleQuorum"
    }
  ],
  "lock": "Unlocked",
  "description": "Low-rank fallback for unexpected governed workflows.",
  "customProperties": {}
}
```

## Output

By the end of this step, you should have:

- Initial policy set.
- Coverage matrix.
- Rank strategy.
- Fallback policy.
- Breakglass and recovery policy design.
- Compliance policy design, if applicable.


For implementation examples, see [Policy examples](/products/custody/v1.36/governance/policies/examples). For policy fields, see [Policy reference](/products/custody/v1.36/governance/policies/reference).