add adr 009

docs/architecture/README.md

@@ -25,13 +25,14 @@ To suggest an ADR, please make use of the [ADR template](./adr-template.md) prov
 
 ## Table of Contents
 
-| ADR \#              | Description | Status   |
-|---------------------| ----------- |----------|
-| [001](./adr-001.md) | Disable Gravity Bridge at Genesis | Accepted |
-| [002](./adr-002.md) | Use a custom fork of ibc-go | Accepted |
-| [003](./adr-003.md) | Add Fee Market Module | Accepted |
-| [004](./adr-004.md) | Tokens conversion in Cronos | Accepted |
-| [005](./adr-005.md) | Cross-chain Validation for Gravity Bridge | Rejected |
-| [006](./adr-006.md) | Migrating CRC20 contract to CRC21 standard | Rejected |
-| [007](./adr-007.md) | Generic event format for evm-hook actions | Accepted |
+| ADR \#              | Description                                                                | Status   |
+|---------------------|----------------------------------------------------------------------------|----------|
+| [001](./adr-001.md) | Disable Gravity Bridge at Genesis                                          | Accepted |
+| [002](./adr-002.md) | Use a custom fork of ibc-go                                                | Accepted |
+| [003](./adr-003.md) | Add Fee Market Module                                                      | Accepted |
+| [004](./adr-004.md) | Tokens conversion in Cronos                                                | Accepted |
+| [005](./adr-005.md) | Cross-chain Validation for Gravity Bridge                                  | Rejected |
+| [006](./adr-006.md) | Migrating CRC20 contract to CRC21 standard                                 | Rejected |
+| [007](./adr-007.md) | Generic event format for evm-hook actions                                  | Accepted |
 | [008](./adr-008.md) | Denom and Contract Mapping Enhancement for Bi-Directional Token Conversion | Accepted |
+| [009](./adr-009.md) | Permissioned addresses in Cronos                                           | Proposed |

docs/architecture/adr-009.md

@@ -0,0 +1,62 @@
+# ADR 009: Permissioned addresses in Cronos
+
+## Changelog
+* 2022-01-04: first draft
+
+## Context
+
+Some messages in cronos require permissions. For example changing the mapping to support new CRC20 auto-conversion contracts or disabling the bridge module in case of emergency. Right now, only the admin has the ability to use those messages.
+The admin is a single address defined in cronos param's space and can be modified through governance. It is usually a multi-sig address shared by multiple trusted party in order to achieve a higher level of security.
+
+While a single multi-sig admin address was originally implemented with simplicity in mind, realistically it is not practical to rely on a single address to perform all admin tasks.
+As those operations could become more frequent (updating the token mapping) or needs to be trigger by external systems (circuit breaker for gravity module), it would be more practical to define a granular permission system which restrict certain operations to only "some" known addresses.
+
+
+## Terminologies
+
+### Admin
+
+A special address defined in cronos param's space that can be modified through governance. Usually a multi-sig address.
+
+### Permissioned addresses
+
+An address in Cronos that is allowed to perform a type of operation (message).
+
+### Non-permissioned addresses
+
+An address in Cronos that carry no permissions. 
+
+
+## Decision
+
+For the above problem, we propose the following:
+
+- Keep the admin address in Cronos param's space. The admin has all the permissions and has the ability to change the permission of an address. 
+
+- By default, all addresses in Cronos are non-permissioned
+
+- Assign to each "restricted" messages in Cronos a permission (integer value) and create in Cronos module a mapping between addresses and permissions that is stored in memory. For now, there are only two messages that require permission : MsgUpdateTokenMapping and MsgTurnBridge.
+
+- Create a msg type "MsgUpdatePermissions" that only admin can use and allow to update the address permission mapping.
+
+- Change the logic to always check for the permission before processing the restricted messages.
+
+## Status
+
+Proposed
+
+## Consequences
+
+### Positive
+
+- The admin address can share its power to other addresses. It becomes less vulnerable to exposure. 
+- Permissioned addresses can only carry few responsibilities. The damage is limited in case they are stolen. Could be used in a hot-wallet.
+- It is still decentralized as the admin key is still controlled through governance. 
+
+### Negative
+
+- Require some change in the code
+
+## References
+
+- https://github.com/crypto-org-chain/cronos/pull/795