# 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.

## Behavioral changes

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](/products/custody/v1.36/reference/api/openapi/accounts/getaccountbalances) 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.


## Prerequisites

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.


External accounts
Transactions using external accounts (Coinbase) are not supported by the new accounting flow. If you use external accounts, deploy the release but keep `HMZ_TEMPORAL_MIGRATION_ENABLED` and `HMZ_ACCOUNTING_SERVER_ENABLED` set to `false`, and do not run this migration.

## Migration procedure

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](/products/custody/v1.36/reference/api/openapi/accounts/forceupdateaccountbalances) to sync on-chain balances with the accounting service.


## Known issues and limitations

- **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](/products/custody/v1.36/reference/api/openapi/accounts/forceupdateaccountbalances) 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](/products/custody/v1.36/reference/api/openapi/accounts/forceupdateaccountbalances) to sync balances.


## Related documentation

- [Ripple Custody 1.34 release notes](/products/custody/v1.36/support/change-history/v134)
- [Get account balances](/products/custody/v1.36/reference/api/openapi/accounts/getaccountbalances)
- [Transaction processing](/products/custody/v1.36/transactions/processing)


## Support

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