[migration] Resolve possible inconsistencies when scaling large native token supplies

[kodemartin]

Description

This follows #359 and the adopted scaling approach of large (> u64::MAX) native token supply configurations.

The scaling would be trivial if it weren't for the fact that we deal with integers. And one issue remains with both the direct scaling of all values, and this scaling by equation between circulating and maximum supply:

Any token_amount < 1 / ratio held by basic outputs will reduce to zero. This will lead to an effective 0 <= actual_circulating_amount <= circulating_amount. Can we consider such a ledger state consistent?

See original discussion thread here.

[samuel-rufi]

To resolve this, we could add checks in the executor.rs if native token amount is 0. Then don't create the Coin object.

[miker83z]

Maybe the beste approach would be to print package ids here of the foundries that had the total supply changed. Then check them manually in the explorer.

[Dkwcs]

Explorer

IOTA:

./target/release/iota-genesis-builder --disable-global-snapshot-verification iota --snapshot-path iota_latest-full_snapshot.bin --target-network alphanetv0.1.1

FOUNDRY COIN MANAGER ID: 0x2bcd272cfc0d09be2b9f9469152b29dc7fb719517fb41ed94c6fb34f41a5e2db
MAX SUP BEFORE: 55500000000000003756297923859922812928
MAX SUP AFTER:    18446744073709551614
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0x926bd74b30aca6bf5fbd0dffd9f78b33a27809f5bbce0f2afeba05e5c2dd17e0
MAX SUP BEFORE:  690000000000000000000
MAX SUP AFTER:    18446744073709551614
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0x5fee6f92b8d2dae6c6012d552446c4c30199b7bf623ddcb6c50b7c2d6fcddbd2
MAX SUP BEFORE:  100000000000000000000000000
MAX SUP AFTER:     18446744073709551614
TOTAL SUP AFTER:  18446744073709551614

SHIMMER:

./target/release/iota-genesis-builder --disable-global-snapshot-verification iota --snapshot-path iota_latest-full_snapshot.bin --target-network alphanetv0.1.1

MAX SUP AFTER: 18446744073709551614 for all cases

FOUNDRY COIN MANAGER ID: 0x63d6a80a63b8a2a293be0bf0619bb8dd251aa7ce74dd729db59b7861fca33fea
MAX SUP BEFORE:  10000000000000000905969664
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0x25657ef3ab931b449fa9fa67294c49ec6cd7a2cd006f867739b4da27903c3798
MAX SUP BEFORE:  100000000000000000000
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0x0465ec029540d01612e4a8bc5b74658165f6f30a39f40d4001e0f33a7da128ae
MAX SUP BEFORE:  1000000000000000044885712678075916785549312
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0xfdab91fdce0f0f30b281d8bfbe22068c2bef86f7d5063e7a6c594bf1ebed7cb2
MAX SUP BEFORE:  999999999999999926539781176481198923508803215199467887262646419780362305536
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0x6df508742b2c84f8e38a796fb638deebd73ccc7b9861815c44e908e0c5859a06
MAX SUP BEFORE:  666666666666666622976
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0xe44fcd1f6b9162868abcd87959d4ef582a38ab82b234c218e7212fd669157fb6
MAX SUP BEFORE:  6666666666666667016192
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0xd4b31ad7d601a81a9905541438437a1937d535d77874961ebb3b8833b6d7db5d
MAX SUP BEFORE:  7777777777777777647288320
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0x2af47bcf2c28d4db11a80005812fee7d50c5e18f364f12608c8e20087399c737
MAX SUP BEFORE:  1000000000000000043845843045076197354634047651840
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0x942fa535dd85f4c7c784e0a1cb9d38815fc7eb8824a753409a68c8845b4fb161
MAX SUP BEFORE:  1000000000000000043845843045076197354634047651840
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0x7b329e2ab32052277e5fc4e43a34f3337d00bbb2c8584eacb4aa86d599996dc3
MAX SUP BEFORE:  1000000000000000043845843045076197354634047651840
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0xd0bdf0ed0632a6455815675a59e0adaa7de817c70945063fab5ef7a9f23eaf2e
MAX SUP BEFORE:  1000000000000000043845843045076197354634047651840
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0x461ef71ae709dd701fba0f76ae63f9008c84b7d4924b54c09cebd09b399da850
MAX SUP BEFORE:  1000000000000000043845843045076197354634047651840
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0xcd36075ad42aa8de19ab2dc8eae10fe3a7ad3b230ea5c5959f31f76dd9f3838c
MAX SUP BEFORE:  100000000000000004384584304507619735463404765184
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0xd726e5256598eee9d5fd9b1ed2fd0d1ed5af595d00b44d1216b730add41c1ad8
MAX SUP BEFORE:  7777777777777777226371629387350016
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0x98607354170909a3f1de6df8f60575727517ccb07c63cc1a13564d24316de90e
MAX SUP BEFORE:  10000000000000000470601344959054695891559601407866630764278709534898249531392
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0x83df0a3f873bdf974f6f48c7f1f52a9313d55ccd72eb641ef8b02c4bcee6b184
MAX SUP BEFORE:  999999999999999983222784
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0x0cca0e3b2f0e8aea96de4358b9c56a3d20fdd16d3f48310fd69c92aeb11668bd
MAX SUP BEFORE:  500000000000000000000
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0x8a3ca55eddf88fb7d607cb8031ad129ff457bb5bc1c030247eab1199ef79f9c7
MAX SUP BEFORE:  339999999999999991611392
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0x5b3e6ed0294cb56124f2fa53c47e0093f49b18ce72e2275b293af88b5a0ccc93
MAX SUP BEFORE:  10000000000000000905969664
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0x7f5482ca165b839631b2e33802b5a559d9bb14d279482383939faff3851d9789
MAX SUP BEFORE:  99999999999999998278261272554585856747747644714015897553975120217811154108416
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0x47b152062eeaef4a2b94cdf58ffb75f0de45326bcef3e20ecee2a5ecc500beff
MAX SUP BEFORE:  1000000000000000000000
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0x47cda1ca50d29d7d938c52184f338057459a3e3b46db82e2c295f744c8b128b9
MAX SUP BEFORE:  10000000000000000139372116959414099130712064
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0x1b20369d6130dee4f259842cc485118994152ab78050870624860642dd3f50b6
MAX SUP BEFORE:  10000000000000000905969664
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0xb160e5fa119a0c9f2bb1f7e009e788811fb6d75cfbd33878eac16bef6637ca17
MAX SUP BEFORE:  10000000000000000905969664
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0x00f8b4fbc893a789502ea52e45c4822dea8fcb98cd33e92ced6f253c750f94ea
MAX SUP BEFORE:  1111111111111111179197135620610356299040699920330784768
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0x13a7192a28db91b0c3f3c7ab2e1c464cb3838107b73a86c51ec826e0bc697fb3
MAX SUP BEFORE:  999999999999999983222784
TOTAL SUP AFTER: 1000000000000000000

