# Domain injection

Introduced in Ripple Custody v1.20, domain injection is the action of introducing a new domain between an existing parent domain and its child domains. Domain injection is suitable for scenarios where you want an existing child domain(s) to inherit a specific set of policies from its parent domain, where adding those policies to the parent domain would otherwise adversely affect other existing child domain(s). By injecting a domain with a specific set of policies between the existing child domain(s) and its parent, the reparented child domain(s) will inherit those policies.

## Impact of domain injection on child domains

When you inject a new parent domain, all open intents in child domain(s) remain unaffected by applicable policies from the newly added parent domain. Policies from the newly added parent domain will only apply to the intents in the child domain(s) that are created ***after*** the new parent domain is introduced.

Minimize disruptions
We recommend doing the domain injection during a period of low or no transaction activity in your Ripple Custody instance. This is to minimize any possible disruptions to pending transactions.

## Inject a domain

The following sections walk you through an example of injecting a new parent domain between the current domain and two existing child domains. We perform the domain injection by proposing an intent using the Ripple Custody API.

### Prerequisites

To successfully create an intent to inject a domain:

* You must be an administrator of the parent domain under which you want to inject a new domain.
* You must have the domain ID of the child domain(s) that you want to reparent.
* The `lock` status of the child domain(s) that you want to reparent under the newly injected domain must be `Unlocked`. If you're reparenting multiple domains, the domain injection will fail if any of the child domains are in the `Locked` state.


You can find the child domain's ID in the following ways:

* By going to the **Domains** page in the Ripple Custody UI. For more information, see [View domain details](/products/custody/v1.26/ui/environment/domain/view).
* By calling the [Get domain details](/products/custody/v1.26/api/reference/openapi/domains/getdomain) API operation.


### Step 1: Prepare the request body to create and inject a domain

Prepare the request body in the standard intent proposal format, with a `payload` block similar to the example shown in [Create domain payload example for domain injection](#createdomain-payload-example-for-domain-injection).

For the domain injection use case, you must include the `childrenDomainIds` array containing the domain IDs of all the child domains that you want to reparent. If you don't include this parameter, the newly created domain will not have any child domains associated with it. For more information, see [Propose an intent request body](/products/custody/v1.26/api/reference/intent-structure#propose-an-intent-request-body).

### Step 2: Perform an intent proposal dry run to inject a domain

This step is optional, but highly recommended. A dry run can reveal errors or unintended consequences for the intent.

Call the [Perform a dry run for an intent](/products/custody/v1.26/api/reference/openapi/intents/intentdryrun) operation. For more information, see [Dry run intents](/products/custody/v1.26/api/get-started/key-operations/update/dry-run). You can repeat this step more than once to obtain the required result.

Once you're satisfied with the response, you can propose the intent to inject the domain as shown in the next section.

### Step 3: Propose an intent to inject a domain

Sign the request body and call the [Propose an intent](/products/custody/v1.26/api/reference/openapi/intents/createintent) operation. For more information, see [Propose an intent to create an entity](/products/custody/v1.26/api/get-started/key-operations/update/intent-proposal#propose-an-intent-to-create-an-entity).

Check the update. For more information, see [Check updates](/products/custody/v1.26/api/get-started/key-operations/update/check).

### CreateDomain payload example for domain injection

The following example shows how to structure the `payload` for a `v0_CreateDomain` intent type to create and inject a new domain between the current domain and two existing domains which are the children of the current domain. In the `childrenDomainIds` array, list the domain IDs of the child domains you want to reparent.


```json
{
    "payload": {
        "id": "6c460500-5aa9-47cc-b3b0-20264331e995",
        "alias": "Alias for domain with id 6c460500-5aa9-47cc-b3b0-20264331e995",
        "lock": "Unlocked",
        "governingStrategy": ...,
        "permissions": {...},
        "description": "Description for domain with id 6c460500-5aa9-47cc-b3b0-20264331e995",
        "customProperties": {},
        "users": [...],
        "policies": [...],
        "childrenDomainIds": [
            "c53e9275-7754-44d6-b029-00b14b51cefd",
            "6c460500-5aa9-47cc-b3b0-20264331e995"
        ],
        "type": "v0_CreateDomain"
    }
}
```