Skip to main content

Migrating from Coin to Address Balances

Address balances introduce a canonical balance system for fungible assets tied to Sui addresses. This supplements the Coin<T> model with direct address-owned balances, simplifying transaction construction and eliminating coin selection complexity.

For the full specification, see SIP-58: Sui Address Balances. For implementation details on sending, withdrawing, and paying gas from address balances, see Using Address Balances.

What changes with address balances?​

This rollout initially has very limited impact:

  • Nothing is deprecated or removed. All transactions that are currently valid continue to be valid. Coin objects are not forcibly migrated to address balances.
  • No contracts need to be rewritten. Contracts can continue to accept Coin<T> and &mut Coin<T> as before.
  • Coins can still be sent through transfer::public_transfer or the TransferObjects command.

What changes for wallets, exchanges, and custody providers?​

Anyone operating a wallet (custodial, non-custodial, or exchange wallets) might be impacted by this change. Users can now send funds to your address through send_funds(), which credits your address balance, instead of transferring a coin object with TransferObjects. If a wallet receives funds this way, but does not have proper support for address balances, the user cannot see or access the funds. The user might then believe the funds have been lost. The funds cannot actually be lost, but this can cause confusion for affected users.

Initially, this should not happen often because most of the ecosystem continues to transfer coin objects. However, because there is no way to prevent funds from arriving at any given wallet through an address balance transfer, wallet implementors should be prepared.

User funds can also become split across both coins and address balances. Balance queries through gRPC or GraphQL show the combined total. To see how much of that total is held in coin objects and how much is held in the address balance, read the separate coinBalance and addressBalance fields described in Changes to balance queries. To send funds that include the address balance portion, you must either:

  • Use coinWithBalance from the TypeScript SDK (v2+), which automatically draws from both sources.
  • Implement manual withdrawal logic as described in Using Address Balances.

What should I check in my integration?​

  • Handle funds that arrive through send_funds() in the address balance, not only funds that arrive as coin objects. See Using Address Balances.
  • Read the combined balance, or the separate coinBalance and addressBalance fields, from the gRPC GetBalance and ListBalances methods or the GraphQL balance and balances fields. See Changes to balance queries.
  • When sending funds that include the address balance portion, use coinWithBalance from the TypeScript SDK (v2+), which draws from both coin objects and the address balance, or manual withdrawal logic as described in Using Address Balances.
  • If you compute balance changes from checkpoint data, process accumulator events (the records of address balance withdrawals and deposits in TransactionEffects, available through effects.accumulator_events()) or use derive_balance_changes. See Changes to balance computation from checkpoint data.
  • Replace legacy JSON-RPC suix_getBalance and suix_getAllBalances calls with the gRPC GetBalance and ListBalances methods from StateService, or the GraphQL balance and balances fields.

Changes to balance queries​

Balance query responses now include address balance information alongside coin object totals.

JSON-RPC (legacy)​

Sui Foundation disabled JSON-RPC on Mainnet full nodes. Do not call suix_getBalance or suix_getAllBalances in new code. The legacy response shape helps you recognize these calls in code you are migrating to the gRPC or GraphQL fields.

The legacy suix_getBalance and suix_getAllBalances response carries a fundsInAddressBalance field, and its totalBalance field combines coin objects and address balance funds:

{
"coinType": "0x2::sui::SUI",
"coinObjectCount": 2,
"totalBalance": "99998990120",
"lockedBalance": {},
"fundsInAddressBalance": "5000000"
}

Getting only the coin-based balance means subtracting fundsInAddressBalance from totalBalance. The gRPC and GraphQL responses return the two amounts as separate fields, so you do not need that arithmetic.

gRPC​

The GetBalance and ListBalances methods from StateService now return separate fields for coin and address balances:

  • coinBalance: Total held in coin objects.
  • addressBalance: Amount held in address balance.
  • balance: Sum of the two.
{
"balance": {
"coinType": "0x2::sui::SUI",
"balance": "99998990120",
"addressBalance": "5000000",
"coinBalance": "99993990120"
}
}

GraphQL​

The balance and balances fields on address types now include addressBalance, coinBalance, and totalBalance fields. See the IAddressable.balance entry in the GraphQL reference for the full schema.

Changes to balance computation from checkpoint data​

Use the balance changes that gRPC or GraphQL provide rather than computing them yourself.

If you compute balance changes from checkpoint data, you must now process accumulator events from TransactionEffects in addition to coin object diffs. Accumulator events are the records of address balance withdrawals and deposits, so coin object diffs alone miss funds that move through address balances.

