Govern MPTs with policies

This guide shows how to write Ripple Custody policies that control Multi-Purpose Token (MPT) operations on the XRP Ledger, including requiring compliance approval for clawbacks, restricting who can create a new MPT issuance, and enforcing dual control on freeze actions.

• Ripple Custody v1.32 or later (MPT issuer operations are available from v1.32; holder operations from v1.31).
• An XRPL account registered in Ripple Custody as the MPT issuer.
• Familiarity with policy conditions and the v0_CreatePolicy payload structure.
• A set of user roles defined in your domain that reflects how your organisation separates duties. The examples below use illustrative names like transaction-operator, treasury-operator, compliance, and cfo; substitute the equivalents that already exist in your deployment.

Two characteristics of MPTs affect how you write matching conditions:

1. MPT operations do not have dedicated intent types. Every MPT action — create, mint, burn, freeze, clawback, destroy — is submitted as a v0_CreateTransactionOrder intent. Policies that filter only by intentTypes: ["v0_CreateTransactionOrder"] match every XRPL and EVM transaction, not just MPT ones.
2. The specific MPT operation is located at context.request.payload.parameters.operation.type. Policy conditions must inspect this path to target an individual operation.

The following table maps each MPT action to the condition expression that identifies it. All expressions assume the intent is a v0_CreateTransactionOrder with payload.parameters.type == "XRPL".

For full payload examples of each operation, see Multi-purpose tokens.

Before deploying any policy from this page, review and replace the following. None of these values are platform defaults — they vary by deployment:

Once adapted, install each policy with lock: "Locked" first, unlock it, submit a representative intent from a test account, and confirm via GET /v1/domains/{domainId}/intents/{intentId}.state.progressPerPolicy[].policyReference.id that the intended policy is matched before rolling out further.

Clawback lets an issuer reclaim tokens from a holder without consent. One common pattern is to require the submitting operator plus two compliance approvers on every clawback; adjust the roles and quorum to fit your approval policy.

{
  "payload": {
    "id": "{{policy_id}}",
    "alias": "mpt-clawback-requires-compliance",
    "rank": 780,
    "intentTypes": ["v0_CreateTransactionOrder"],
    "scope": "Self",
    "scriptingEngine": "Javascript_v0",
    "condition": {
      "type": "Expression",
      "expression": "context.request.payload.parameters.type == 'XRPL' && context.request.payload.parameters.operation != null && context.request.payload.parameters.operation.type == 'Clawback' && context.request.payload.parameters.operation.currency.type == 'MultiPurposeToken'"
    },
    "workflow": [
      {
        "type": "And",
        "left":  { "type": "RoleQuorum", "role": "transaction-operator", "quorum": 1 },
        "right": { "type": "RoleQuorum", "role": "compliance",           "quorum": 2 }
      }
    ],
    "lock": "Unlocked",
    "customProperties": {},
    "type": "v0_CreatePolicy"
  }
}

If your policy is that only one or two operational accounts should ever create new MPT issuances, you can pin creation to a specific account UUID. The example below pins to a single UUID and requires treasury plus compliance approval; replace the placeholder UUID with the issuer account in your deployment.

{
  "payload": {
    "id": "{{policy_id}}",
    "alias": "mpt-issuance-create-pinned-account",
    "rank": 790,
    "intentTypes": ["v0_CreateTransactionOrder"],
    "scope": "SelfAndDescendants",
    "scriptingEngine": "Javascript_v0",
    "condition": {
      "type": "Expression",
      "expression": "context.request.payload.parameters != null && context.request.payload.parameters.operation != null && context.request.payload.parameters.operation.type == 'MPTokenIssuanceCreate' && context.request.payload.accountId == '11111111-2222-3333-4444-555555555555'"
    },
    "workflow": [
      {
        "type": "And",
        "left":  { "type": "RoleQuorum", "role": "treasury-operator", "quorum": 1 },
        "right": { "type": "RoleQuorum", "role": "compliance",        "quorum": 2 }
      }
    ],
    "lock": "Unlocked",
    "customProperties": {},
    "type": "v0_CreatePolicy"
  }
}

To reject MPT issuance creation from any other account, pair the policy above with a lower-ranked catch-all that has an empty workflow array. An empty workflow auto-rejects every matching intent.

{
  "payload": {
    "id": "{{policy_id}}",
    "alias": "mpt-issuance-create-reject-other-accounts",
    "rank": 770,
    "intentTypes": ["v0_CreateTransactionOrder"],
    "scope": "SelfAndDescendants",
    "scriptingEngine": "Javascript_v0",
    "condition": {
      "type": "Expression",
      "expression": "context.request.payload.parameters != null && context.request.payload.parameters.operation != null && context.request.payload.parameters.operation.type == 'MPTokenIssuanceCreate'"
    },
    "workflow": [],
    "lock": "Unlocked",
    "customProperties": {},
    "type": "v0_CreatePolicy"
  }
}

The pinned-account policy (rank 790) is evaluated first and applies to the authorized account. The catch-all (rank 770) applies only when the first policy does not match, and rejects the intent.

Freezing a holder or the entire issuance can halt all transfers of the token, so dual control is a common control point. The example below applies a maker-checker workflow to both freeze and unfreeze actions in one policy; you can split into two policies if the two actions merit different approval paths.

