Ledger accounting migration guide (v1.34 LTS)

Ripple Custody version 1.34 migrates core balance tracking and transaction processing to a new event-driven accounting service. This guide describes the behavioral changes the new service introduces for API integrations and the one-time migration procedure for on-premise deployments.

The behavioral changes apply to all deployments. The migration procedure applies to on-premise deployments only; Ripple manages the migration for SaaS deployments.

Review these changes and update your integrations before you migrate:

• Use the availableAmount balance field. The accounting service computes the available balance directly. The old formula, totalAmount - reservedAmount - quarantinedAmount, can produce incorrect results in some situations, such as an incoming transaction in the Detected state. Use the availableAmount field from Get account balances instead.
• Inbound processing status. The processing status of inbound transactions is now tracked and populated, in addition to outbound transactions.
• Concurrent processing. Transactions are processed concurrently. There is no guarantee that transactions are processed in the order you submit them. If your integration depends on submission order, enforce the ordering on your side.
• One sender per transfer. The new accounting service supports one sender per transfer.

Before starting the migration, confirm that:

• Your release package includes the new accounting services and their Helm charts.
• You have a maintenance window: the migration requires you to stop accepting new requests until it completes.
• You can port-forward to the transaction processor, which exposes the balance migration API.
• You have a current backup of your database.

Migrating to the new accounting flow is a one-time process:

1. Deploy the release with HMZ_TEMPORAL_MIGRATION_ENABLED and HMZ_ACCOUNTING_SERVER_ENABLED set to false, and deploy all the new services with Helm. Confirm the system operates normally before continuing — this isolates the accounting migration from the release's unrelated changes.
2. Make sure there are no in-flight outgoing transactions, and stop accepting new requests (such as new outgoing transactions or quarantine releases) until the migration completes.
3. Set HMZ_TEMPORAL_MIGRATION_ENABLED and HMZ_ACCOUNTING_SERVER_ENABLED to true and restart all services.
4. Start the balance migration by calling the transaction processor's balance migration API (POST /v1/api/txnprocessor/accounts/balance-migration; this requires a port forward), and monitor the balance-migration workflow until it completes.
5. Validate by re-running the balance migration with dryRun: true. If the workflow result shows balanceAdjusted: true, some accounts are out of sync — typically because balances changed during migration — and you can re-run the migration.
6. Resume normal operations. If account balances are found out of sync after migration, run a force balance refresh to sync on-chain balances with the accounting service.

• IBM s390x: Temporal does not support IBM s390x architecture.
• External accounts: Transactions using external accounts (Coinbase) are not supported by the new flow. If you use external accounts, deploy the release but keep HMZ_TEMPORAL_MIGRATION_ENABLED and HMZ_ACCOUNTING_SERVER_ENABLED set to false.
• Staking balance sync: During Substrate staking operations, balances can go out of sync; run a force balance refresh after the operations complete. A fix follows the LTS release. Balances also go out of sync when staking rewards are paid out on Cardano and Ethereum — as in previous releases — so run force balance refresh after rewards payouts.
• ERC20 transfer event accuracy: The platform tracks token movements through ERC20 Transfer events. If a buggy or non-compliant contract emits Transfer events without moving balances, transaction history shows transfers that didn't move funds. This is an inherent blockchain limitation, unchanged from previous releases, and compliant contracts are not affected. After interacting with such a contract, run a force balance refresh to sync balances.

• Ripple Custody 1.34 release notes
• Get account balances
• Transaction processing

For additional assistance with the migration, contact your Customer Partner Engineer (CPE) or Ripple Support.