docs: ADR-002 The Photon Token

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

@@ -0,0 +1,228 @@
+# ADR 002: The Photon token
+
+## Changelog
+
+- 15 October 2024: Initial version
+- 30 October 2024: Revisions
+
+## Status
+
+DRAFT
+
+## Abstract
+
+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
+```
+Any subsequent formula in this document will use the `photon` denom for
+brevity.
+
+## Context
+
+The PHOTON token is specified in the [AtomOne Constitution Article 3 Section 5]:
+
+> ### Section 5: The PHOTON Token
+>
+> The PHOTON shall be the only fee token except for ATONE to PHOTON burn
+> transactions. This applies for all transactions on the root and core shards,
+> and all IBC and ICS payments.
+>
+> ATONE tokens may be burned to PHOTON tokens at a conversion rate set by law
+> such that the total amount of PHOTONs mintable through burning ATONE tokens
+> shall be capped at 1B PHOTON tokens.
+>
+> PHOTONs cannot be converted back into ATONE tokens.
+
+## Decision
+
+The ADR proposes to create a new `x/photon` module to host the following
+features:
+- New `ConversionRate` query
+- New `MsgMintPhoton` message
+- New [`TxFeeChecker`] implementation to enforce the PHOTON token as the only
+  fee token.
+
+### `ConversionRate` query
+
+The `ConversionRate` query returns a `sdk.Dec` which represents the current
+conversion rate of ATONE to PHOTON. This conversion rate is computed as the
+following:
+
+```math
+conversion\_rate = \dfrac{photon_{max\_supply} - photon_{supply}}{atone_{supply}}
+```
+where
+```math
+photon_{max\_supply} = 1,000,000,000
+```
+
+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 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
+```
+
+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
+
+The [`TxFeeChecker`] is a function definition that is part of the ante handler
+`auth/ante.DeductFeeDecorator`. When this ante handler is invoked, it calls the
+`TxFeeChecker` to ensure that the fee specified in the tx is sufficient.
+
+Currently, AtomOne uses the default `TxFeeChecker` (namely
+[`checkTxFeeWithValidatorMinGasPrices`]), so the `x/photon` module must provide an
+alternative `TxFeeChecker` implementation, which should:
+
+- enforce that the fee denom is `uphoton`, 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. The list of exceptions will in fact 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`.
+- `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 `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 `x/bank` module state (XXX while
+admittedly this record does not look very usefull, it is only used in
+queries...)
+
+```json
+{
+  "description": "The fee token of AtomOne Hub",
+  "denom_units": [
+    {
+      "denom": "uphoton",
+      "exponent": 0,
+      "aliases": [
+        "microphoton"
+      ]
+    },
+    {
+      "denom": "mphoton",
+      "exponent": 3,
+      "aliases": [
+        "milliphoton"
+      ]
+    },
+    {
+      "denom": "photon",
+      "exponent": 6,
+      "aliases": [
+        "photon"
+      ]
+    }
+  ],
+  "base": "uphoton",
+  "display": "photon",
+  "name": "AtomOne Photon",
+  "symbol": "PHOTON",
+  "uri": "",
+  "uri_hash": ""
+}
+```
+
+In contrast, it is not required to provide an initial supply for PHOTON (still
+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 `uatone` or `uphoton`, so the setting
+should look like:
+
+```toml
+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 `x/photon` module, the
+> implementation must be different, it must be checked on at least one of the
+> 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.
+
+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 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.
+  PHOTON holders will be subject to no dilution at all. The more stable nature
+  of PHOTON  makes it a perfect candidate for a fee token.
+
+### Negative
+
+- 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
+
+- Dual token model like this has not been experimented at this scale in the
+  Cosmos ecosytem, we might experience some unexpected side effect, positive or
+  negative.
+
+## References
+
+* [AtomOne Constitution Article 3 Section 5]: The PHOTON Token
+
+[AtomOne Constitution Article 3 Section 5]: https://github.com/atomone-hub/genesis/blob/b84df30364674c3f68b4bc0a43d7ed977ae22226/CONSTITUTION.md#section-5-the-photon-token
+[`TxFeeChecker`]: https://github.com/cosmos/cosmos-sdk/blob/44c5d17ca6d9d37fdd6adfa3169c986fbce22b8f/x/auth/ante/fee.go#L11-L13
+[`checkTxFeeWithValidatorMinGasPrices`]: https://github.com/cosmos/cosmos-sdk/blob/6e59ad0deea672a21e64fdc83939ca812dcd2b1b/x/auth/ante/validator_tx_fee.go#L17

