Address Swap Split Map

Address Swap Split is a process used during the creation of a Stardust Objects snapshot from a Hornet snapshot. This process ensures that some assets, i.e., IOTA tokens and timelocked IOTA tokens, in the Hornet snapshot are reallocated to new addresses specified in a CSV Address Swap Split Map.

During the migration process, the system checks whether the address of the Address Unlock Condition of each output is present in the Address Swap Split Map as an Origin Address. If it is, this address is replaced with the corresponding Destination Address specified in the map. However, differently from the Address Swap Map, here possibly not all outputs are swapped. The amount (in nanos) of IOTA tokens and timelocked IOTA tokens to be swapped to is indicated in the Address Swap Split Map as Tokens and TokensTimelocked numerical values. In addition, there may be multiple Destination Addresses associated with the same Origin Address. All of this means that, probably, during this process, some outputs could be split.

To ensure correctness, the ledger state is verified during the migration. This involves double-checking that all the Tokens and TokensTimelocked amount targets have been met after all outputs contained in the Hornet snapshot have been processed. If a target remains unsatisfied, an error is returned, which means that the Address Swap Split Map was constructed with some amount targets that are greater than the value of the assets owned by the Origin Address in the Hornet snapshot.

After that the Address Swap Split operation has been performed, some assets might still be owned by the indicated Origin Addresses. This means that the Address Swap Map can be used to swap these remainder assets to a new Destination Address.

Address Swap Split Map CSV format:

This must be a CSV file with four columns, where an entry contains in the first column an Bech32 format present in the Hornet full-snapshot, in the second column an IotaAddress that will be used for the swap, and in the other columns the tokens target amounts.

  • Columns: Origin: The address in the Hornet snapshot from which assets are taken. Type - bech32. Destination: The new address where assets are allocated in the Stardust Object snapshot. Type - IotaAddress. Tokens: The amount of IOTA tokens to swap indicated in NANO. Type - u64. TokensTimelocked: The amount of timelocked IOTA tokens to swap indicated in NANO. Type - u64.
  • Constraints: Origin addresses must exist in the Hornet snapshot. Destination addresses must be valid IOTA addresses. The two amounts in nano must represent amounts of assets owned by the Origin addresses in the Hornet snapshot.
Origin,Destination,Tokens,TokensTimelocked
iota1qp8h9augeh6tk3uvlxqfapuwv93atv63eqkpru029p6sgvr49eufyz7katr,0x1336d143de5eb55bcb069f55da5fc9f0c84e368022fd2bbe0125b1093b446313,107667149000,107667149000
iota1qp8h9augeh6tk3uvlxqfapuwv93atv63eqkpru029p6sgvr49eufyz7katr,0x83b5ed87bac715ecb09017a72d531ccc3c43bcb58edeb1ce383f1c46cfd79bec,388647312000,0

How to use Address Swap Split:

  1. Prepare Address Swap Split Map CSV file.
  2. Invoke the iota-genesis-builder command: Use the following command to execute the process:
iota-genesis-builder iota --address-swap-split-map-path address_swap_split.csv ...