From cccabf11424992816404dc46e2f3d203479970e4 Mon Sep 17 00:00:00 2001 From: Giuseppe Natale <12249307+giunatale@users.noreply.github.com> Date: Wed, 30 Oct 2024 15:51:58 +0100 Subject: [PATCH] revisions --- docs/architecture/adr-002-photon-token.md | 101 ++++++++++++---------- 1 file changed, 54 insertions(+), 47 deletions(-) diff --git a/docs/architecture/adr-002-photon-token.md b/docs/architecture/adr-002-photon-token.md index 4a414e87..3285f387 100644 --- a/docs/architecture/adr-002-photon-token.md +++ b/docs/architecture/adr-002-photon-token.md @@ -3,6 +3,7 @@ ## Changelog - 15 October 2024: Initial version +- 30 October 2024: Revisions ## Status @@ -10,14 +11,15 @@ DRAFT ## Abstract -This ADR proposes to introduce the PHOTON token as the only fee token of -AtomOne. The only way to get PHOTONs is to burn ATONEs. +This ADR proposes the introduction of the PHOTON token as the only fee token of +AtomOne. The only way to get PHOTONs is to burn ATONEs, with a one-way burn +that is not reversible at protocol level. The PHOTON denom is `photon`, while the base denom is `uphoton`, with: ``` 1 photon = 1,000,000 uphoton ``` -The following formulas in this document will use the `photon` denom for +Any subsequent formula in this document will use the `photon` denom for brevity. ## Context @@ -38,7 +40,7 @@ The PHOTON token is specified in the [AtomOne Constitution Article 3 Section 5]: ## Decision -The ADR proposes to create a new `photon` module to host the following +The ADR proposes to create a new `x/photon` module to host the following features: - New `ConversionRate` query - New `MsgMintPhoton` message @@ -59,18 +61,16 @@ where photon_{max\_supply} = 1,000,000,000 ``` -Given this formula and the initial supply of 107,775,332 ATONEs, the -`conversion_rate` will start as a number greater than 1, until it becomes -becomes a negligible number as the PHOTON supply approaches the maximum supply. - -The pivot point at which the `conversion_rate` becomes less than 1 depends on -the ATONEs supply, which evolves over time given the inflation. +The `conversion_rate` will therefore be a function of the ATONE supply and the +current PHOTON supply. The `conversion_rate` is expected to naturally decrease +over time as the ATONE supply increases by means of inflation. ### `MsgMintPhoton` message -`MsgMintPhoton` takes an amount of ATONEs and returns an amount of PHOTONs. -The amount of ATONEs is burnt while the amount of PHOTONs is minted and moved -onto the message signer account. The number of minted PHOTONs is equal to the +`MsgMintPhoton` takes an amount of ATONEs and returns a corresponding amount +of PHOTONs. The amount of ATONEs is burnt while the corresponding amount of +PHOTONs is minted and sent to the message signer account (who is also the sender +of the ATONEs that are burnt). The number of minted PHOTONs is equal to the number of burnt ATONEs multiplied by the conversion rate described in the `ConversionRate` query section below. @@ -78,9 +78,14 @@ number of burnt ATONEs multiplied by the conversion rate described in the photons_{minted} = atones_{burned} \times conversion\_rate ``` -However, if `conversion_rate` is 0, i.e. the maximum supply of PHOTON has been -reached, `MsgMintPhoton` should fail to avoid burning ATONEs without PHOTONs in -return. +The supply of PHOTON, although capped at 1B, will never reach this cap because +the situation in which this happens is if all ATONEs in circulation are burnt. +This is not possible if there are ATONEs staked, which is a requirement to be +able to produce blocks. This also means in practice that this message is +expected to never be able to fail because of insufficient mintable PHOTONs. + +The total PHOTON supply will be a constant hard-coded within the `x/photon` +module. ### `TxFeeChecker` implementation @@ -91,36 +96,31 @@ The [`TxFeeChecker`] is a function definition that is part of the ante handler Currently, AtomOne uses the default `TxFeeChecker` (namely [`checkTxFeeWithValidatorMinGasPrices`]), so the photon module must provide an alternative `TxFeeChecker` implementation, which should: + - enforce that the fee denom is PHOTON, and return a specific error message if it does not (this to be explicitely separated with the insufficient fee error message) - make exception for some messages, specifically like `MsgMintPhoton`, because `MsgMintPhoton` is the only way to get PHOTONs, so it should accept ATONEs as fee - token. + token. Possibly, the list of exception could be a module parameter. ### Params The `photon` module has the following params: -- `mint_disabled` (default to false): if true, disable the ability to call - `MsgMintPhoton`. - -> [!NOTE] -> XXX is it really usefull to disable `MsgMintPhoton` ? Looks like it is an urgency -> method when something goes wrong, which is not very compatible with a -> governance proposal to change the parameters... Suggestion: remove it -> [!NOTE] -> Because the maximum supply of PHOTON is constitutionnal, it must be hosted in -> a constant in the code, and not in the parameters. (XXX true or not?) +- `mint_disabled` (default to `false`): if `true`, disable the ability to call + `MsgMintPhoton`. +- `txfee_exceptions` (default to `["MsgMintPhoton"]`): list of messages that + are allowed to have ATONE as fee token as well as PHOTON. ### State -Aside from its params, the `photon` module does not have any additionnal state, -as the PHOTON balances and supply are handled by the `bank` module. +Aside from its params, the `x/photon` module does not have any additionnal state, +as the PHOTON balances and supply are handled by the `x/bank` module. ### Migration -The PHOTON denom metadata has to be added to the `bank` module state (XXX while +The PHOTON denom metadata has to be added to the `x/bank` module state (XXX while admittedly this record does not look very usefull, it is only used in queries...) @@ -160,14 +160,14 @@ queries...) ``` In contrast, it is not required to provide an initial supply for PHOTON (still -in the `bank` module), because the initial supply will be 0. +in the `x/bank` module), because the initial supply will be 0. ## Consequences ### Validator `minimum-gas-prices` Validators will have to update their `minimum-gas-prices` setting to reflect -this new setup. It should basically allow both ATONE and PHOTON, so the setting +this new setup. It should basically allow both `uatone` or `uphoton`, so the setting should look like: ```toml @@ -177,19 +177,30 @@ minimum-gas-prices = "0.001uatone,0.001uphoton" > [!IMPORTANT] > In the legacy `TxFeeChecker` implementation > ([`checkTxFeeWithValidatorMinGasPrices`]), the validator `minimum-gas-prices` -> is checked against *all* mentionned denoms. For the photon module, the +> is checked against *all* mentionned denoms. For the `x/photon` module, the > implementation must be different, it must be checked on at least one of the -> denoms (ATONE or PHOTON, but not both). +> denoms (`uatone` or `uphoton`, but not both). + +If the validator `minimum-gas-prices` does not match the required denom (`uatone` +or `uphoton` for `MsgMintPhoton` or any message in `txfee_exceptions`, and only +`uphoton` for all other messages), an error is returned and the tx is rejected. + +### ICS payments and core shard fees enforcement + +The proposed x/photon module does not enforce the usage of PHOTON as payment +token for ICS. This enforcement is left to be done by the ICS implementation. -If the validator `minimum-gas-prices` does not match the required denom (ATONE -or PHOTON for `MsgMintPhoton, only `PHOTON` for all other messages), an error -is returned and the tx is rejected. +Seemingly, for future core shards the enforcement of PHOTON as the fee token +will have to be done at the shard level. A simple way to do this would be to +use the same `TxFeeChecker` implementation as the root shard (i.e. the one +provided by the `x/photon` module). ### Positive -- Create a clear distinction between money (PHOTON) and security (ATONE). ATONE - is not money and should only be thought of as a security token. PHOTON as the - only fee token reinforces this property. +- Create a clear distinction between fee token (PHOTON) and staking token + (ATONE). ATONE is meant to be a pure staking token and allow to freely + inflate between the 7% and 20% bounds,targeting the 2/3 bonding ratio. + PHOTON as the fee token reinforces this property. - Having a non-inflationnary fee token (in contrast to ATONE) ensures PHOTON will not be subject to the same dilution tax for non-stakers as ATONE does. @@ -198,13 +209,9 @@ is returned and the tx is rejected. ### Negative -- Users will have to choose between PHOTON and ATONE for the fee token when - signing a transaction for AtomOne. Basically, for `MsgMintPhoton` ATONE and - PHOTON are accepted, for all other messages, only PHOTON is accepted. While - this may seem obvious, it can be confusing because as far as we know, wallets - do not have message-based logic regarding the choice of the fee token. Maybe - it is time to start discussion with some wallets dev regarding that, this - would improve the UX. +- Enforcing PHOTON as the only fee token might be seen as a limitation for + users who would like to pay fees in other tokens. This is a trade-off to + ensure the stability of the fee token. ### Neutral