feat(iota-genesis-builder): Add native token circulating supply validation

[miker83z]

Description of change

Based on #440 discussion, some native token supplies in the final ledger state were expected to be broken due to the adaptation of a native token supply value from u256 to u64. This because the total supply of a token could be easily calculated (minted - melted tokens) and set in the dedicated Supply object of a Coin. But, instead, each native token coin instance balance is set in a context where the real circulating supply cannot be known a priori and thus can be incorrect (where incorrect means that due to the big difference between u256 and u64 and rounding, some balances could not represent the original coin-instance-balance/total-supply ratio equivalently after the adaptation).

The analysis in #440 comments shows that all Foundries using a supply greater than u64::MAX were correctly adapted when converted into Coins. This PR provides a way to compute the real circulating supply of all created tokens. It provides a warning during the validation of the created object snapshot, indicating the Coins that have a mismatch between real circulating supply and the expected one.

The output is shown below in a PR comment.

The results show that adapted Foundries (from u256 to u64 supply) only differ by an amount of 1 coin (18446744073709551613 instead of 18446744073709551614, which is the expected supply obtained by u64::MAX - 1).

There are other native tokens that have a mismatch but were not part of the adaptation process. In this case, I assume that something was done already in Stardust (e.g. burn some tokens without affecting the melting in the Foundry?). E.g., in IOTA 0xabfe2fe5e9f5af219f775abafe2a527a18e50a818c5e0c2af60a747f7a3a8843::spig::SPIG: found 200000000, expected 1000000000 we can se that the address who created this (test?) token owns only an output with an amount of 200000000 SPIG (how can we check if the other 800000000 are still around somewhat?).

Links to any relevant issues

Closes #5001.

Type of change

• Enhancement (a non-breaking change which adds functionality)

How the change has been tested

• cargo run --release --bin iota-genesis-builder -- --disable-global-snapshot-verification iota --snapshot-path ../latest-full_snapshot-iota.bin --target-network alphanetv0.1.1
• equivalent for shimmer

Change checklist

• I have followed the contribution guidelines for this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• I have added tests that prove my fix is effective or that my feature works
• I have checked that new and existing unit tests pass locally with my changes

[miker83z]

Mismatching native tokens in IOTA (from a quite old hornet snapshot)

• 0x9aaf99bbc2a0d525195ba1513d8f8ecd1cedcf7b42970a92723b6e682055e0a5::house::HOUSE: found 999999700000000, expected 1000000000000000
• 0x64518b4b143482378d2fde5cc7f701e56b69e0485505e8ce7ddf3c588fb7e12d::sdv::SDV: found 0, expected 100000
• 0x8bac809ee0486800e8e1c2a9877de7a61155ece75f3a66508b0b5e62ce345ee2::iq::IQ: found 0, expected 690000000000000
• 0x1c5d6f865fa05f326719e98ab8334f1180f6ac3d735bfab1cbaf787d0ae29e24::tud::TUD: found 90, expected 1234
• 0x7fa56ebac7a402ac36acd6a532a1713a8807dcf5179c1e8585a1eee4f64b1389::iq::IQ: found 18446744073709551613, expected 18446744073709551614
• 0x19219831ab170fe793c71ab6b1e3f69321d402af8215dbbdd0f00bcb51e72625::tst::TST: found 80, expected 100
• 0xabfe2fe5e9f5af219f775abafe2a527a18e50a818c5e0c2af60a747f7a3a8843::spig::SPIG: found 200000000, expected 1000000000
• 0xe0e68721658819a29af8ccee1e0eb8d9881eebd969a60ee868f47ee0ec28c673::nxs::NXS: found 0, expected 1000000
• 0x577beb01bb2111ce48fed65dceedce61506f218598b6f95e5bf78be8423f3dc3::emosi::EMOSI: found 18446744073709551613, expected 18446744073709551614
• 0x7c712f0a1bde3dd5fde1ff0e2b270cd3b1954a670be8e5c8eedec789b27992ac::btc::BTC: found 0, expected 21000000
• 0x4ae3732bf38dc53eaa978f40732ae531d9354361c5c4055f772133e945d015f7::btc::BTC: found 0, expected 21000000
• 0x43f0063653317bddbcdb105f5530ee546dcba8762e4b030c9b1bf024351db2cc::ape::APE: found 99999934000000, expected 100000000000000

