diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index a8be53b75d..68dbc8e373 100755 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -259,6 +259,7 @@ module.exports = { collapsable: false, children: [ '/tutorials/ibc-transfers', + '/tutorials/currency-allowlist-proposal', ], }, { diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md index 0f4125a86c..58b397ad53 100644 --- a/docs/tutorials/README.md +++ b/docs/tutorials/README.md @@ -5,6 +5,7 @@ Tutorials for interacting and building with Regen Ledger. ## User Tutorials - [IBC Transfers](./ibc-transfers.md) +- [Currency Allowlist Proposal](./currency-allowlist-proposal.md) ## Developer Tutorials diff --git a/docs/tutorials/currency-allowlist-proposal.md b/docs/tutorials/currency-allowlist-proposal.md new file mode 100644 index 0000000000..e236918de7 --- /dev/null +++ b/docs/tutorials/currency-allowlist-proposal.md @@ -0,0 +1,57 @@ +# Currency Allowlist Proposal + +Allowed currencies are currencies (or "denoms") that can be used for the asking price by owners of ecosystem service credits when listing credits for sale in the marketplace. + +Community members or representatives of projects/protocols are encouraged to submit proposals to add allowed currencies. See [Governance Guidelines](https://github.com/regen-network/governance#guidelines) for additional information about submitting proposals and to ensure the recommended steps are taken for a successful proposal. + +This document provides instructions for submitting a currency allowlist proposal using the [command-line interface (CLI)](../ledger/infrastructure/interfaces.md#command-line-interface). For instructions on how to install the `regen` binary, see [Install Regen](../ledger/get-started/README.md). + +## Create Proposal + +The first step is to create a json file that includes information about the proposal and the currency that will be added to the list of allowed currencies if the proposal passes. + +Create a `proposal.json` file using the following example (note that the name and location of the file is not significant as long as you use the same name and location when submitting the proposal): + +```json +{ + "title": "Add $REGEN to the currency allowlist", + "description": "This proposal adds $REGEN to the currency allowlist", + "denom": { + "bank_denom": "uregen", + "display_denom": "regen", + "exponent": 6 + } +} +``` + +Each field in the json file is required and should be properly filled out. + +Make sure you give the proposal a meaningful title and description. The description should provide a rationale as to why this currency should be added to the list and can be written in either plain text or markdown (see [Proposal #15](https://wallet.keplr.app/chains/regen/proposals/15) for a example of a detailed description). + +`denom` includes information about the currency you are proposing to add: + +- `bank_denom` is the denom that will be added to the list. In the example above, `uregen` (i.e. "micro regen") is being added. For any denom that is not native to the network, the IBC denom is required (e.g. `ibc/CDC4587874B85BEA4FCEC3CEA5A1195139799A1FEE711A07D972537E18FD`). + +- `display_denom` is the display name of the denom (e.g. `regen` or `atom`). The display denom is what users will see when interacting with the proposed currency in the marketplace. + +- `exponent` is used to relate the `bank_denom` to the `display_denom` and is informational. For example, `1000000uregen` is equal to `1regen` and therefore the exponent is `6`. + +Keep in mind that non-native tokens represented by an IBC denom only enables a currency from a specific source. For example, `atom` transferred from one chain is different from `atom` transferred from another chain, i.e. each of these represent `atom` but they have different IBC denoms. + +## Submit Proposal + +Once the json file has been created, you can use the following command to submit the proposal: + +```bash +regen tx gov submit-proposal allow-denom-proposal proposal.json --deposit=200000000uregen --from --fees +``` + +- `proposal.json` refers to the json file from the previous step, which can be deleted once the proposal has been submitted. + +Additional flags may be required depending on your configuration. For example, you may need to add a `--node`, `--chain-id`, and `--keyring-backend` if these options are not preconfigured. + +You can also submit the proposal without a deposit (i.e. without `--deposit`) or with an amount that is less than the full deposit and that can then be filled by another account or with another transaction. The voting period will only start once the full deposit has been received. + +## Additional Resources + +- [Understanding IBC Denoms](https://tutorials.cosmos.network/tutorials/understanding-ibc-denoms/)