revisions

docs/architecture/adr-002-photon-token.md

@@ -3,21 +3,23 @@
 ## Changelog
 
 - 15 October 2024: Initial version
+- 30 October 2024: Revisions
 
 ## Status
 
 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,28 +61,31 @@ 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.
 
 ```math
 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