[miker83z]

Latest mismatching IOTA native tokens:

2024-12-12T09:22:04.194579Z  WARN iota_genesis_builder::stardust::migration::verification: total supply mismatch for ad2b7d988ee6fa4fb484eb9f3187ba57b1c6fbf4f4583fb2137f220288e09587::iq::IQ: found 18446744073709551613, expected 18446744073709551614
2024-12-12T09:22:04.194603Z  WARN iota_genesis_builder::stardust::migration::verification: total supply mismatch for b497233c789ef21f749e4d13037732cac29412cc301909d4e91f4f842b65c3b1::test::TEST: found 0, expected 300000
2024-12-12T09:22:04.194609Z  WARN iota_genesis_builder::stardust::migration::verification: total supply mismatch for ca7f0ed4072278a0756d7c15a62bf018c116d5cbf9213537eab9103e88ecba92::zipp::ZIPP: found 0, expected 100000
2024-12-12T09:22:04.194621Z  WARN iota_genesis_builder::stardust::migration::verification: total supply mismatch for 2ac523127c5941427ae9d80771c72c9a558650cb7dc74089d3a8dced994faa4c::ger::GER: found 0, expected 84669326
2024-12-12T09:22:04.194662Z  WARN iota_genesis_builder::stardust::migration::verification: total supply mismatch for 5472388003ad1ef88132cd71177f0d6827bf2d155ddeefffa84e5a831826ec54::t2::T2: found 0, expected 300000
2024-12-12T09:22:04.194668Z  WARN iota_genesis_builder::stardust::migration::verification: total supply mismatch for 98c81948c5549f6dade5ac9a1e91798e1dc6292ca9fba5d547f38d44883359a4::btc::BTC: found 0, expected 21000000
2024-12-12T09:22:04.194672Z  WARN iota_genesis_builder::stardust::migration::verification: total supply mismatch for 25895b3847fa639eb7db8e4792bbf959c9d7db18e382bc45ed8f561eb026918b::t3::T3: found 0, expected 30000000000000
2024-12-12T09:22:04.194677Z  WARN iota_genesis_builder::stardust::migration::verification: total supply mismatch for 3fc080b06b22bfbc10fed2f575e34a2cd9d50d345c8c8ea5fa69476277ca54d9::spig::SPIG: found 200000000, expected 1000000000
2024-12-12T09:22:04.194827Z  WARN iota_genesis_builder::stardust::migration::verification: total supply mismatch for 585552d14681e391f4922725a960fd07dd1dc5c883455d2b2f529b6d9fff6165::t::T: found 0, expected 300000
2024-12-12T09:22:04.194833Z  WARN iota_genesis_builder::stardust::migration::verification: total supply mismatch for 277579fea3eb8e6d24d8e582f9f0dfe8ae29e361d9455fece4eb60c3b7fa11de::tud::TUD: found 90, expected 1234
2024-12-12T09:22:04.194838Z  WARN iota_genesis_builder::stardust::migration::verification: total supply mismatch for 6bcda5c62e54831a9a5e173289634f6ece910bc2c8123273f3596e9f0bfefde6::emosi::EMOSI: found 18446744073709551613, expected 18446744073709551614
2024-12-12T09:22:04.194842Z  WARN iota_genesis_builder::stardust::migration::verification: total supply mismatch for ac9984d216a65ff610728e704c2e9f033c32c4632663832f5c03d820237b422b::ape::APE: found 99999869000000, expected 100000000000000
2024-12-12T09:22:04.194867Z  WARN iota_genesis_builder::stardust::migration::verification: total supply mismatch for 3f9789518737453aa7cabbf0e47908c15a22388a062dc6719d14cd1d47aaa21f::btc::BTC: found 0, expected 21000000
2024-12-12T09:22:04.194876Z  WARN iota_genesis_builder::stardust::migration::verification: total supply mismatch for dadb5e7b851b5ea23df0b654b9a93ea90f188c29ffac383a9180bbca47f74626::iq::IQ: found 0, expected 690000000000000
2024-12-12T09:22:04.194881Z  WARN iota_genesis_builder::stardust::migration::verification: total supply mismatch for 595a54b83ae4d8315ca1f65a31d164e8e987866811d50d0a9b0aa4dc4a8be730::ptt::PTT: found 0, expected 1000000
2024-12-12T09:22:04.194885Z  WARN iota_genesis_builder::stardust::migration::verification: total supply mismatch for 85900a49fa048b3999cab339ac3ab1c2efd4f466d0d648ae6a8404b5ed3da37f::t::T: found 0, expected 300000
2024-12-12T09:22:04.194895Z  WARN iota_genesis_builder::stardust::migration::verification: total supply mismatch for d0c7f2ccc139601b5dfe3116aacddc6060ce5d4b9e7323564b9129e3ea6543fe::tst::TST: found 80, expected 100
2024-12-12T09:22:04.194900Z  WARN iota_genesis_builder::stardust::migration::verification: total supply mismatch for 91da819f112e6d7fd04cfe3380200c4a2c688b90bfdc07586085a13c230e8d65::sdv::SDV: found 0, expected 100000
2024-12-12T09:22:04.194906Z  WARN iota_genesis_builder::stardust::migration::verification: total supply mismatch for aeec58c69379ee984a761bfe82b64c0954678892677dbec43422368506b7ff60::t::T: found 0, expected 300000
2024-12-12T09:22:04.194911Z  WARN iota_genesis_builder::stardust::migration::verification: total supply mismatch for 7f09b0a2a6d9ded0d5929d4c056629c91a9a440084db040a437055a49b6cbab0::nxs::NXS: found 0, expected 1000000
2024-12-12T09:22:04.194916Z  WARN iota_genesis_builder::stardust::migration::verification: total supply mismatch for 307de3d3bb3cb80aeda29f64e111b3d8d1c074adf73bf14833763aec498bb849: found 999999700000000, expected 1000000000000000
2024-12-12T09:22:04.194920Z  WARN iota_genesis_builder::stardust::migration::verification: total supply mismatch for 12e4a562e0ff004362bc3cc0812355196370048bc58a1de83890953f9fc62d96::mrns::MRNS: found 999, expected 1000
2024-12-12T09:22:04.194967Z  WARN iota_genesis_builder::stardust::migration::verification: total supply mismatch for 9bea8a260ac3c4dfeca0923384ace37c6f1eb6bf9292a676e8908594ec872c0e::t::T: found 0, expected 300000