FOUNDRY COIN MANAGER ID: 0x41788a5126e02f6a6b3819a5136281ec45837d5faa97fa99795c208aa9b893c7
MAX SUP BEFORE:  210000000000000012582912
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0xdc829faf7cdc17d8ab9114d2435bdc1a51c49b3c7f56dd915e2c1eff8ee49116
MAX SUP BEFORE:  100000000000000000000
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0x49b1645a8743f96dd452969124e947e0efbfe20b79e51ff791c3f30ac6adb47e
MAX SUP BEFORE:  40000000000000000000
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0x7a9fc288677e2b532143999083b9fb9bdf92f589c2e6fbd796a05f0f19d94c25
MAX SUP BEFORE:  99999999999999998278261272554585856747747644714015897553975120217811154108416
TOTAL SUP AFTER: 1

FOUNDRY COIN MANAGER ID: 0x8960a4023e83e7f361a2e92a6214b2e8f88d2d92e7f9b40e4a899a0e14725859
MAX SUP BEFORE:  99999999999999991611392
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0x18fa6181383ff0f3a7949cb5ea55d121bf6721a4e6bd4e036a1e0461898173c1
MAX SUP BEFORE:  21000000000000000000
TOTAL SUP AFTER: 19166212000000000

FOUNDRY COIN MANAGER ID: 0x71d55ca30d7d63f5afcdf9e3b0cd6b1ef306f647a3306f27427126c09034a601
MAX SUP BEFORE:  21000000000000000000
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0x5e6e6d327d22911e811b4b6c553cc13c700775139db265e6c0e0d5ae59f91da5
MAX SUP BEFORE:  21000000000000000000
TOTAL SUP AFTER: 18446744073709551614

FOUNDRY COIN MANAGER ID: 0x56cb1673680e23702aaf1dad45da5a2cff9c7ff7f92d460611b97dc3897e3822
MAX SUP BEFORE:  99999999999999991611392
TOTAL SUP AFTER: 18446744073709551614

For clarifying:
In this case, we have 1 total supply because there was only 1 minted token.

iota/crates/iota-genesis-builder/src/stardust/types/token_scheme.rs

Line 57 in 134873d

let minted_tokens_u256 = token_scheme.minted_tokens();

FOUNDRY COIN MANAGER ID: 0x7a9fc288677e2b532143999083b9fb9bdf92f589c2e6fbd796a05f0f19d94c25
MAX SUP BEFORE:  99999999999999998278261272554585856747747644714015897553975120217811154108416
TOTAL SUP AFTER: 1

[miker83z]

The verification implemented in #2126 shows that in the 12th of Dec 2024 there were no native tokens affected by the issue indicated here (this comment explains why).

TODO:

• decide if it is needed to implement a way to avoid such rounding error anyway
• decide if it is needed to implement a fix to a related minor effect (native tokens with a supply amount that differs by 1 coin from the expected amount, 18446744073709551613 instead of 18446744073709551614)

cc @lzpap @kodemartin @thibault-martinez