From 990fae35285a99dbbe719ac40c96dbd0fcc401cc Mon Sep 17 00:00:00 2001 From: marbar3778 Date: Mon, 3 Jun 2024 11:55:55 +0200 Subject: [PATCH] add docs on sudo permissions --- docs/build/building-modules/00-intro.md | 9 +++++++++ x/bank/README.md | 5 +++++ 2 files changed, 14 insertions(+) diff --git a/docs/build/building-modules/00-intro.md b/docs/build/building-modules/00-intro.md index b055dfd1e42c..4eda49125a7b 100644 --- a/docs/build/building-modules/00-intro.md +++ b/docs/build/building-modules/00-intro.md @@ -42,6 +42,15 @@ flowchart TD As a result of this architecture, building a Cosmos SDK application usually revolves around writing modules to implement the specialized logic of the application and composing them with existing modules to complete the application. Developers will generally work on modules that implement logic needed for their specific use case that do not exist yet, and will use existing modules for more generic functionalities like staking, accounts, or token management. + +### Modules as Sudo + +Modules have the ability to perform actions that are not available to regular users. This is because modules are given sudo permissions by the state machine. Modules can reject another modules desire to execute a function but this logic must be explicit. Examples of this can be seen when modules create functions to modify parameters: + +```go reference +https://github.com/cosmos/cosmos-sdk/blob/61da5d1c29c16a1eb5bb5488719fde604ec07b10/x/bank/keeper/msg_server.go#L147-L149 +``` + ## How to Approach Building Modules as a Developer While there are no definitive guidelines for writing modules, here are some important design principles developers should keep in mind when building them: diff --git a/x/bank/README.md b/x/bank/README.md index 5a660c019d2f..8bd981a9a7f2 100644 --- a/x/bank/README.md +++ b/x/bank/README.md @@ -280,6 +280,11 @@ During `InputOutputCoins`, the send restriction is applied after the input coins A send restriction function should make use of a custom value in the context to allow bypassing that specific restriction. +Send Restrictions are not placed on `ModuleToAccount` or `ModuleToModule` transfers. This is done due to modules needing to move funds to user accounts and other module accounts. This is a design decision to allow for more flexibility in the state machine. The state machine should be able to move funds between module accounts and user accounts without restrictions. + +Secondly this limitation would limit the usage of the state machine even for itself. users would not be able to receive rewards, not be able to move funds between module accounts. In the case that a user sends funds from a user account to the community pool and then a governance proposal is used to get those tokens into the users account this would fall under the discretion of the app chain developer to what they would like to do here. We can not make strong assumptions here. +Thirdly, this issue could lead into a chain halt if a token is disabled and the token is moved in the begin/endblock. This is the last reason we see the current change and more damaging then beneficial for users. + For example, in your module's keeper package, you'd define the send restriction function: ```golang