[kodemartin]

@miker83z I don't quite see how this patch handles #440. With this comment you report the same inconsistencies reported by #440, i.e. 0 total supply for multiple native tokens.

[miker83z]

@miker83z I don't quite see how this patch handles #440. With this comment you report the same inconsistencies reported by #440, i.e. 0 total supply for multiple native tokens.

@kodemartin this PR aims to not modify the migration logic, but just enhance the information that we can extract during the process -> it provides us with real circulating supply of all created tokens.
Given that in this comment the results show that adapted Foundries, potentially suffering from the issue indicated in #440 (i.e., going from u256 to u64 supply), only differ by an amount of 1 coin (18446744073709551613 instead of 18446744073709551614), we might argue that a fix to #440 might not be needed. And with fix here I mean actually modifying the migration logic. (We could decide to open a new issue to make this 1 coin difference be filled, though).

Pls, bear in mind that the native tokens potentially suffering from the issue indicated in #440 are only:

• ad2b7d988ee6fa4fb484eb9f3187ba57b1c6fbf4f4583fb2137f220288e09587::iq::IQ
• 6bcda5c62e54831a9a5e173289634f6ece910bc2c8123273f3596e9f0bfefde6::emosi::EMOSI
  because their total supply was scaled to u64::MAX.
  All the rest of tokens that you find in the comment have a total supply < u64::MAX, then these do not fall into the category of tokens of [migration] Resolve possible inconsistencies when scaling large native token supplies #440. In fact, in these cases, you find the real circulating supply equal to 0 not because of rounding but because (it seems that) the owners of those tokens burned them in the current Stardust mainnet ledger without using the appropriate Stardust burn logic (I checked manually a couple of occurrences in the mainnet explorer).