docs/architecture/adr-template.md

@@ -1,58 +1,58 @@
-<!--
-order: false
--->
-
-# ADR {ADR-NUMBER}: {TITLE}
-
-## Changelog
-
-- {date}: {changelog}
-
-## Status
-
-{DRAFT | PROPOSED} Not Implemented
-
-> Please have a look at the [PROCESS](./PROCESS.md#adr-status) page.
-> Use DRAFT if the ADR is in a draft stage (draft PR) or PROPOSED if it's in review.
-
-## Abstract
-
-> "If you can't explain it simply, you don't understand it well enough." Provide
-> a simplified and layman-accessible explanation of the ADR.
-> A short (~200 word) description of the issue being addressed.
-
-## Context
-
-> This section contains all the context one needs to understand the current state, and why there is a problem. 
-> It should be as succinct as possible and introduce the high level idea behind the solution. 
-> The language in this section is value-neutral. It is simply describing facts.
-
-## Decision
-
-> This section explains all of the details of the proposed solution, including implementation details.
-It should also describe affects / corollary items that may need to be changed as a part of this.
-If the proposed change will be large, please also indicate a way to do the change to maximize ease of review.
-(e.g. the optimal split of things to do between separate PR's)
-
-## Consequences
-
-> This section describes the consequences, after applying the decision. 
-> All consequences should be summarized here, not just the "positive" ones.
-
-### Positive
-
-> {positive consequences}
-
-### Negative
-
-> {negative consequences}
-
-### Neutral
-
-> {neutral consequences}
-
-## References
-
-> Are there any relevant PR comments, issues that led up to this, or articles referrenced for why we made the given design choice? If so link them here!
-
-* {reference link}
+<!--
+order: false
+-->
+
+# ADR {ADR-NUMBER}: {TITLE}
+
+## Changelog
+
+- {date}: {changelog}
+
+## Status
+
+{DRAFT | PROPOSED} Not Implemented
+
+> Please have a look at the [PROCESS](./PROCESS.md#adr-status) page.
+> Use DRAFT if the ADR is in a draft stage (draft PR) or PROPOSED if it's in review.
+
+## Abstract
+
+> "If you can't explain it simply, you don't understand it well enough." Provide
+> a simplified and layman-accessible explanation of the ADR.
+> A short (~200 word) description of the issue being addressed.
+
+## Context
+
+> This section contains all the context one needs to understand the current state, and why there is a problem. 
+> It should be as succinct as possible and introduce the high level idea behind the solution. 
+> The language in this section is value-neutral. It is simply describing facts.
+
+## Decision
+
+> This section explains all of the details of the proposed solution, including implementation details.
+It should also describe affects / corollary items that may need to be changed as a part of this.
+If the proposed change will be large, please also indicate a way to do the change to maximize ease of review.
+(e.g. the optimal split of things to do between separate PR's)
+
+## Consequences
+
+> This section describes the consequences, after applying the decision. 
+> All consequences should be summarized here, not just the "positive" ones.
+
+### Positive
+
+> {positive consequences}
+
+### Negative
+
+> {negative consequences}
+
+### Neutral
+
+> {neutral consequences}
+
+## References
+
+> Are there any relevant PR comments, issues that led up to this, or articles referrenced for why we made the given design choice? If so link them here!
+
+* {reference link}