Function buildMergeCoinsTransaction

Build a transaction that consolidates all Coin<coinType> objects owned by address into a single coin object or into the address balance (accumulator).

With coin-object output any existing address balance is also withdrawn and merged in, so the full balance ends up in one coin object. With address-balance output the coin objects are sent to the address balance via 0x2::coin::send_funds.

The sender (and gas payer) is address itself. Gas payment must be set explicitly for SUI because the automatic build-time gas resolution can only pick SUI coins that are not inputs of the transaction, and here every SUI coin is one. The largest SUI coin is reserved as the gas coin (it alone must cover the gas budget): with coin-object output everything merges into it, and with address-balance output it stays as a coin object. Exception: with address-balance output, when the pre-existing SUI address balance already exceeds MIN_ADDRESS_BALANCE_FOR_GAS no gas coin is reserved — gas resolves against the address balance and every coin is sent, leaving none behind. (Funds deposited by this same transaction cannot pay its gas, so a first run that leaves the gas coin can be re-run once the address balance is funded.)

Consolidates at most MAX_COINS_PER_TX coin objects per transaction — re-run until one coin object remains.

The address balance is read at build time and withdrawn as an exact amount (the protocol does not support entire-balance withdrawals yet), so concurrent accumulator activity between build and execution fails the transaction with "Invalid withdraw reservation" — rebuild and retry.