The Sui framework provides a helper for this process:

use sui_types::balance_change::{derive_balance_changes, BalanceChange};

let balance_changes: Vec<BalanceChange> = derive_balance_changes(
&effects,
&input_objects,
&output_objects,
);

Each BalanceChange contains the address, coin type, and a signed amount (negative for spent, positive for received).

See the reference implementation for the full algorithm.

How do you access accumulator events?​

Accumulator events are embedded in TransactionEffects. Access them through the TransactionEffectsAPI trait:

use sui_types::effects::TransactionEffectsAPI;

let events = effects.accumulator_events();

Each event contains the target address, a balance type, an operation (Split for withdrawal, Merge for deposit), and the amount. See sui-types/src/effects/mod.rs for the full API.

Backward compatibility​

Existing contracts​

Contracts that accept Coin<T> or Balance<T> remain callable without changes. The redeem_funds functions (in the sui::coin and sui::balance modules respectively) convert withdrawals to the expected types within the programmable transaction block (PTB). The following pseudocode shows a PTB that redeems a withdrawal and transfers the resulting coin. It is not a BCS or JSON encoding. For details on the withdrawal<T> input, see Withdrawal inputs in PTBs.

inputs: [withdrawal<0x2::sui::SUI>(100)]
commands:
0: 0x2::coin::redeem_funds(inputs(0))
1: 0x2::transfer::public_transfer(result(0))

Compatibility coin reservations for legacy clients​

A compatibility coin reservation is a synthetic object reference that encodes a withdrawal from an address balance. It has the same shape as a coin object reference (an object ID, a version, and a digest), so a client that only understands coin object references can still spend address balance funds. It is not a persisted Coin<T> object. The digest carries the maximum amount to withdraw, the epoch that the reservation targets, and a fixed marker that identifies the reference as a reservation. A reservation is valid only in that epoch and the following epoch.

Validators recognize a coin reservation by its digest and process it as a withdrawal from the sender's address balance, whether the transaction uses it as an input or as a gas payment. A coin reservation used as a gas payment must reserve the sender's own SUI address balance, so sponsored transactions cannot pay gas with one. The gRPC SimulateTransaction method accepts coin reservations without looking them up as objects. When SimulateTransaction selects gas for a transaction that uses the gas coin as a command argument, and the sender has a SUI address balance, it adds a coin reservation as the first gas payment so the gas coin can draw on that balance.

These reservations exist to preserve basic functionality for older clients that expect coin object references. Do not treat them as normal persisted coin objects. For new development, use address balances directly, as described in Using Address Balances.

When a coin reservation is a gas payment, its position in the gas payment list determines how gas smashing handles it. See How gas smashing handles coin reservations and Gas Smashing.

Do you need to convert existing coins?​

Migration is optional. The SDK automatically selects coins or address balances as needed. To consolidate existing coin objects into an address balance, see Converting Existing Coins to Address Balances in the usage guide.

Troubleshooting​

Why are funds shown in both coin objects and the address balance?​

User funds can be split across coin objects and the address balance of the same address. Balance queries through gRPC or GraphQL return the combined total, and the separate coinBalance and addressBalance fields show each portion. See Changes to balance queries.

Why can a user not see funds that were sent to their address?​

If the sender used send_funds() instead of transferring a coin object, the funds are in the address balance. A wallet without address balance support cannot show or access them, but the funds are not lost. Add address balance support as described in Using Address Balances.

How gas smashing handles coin reservations​

The first entry in the gas payment list is the smash target. The network smashes every other entry into it, and the result depends on where the compatibility coin reservation sits:

  • Reservation after the first position: The network records a withdrawal of the full reserved amount from the address balance. Coin objects in these positions are deleted.
  • Reservation in the first position: The network deposits the value of the other payments into the address balance. The reservation acts only as a maximum withdrawal, and the network withdraws from the address balance only when gas charging requires it.
  • Coin object in the first position: The coin's value becomes the total of all gas payments, including any reserved address balance funds.

Withdrawal inputs in PTBs​

The withdrawal<T> entry in the example is a transaction input, not a PTB command. The PTB command set (MoveCall, MakeMoveVec, TransferObjects, SplitCoins, MergeCoins, Publish, and Upgrade) has no withdrawal command. The input gives Move a Withdrawal<T> value, a struct that records the owner of the funds and a withdrawal limit. You create a Withdrawal as a PTB input for the transaction sender. At signing, the network checks that the limit is less than or equal to the balance. Pass the input to a redeem_funds function to get a Coin<T> or Balance<T>. To take part of a withdrawal, call withdrawal_split.