Skip to content

docs: Module account address documentation #22289

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
julienrbrt merged 9 commits into from
Nov 4, 2024
Merged

docs: Module account address documentation #22289

Changes from 8 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
d813d94
feat(docs): add module account docs
ziscky Oct 10, 2024
e0735b7
feat(docs): add module account docs
ziscky Oct 11, 2024
b6a45d6
feat(docs): update adr-028 link
ziscky Oct 16, 2024
ac1a4bc
feat(docs): update adr link
ziscky Oct 16, 2024
2ea67e6
Merge branch 'main' into ziscky/9916-module-adress-gen-docs
ziscky Oct 31, 2024
62a4e54
docs: move to advanced concepts
ziscky Nov 4, 2024
69cb74c
Merge branch 'main' into ziscky/9916-module-adress-gen-docs
ziscky Nov 4, 2024
0f1d89b
feat(docs): move docs to accounts section
ziscky Nov 4, 2024
73865eb
feat(docs): add module account intro.
ziscky Nov 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions docs/learn/beginner/03-accounts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,23 @@ https://github.com/cosmos/cosmos-sdk/blob/v0.52.0-beta.2/codec/address/bech32_co
| Validator Operator | cosmosvaloper |
| Consensus Nodes | cosmosvalcons |


### Module Accounts

Copy link
Contributor

@julienrbrt julienrbrt Nov 4, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let's have an intro on module accounts as well

#### Address Generation

Module account addresses are generated deterministically from the module name, as defined in [ADR-028](../../architecture/adr-028-public-key-addresses.md)

Definition of account permissions is done during the app initialization.
Comment on lines +106 to +108
Copy link
Contributor

@coderabbitai coderabbitai bot Nov 4, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Add practical examples of module account address generation.

The documentation should include:

  1. Concrete examples of how module account addresses are generated
  2. The specific format and structure of the generated addresses
  3. Example code showing how to generate and validate module account addresses

Example addition:

 Module account addresses are generated deterministically from the module name, as defined in [ADR-028](../../architecture/adr-028-public-key-addresses.md) 
+
+For example, to generate a module account address for the "mint" module:
+```go
+mintModuleAddr := authtypes.NewModuleAddress("mint")
+fmt.Printf("Mint module address: %s\n", mintModuleAddr)
+```
+
+Common module account names include:
+- "fee_collector": Collects transaction fees
+- "distribution": Handles reward distribution
+- "bonded_tokens_pool": Manages staked tokens
+- "not_bonded_tokens_pool": Manages unstaked tokens


```go reference
https://github.com/cosmos/cosmos-sdk/blob/3a03804c148d0da8d6df1ad839b08c50f6896fa1/simapp/app.go#L130-L141
```

```go reference
https://github.com/cosmos/cosmos-sdk/blob/3a03804c148d0da8d6df1ad839b08c50f6896fa1/simapp/app.go#L328
```
Comment on lines +110 to +116
Copy link
Contributor

@coderabbitai coderabbitai bot Nov 4, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Add context to code references.

The code references need explanatory text to help readers understand:

  1. What these code snippets demonstrate
  2. How they relate to module account initialization
  3. The significance of the permissions being set

Example addition:

+The following code demonstrates how module accounts are initialized in a Cosmos SDK application:
+
 ```go reference
 https://github.com/cosmos/cosmos-sdk/blob/3a03804c148d0da8d6df1ad839b08c50f6896fa1/simapp/app.go#L130-L141

+This initialization process:
+1. Creates module accounts with specific names
+2. Assigns appropriate permissions to each module account
+3. Registers the accounts in the auth keeper


<!-- This is an auto-generated comment by CodeRabbit -->


Copy link
Contributor

@coderabbitai coderabbitai bot Nov 4, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Enhance the Module Accounts section with more details

The Module Accounts section needs improvement in the following areas:

  1. Add explanation of what module accounts are and their purpose
  2. Provide specific examples of module account address generation
  3. Explain the permissions system and its implications
  4. Add context for the code references to help readers understand their purpose

Consider adding content like this before the code references:

 ### Module Accounts
+
+Module accounts are special-purpose accounts for modules to perform specific operations. Unlike regular accounts, they are controlled by the module's logic rather than private keys.
+
 #### Address Generation
 
-Module account addresses are generated deterministically from the module name, as defined in [ADR-028](../../architecture/adr-028-public-key-addresses.md) 
+Module account addresses are generated deterministically from the module name, as defined in [ADR-028](../../architecture/adr-028-public-key-addresses.md). For example, if a module is named "mint", its address would be derived using:
+```go
+authtypes.NewModuleAddress("mint")
+```
+
+This ensures that module accounts have consistent addresses across all chains using the same module name.
 
-Definition of account permissions is done during the app initialization.
+Module accounts can be granted specific permissions during app initialization. These permissions control what operations the module can perform, such as minting tokens or sending tokens to accounts.

### Public Keys

Public keys in Cosmos SDK are defined by `cryptotypes.PubKey` interface. Since public keys are saved in a store, the `cryptotypes.PubKey` extends the `proto.Message` interface:
Expand Down