{
  "payload": {
    "id": "{{policy_id}}",
    "alias": "mpt-freeze-unfreeze-dual-control",
    "rank": 785,
    "intentTypes": ["v0_CreateTransactionOrder"],
    "scope": "Self",
    "scriptingEngine": "Javascript_v0",
    "condition": {
      "type": "Expression",
      "expression": "context.request.payload.parameters.operation != null && context.request.payload.parameters.operation.type == 'MPTokenIssuanceSet' && (context.request.payload.parameters.operation.flags.includes('tfMPTLock') || context.request.payload.parameters.operation.flags.includes('tfMPTUnlock'))"
    },
    "workflow": [
      { "type": "RoleQuorum", "role": "transaction-operator", "quorum": 1 },
      { "type": "RoleQuorum", "role": "compliance",           "quorum": 1 }
    ],
    "lock": "Unlocked",
    "customProperties": {},
    "type": "v0_CreatePolicy"
  }
}

To apply different workflows for freeze and unfreeze, create two policies with distinct conditions: one that checks flags.includes('tfMPTLock'), and one that checks flags.includes('tfMPTUnlock').

Mint, burn, and holder-to-holder transfers all use the Payment operation. The example below shows how to add an amount-based threshold: any MPT payment at or above 1000000n base units requires CFO approval. The threshold value, the role, and the quorum are illustrative — pick values that match your own risk appetite and role taxonomy. Guard operation.currency first because it is optional on the Payment schema.

{
  "payload": {
    "id": "{{policy_id}}",
    "alias": "mpt-large-payment-cfo-approval",
    "rank": 760,
    "intentTypes": ["v0_CreateTransactionOrder"],
    "scope": "Self",
    "scriptingEngine": "Javascript_v0",
    "condition": {
      "type": "Expression",
      "expression": "context.request.payload.parameters.operation != null && context.request.payload.parameters.operation.type == 'Payment' && context.request.payload.parameters.operation.currency != null && context.request.payload.parameters.operation.currency.type == 'MultiPurposeToken' && BigInt(context.request.payload.parameters.operation.amount) >= 1000000n"
    },
    "workflow": [
      {
        "type": "And",
        "left":  { "type": "RoleQuorum", "role": "transaction-operator", "quorum": 1 },
        "right": { "type": "RoleQuorum", "role": "cfo",                  "quorum": 1 }
      }
    ],
    "lock": "Unlocked",
    "customProperties": {},
    "type": "v0_CreatePolicy"
  }
}

If the token's assetScale is 6, the threshold 1000000n corresponds to one display unit. Adjust the threshold to match the issuance's decimal precision.

MPTokenIssuanceDestroy permanently retires an MPT once supply reaches zero, so deployments typically set a high approval bar for it. The example below requires treasury plus two compliance approvers; adjust to fit your control framework.

{
  "payload": {
    "id": "{{policy_id}}",
    "alias": "mpt-destroy-issuance-high-bar",
    "rank": 795,
    "intentTypes": ["v0_CreateTransactionOrder"],
    "scope": "SelfAndDescendants",
    "scriptingEngine": "Javascript_v0",
    "condition": {
      "type": "Expression",
      "expression": "context.request.payload.parameters.operation != null && context.request.payload.parameters.operation.type == 'MPTokenIssuanceDestroy'"
    },
    "workflow": [
      {
        "type": "And",
        "left":  { "type": "RoleQuorum", "role": "treasury-operator", "quorum": 1 },
        "right": { "type": "RoleQuorum", "role": "compliance",        "quorum": 2 }
      }
    ],
    "lock": "Unlocked",
    "customProperties": {},
    "type": "v0_CreatePolicy"
  }
}

Policies are evaluated in descending rank order. If a generic v0_CreateTransactionOrder policy has a higher rank than the MPT-specific policies, it captures the intent first and the MPT rules never apply. Always give MPT-specific policies a higher rank than the generic transaction policy.

If any part of the path in a condition resolves to null at evaluation time, accessing a nested property throws a TypeError and the intent terminates with status: "Failed" and error code PolicyScriptingExecutionFailed. This is not a quiet non-match — the intent is rejected entirely and never reaches later policies or execution. Guard every optional nested access with != null:

context.request.payload.parameters.operation != null &&
context.request.payload.parameters.operation.type == 'Clawback'

Do not use hasOwnProperty for these guards. The policy scripting engine re-serializes the parsed domain object before evaluation, and the serializer emits every optional field as "key": null rather than omitting it. The key is always present on the JSON the condition sees, so hasOwnProperty always returns true and provides no protection. Use != null consistently — it catches both the null and undefined cases.

MPT amount and value fields are serialized as strings and can exceed JavaScript's safe integer range. Use BigInt(...) around the field and the n suffix on literals in the condition. Comparing as plain numbers silently loses precision for large values.

Dry-run validates the JSON schema and that the condition parses as JavaScript. It does not validate that path expressions resolve against a real intent and it does not simulate workflow: [] rejection. Runtime errors surface only when an actual v0_CreateTransactionOrder intent is submitted.

To validate behaviour safely:

1. Deploy the policy with lock: "Locked" initially so it does not affect production traffic.
2. Unlock the policy and submit a representative MPT intent from a test account.
3. Fetch GET /v1/domains/{domainId}/intents/{intentId} and inspect state.status (Rejected / Executed / Open) and state.progressPerPolicy[].policyReference.id to confirm the expected policy matched.
4. If state.status is Failed with error.code == "PolicyScriptingExecutionFailed", the condition threw at runtime — add or tighten a != null guard on the nested access that resolved to null.

• Multi-purpose tokens concepts — MPT lifecycle, flags, and on-chain metadata.
• Multi-purpose tokens (API) — Payload reference for each MPT operation.
• Policy conditions — context object and JavaScript expression syntax.
• Create policies — v0_CreatePolicy payload structure.
• Policy examples — Worked policy patterns for other intent types.
• Multi-purpose tokens (XRPL documentation) — Protocol-level reference.