Request a change with an intent

In this tutorial you'll learn how to change your system with an intent using the Ripple Custody API.

You can use these steps for the majority of intent types, such as adding and updating entities in your environment, and performing blockchain transactions.

By the end of this tutorial, you should be able to:

• Run a dry run operation to help define the appropriate format and details for your intent.
• Submit an intent for approval.
• Follow the status of an intent through to successful execution.

The workflow to request a change in Ripple Custody is as follows:

1. Perform a dry run — Dry run the transaction to check for errors and get fee estimates.

2. Submit the intent — Request the change.

3. Check the result — Track the status of the request through the system change workflow.

Prepare the payload you want to use, and then run it through a dry run operation. This fulfills two separate objectives:

• Checks the operation for errors.
• If this is a blockchain transaction, obtains an estimate of the fees needed for the transaction.

This step is optional, but highly recommended. The dry run step is especially important for blockchain transactions, as it can help you calculate the cost to execute the transaction on the ledger.

You do not need to authenticate or pay a fee for a dry run, so you can run it as many times as you want.

Prepare the request body of the update you want to request, with a payload block specific to your request. For more information on the standard dry run request body format, see Dry run and signature request body.

The format of the payload block depends on the entity you want to update and, for transaction orders, on the blockchain:

• For environment and accounting entity updates: Use the payload relevant for the entity, such as the one in Create a user.
• For simple blockchain transactions, such as sending assets: Use a transfer order payload, such as the native asset example in Send assets.
• For complex blockchain transactions, such as smart contract deployment: Use a transaction order payload, such as the one in Deploy a smart contract on an EVM ledger.

Learn more about transfer orders and transaction orders Learn more about fee strategies

Perform a dry run with the request body you prepared. For more information, see Perform the dry run.

Ripple Custody returns a response in a format specific to the update request type.

• All responses contain a result of the dry run. If the result is Failure, you can find more details in the reason and hint fields. For more information, see Troubleshooting.
• Transaction responses contain an estimate of the fee amount, which you can use to help define the fee strategy for the transaction.

If you receive an error or want to adjust the fees, update the payload block and run the dry run again.

Now you have an idea of how to format your request and, if applicable, any fees you need to pay for a transaction, you can move on to the creation of the request itself.

Create the request using the steps in Propose intents. You're going to use the request body you created for the dry run.

If you did not provide a requestId, when the transaction returns a status code of 202 Accepted, make a note of the requestId returned in the response body. You're going to use this to track the status of your request.

Once you have submitted your intent, you can track the status of the intent by following it through the standard intent workflow:

1. Request execution.
2. Intent approval.
3. Entity creation.

For more information about the intent workflow, see Governance workflow.

Check the status of the request. If the request itself does not execute successfully, the intent cannot proceed.

To check the status of the request, follow the steps described in Check the request.

Check the status of the intent. You can follow the intent through the approval process.

To check the status of the intent, follow the steps described in Check the intent.

When the intent is successfully approved, check the entity was created or updated as expected.

To check the status of the entity, follow the steps described in Check the entity.

When you check the status of a transaction order entity, you can also view the underlying transaction and transfer entities, as described in View transactions.

The following example shows one failed transaction and one successful transaction:

{
    "items": [
        {
            "id": "660635b0-b2c4-4f09-9558-0b6c6de34851",
            "ledgerId": "stellar-testnet-june-2023",
            "orderReference": {
                "id": "f039c4c4-f537-4fb0-9a37-66638f942398",
                "domainId": "5cd224fe-193e-8bce-c94c-c6c05245e2d1"
            },
            "relatedAccounts": [
                {
                    "id": "7a29d2ff-1349-40f5-ba88-d3bc63086db4",
                    "domainId": "5cd224fe-193e-8bce-c94c-c6c05245e2d1",
                    "sender": true
                }
            ],
            "processing": {
                "hint": "InternalError",
                "status": "Broadcasting"
            },
            "registeredAt": "2023-12-19T13:57:29.889Z",
            "ledgerTransactionData": null
        },
        {
            "id": "e237921b-6606-4d2b-98db-dfc337f09e5d",
            "ledgerId": "solana-devnet",
            "orderReference": {
                "id": "2c4bc542-23f2-48a1-9144-65f614116340",
                "domainId": "5cd224fe-193e-8bce-c94c-c6c05245e2d1"
            },
            "relatedAccounts": [
                {
                    "id": "b0a8c0fb-628c-40c0-ad35-c2eac0214ded",
                    "domainId": "5cd224fe-193e-8bce-c94c-c6c05245e2d1",
                    "sender": false
                },
                {
                    "id": "5e09d9b9-f1e3-456a-acc7-6cfa7440621d",
                    "domainId": "5cd224fe-193e-8bce-c94c-c6c05245e2d1",
                    "sender": true
                }
            ],
            "processing": {
                "status": "Completed"
            },
            "registeredAt": "2023-12-19T13:37:41.812Z",
            "ledgerTransactionData": {
                "ledgerStatus": "Confirmed",
                "failure": null,
                "ledgerTransactionId": "2uiEJqEf3XDaMTC8vfaaagY4Ed4kk6uBAUuxxeub95o9VrmM4C5utGYwPoxMpNdBnLLwz7qCWfMoAmC6GaiVkMZU",
                "rawTransaction": "4oXTpSjpdHj3f8emwFhgopn1F4xCF8G2qgDKMxz4zq4tfeGXbx52J3BpsPqVwWq7kB8f1iCZJdZ7aZwxo6dFjZYkijg6S3DHLeQKvkdD55a1q8Es75n7HHNGkkwkaL5DCDRGZUbSiDXxXc1NuPDqhTxP3f6C6eCYt4S6HEGkuzA5TJSrmaEydTGNNCjwrHXnBcNA5gr5g9zceWqLa9Z6KbQ839kefbjXCUVGqbjUQ49uyUsZBTaUchsLbbGw4ay3F5BYnszfWW2HAvXQhFKANwmtwYF5u3qvD9GST",
                "statusLastUpdatedAt": "2023-12-19T13:38:06.145Z",
                "ledgerData": null
            }
        }
    ],
    "count": 2,
    "currentStartingAfter": null,
    "nextStartingAfter": "d5c8b04e-94da-45d1-91e6-8e952e4c1dbd"
}

The following fields contain information about the status of the transaction:

• processing.status: The status of the transaction in Ripple Custody, along with a hint if the transaction was not executed successfully.
• ledgerTransactionData.ledgerStatus: The status of the transaction on the blockchain.

For more information, see Transaction statuses.

You can find a list of hints and their meanings in the API reference, as follows:

• For dry run failures, see the 200 response schema for the dry run operation, by selecting result.type as Failure.
• For transaction failures, see the 200 response schema for the Get transaction details operation, by selecting the relevant processing.status.