[feature]: Clarify, document, or remove "decimal_display" from mint api

[MegalithicBTC]

One of the most confusing and dangerous aspects of the Lightning Network, from the perspective of new developers, is the seemingly random usage of "sats" vs "millisats" in various APIs -- for example, in many cases, simple CLI commands in CLN will require "millisat" inputs, while in LND, usually "sats" are used. Similarly, developers often have to puzzle through API outputs from both implementations, and try to remember which outputs are denominated in "sats" and which in "millisats". This confusion has, without a doubt, led to loss of funds, as developers can easily specify "sats" when they intended to specify "millisats", and vice-versa. Taproot assets, as of the most recent release, now adds another quite terrifying layer of complication: the `decimal_display` parameter. It's defined on this page https://docs.lightning.engineering/lightning-network-tools/taproot-assets/first-steps as: ``` Decimal display The number of decimal places your asset will have. Two decimal places would allow only for cents, while six decimal places would allow for micro-units. Too few decimal places can result in rounding errors when transferring assets over the Lightning Network. You can choose up to 12 decimal places. If you want to mint 1 million units of an asset, each divisible into one thousand pieces, you will have to choose a total supply of 1,000,000,000. ``` I believe that very few developers will understand this or be able to choose the "right" `decimal_display` for assets. At a basic level, it's hard to understand how this "decimal" concept relates to assets moving around on the lighting network, as as lighting network assets are always denominated as integers. For example, both for "sat amounts" and "asset amounts", the output of `lncli listchannels` shows balances like this: ``` "capacity": 5000, "local_balance": 4850, "remote_balance": 150 ``` These are integers. There are no decimals. Clearly the term `decimal_display` is somehow related to the concept of "displaying" these assets, but I can't figure out where this display would happen, or what it means. Is this related to, like, on an app or or a website, how many decimal places should appear after an integer number? I DO understand that there can be issues with rounding errors, but if that is the case, would it be possible to at least fall back to the `millisats` vs `sats` concept, something developers already have to deal with, instead of introducing a new abstraction like this? At the end of the day, we can't deal with anything smaller than `1 millisat`, so why not use the `millisat` concept in developer-facing APIs?

[MegalithicBTC]

If there's no way around this, and we really must provide a decimal_display value, then an extensive set of examples, showing real-world scenarios and recommended decimal_display values, and the reasoning behind these choices, like "I want to mint a stablecoin worth $1, and therefore I chose a decimal_display of _ " or "I want to mint a stablecoin worth $0.01, and therefore I chose a decimal_display of _" or "I want to mint 1,000,000 assets, and I don't know what the market price will be so, I chose a decimal_display of ___" .... would be very useful.... and part of this should also be some understandable explanation of the tradeoffs involved in different denominations -- i.e. explain why it might be better to mint a "millicent" or "microcent" asset in the case of a stablecoin, instead of attempting to create a stablecoin where "1 asset = $1".

[guggero]

This might be of interest to you: https://github.com/lightninglabs/taproot-assets/pull/1059

That document also explains the reason for the decimal display and what effect it has on Lightning Multi-Part Payments (MPP).

[MegalithicBTC]

Closed in favor of this: https://github.com/lightninglabs/taproot-assets/pull/1059