Docs address and other fixes #941
Conversation
📝 WalkthroughWalkthroughThe pull request includes modifications to three documentation files aimed at enhancing clarity and updating command syntax. Key updates include the addition of "Overview" sections, revisions to command syntax for displaying public addresses, and adjustments to command descriptions and parameters. The documents now provide clearer instructions and organized code snippets to facilitate user understanding of keychain operations and validator creation. Changes
Possibly related PRs
Suggested labels
Suggested reviewers
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
Documentation and Community
|
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (19)
docs/developer-docs/docs/operate-a-node/create-a-validator.md (1)
34-34: Correct command syntax update, consider adding an explanation.The update from
-addressto--addressis correct and improves the accuracy of the command. This change ensures that users can successfully retrieve their public address.Consider adding a brief explanation of what this command does, for example:
wardend keys show my-key-name --address +# This command displays the public address associated with the key pair 'my-key-name'This addition would provide more context for users, especially those new to the system.
docs/developer-docs/docs/build-an-app/deploy-smart-contracts-on-warden/deploy-a-wasm-contract.md (10)
Line range hint
8-13: Great addition of the Overview section!The new Overview section provides a clear introduction to the topic and sets the context for the guide. It's helpful that you've included a link to more detailed information about the
x/wasmmodule.Consider adding a brief mention of the benefits of using WebAssembly smart contracts to further motivate the reader.
Line range hint
15-45: Excellent expansion of the Prerequisites section!The detailed instructions for setting up the development environment are very helpful. The inclusion of specific commands for installation and checking available keys will make it easier for users to get started.
Consider adding a note about the approximate time it might take to complete the setup process, to help users plan accordingly.
Line range hint
54-131: Well-structured contract code provided!The code for the "Hello World" contract is clear, well-structured, and properly formatted. Splitting the code into
contract.rsandmsg.rsfollows good practice and improves readability.Consider adding brief comments explaining the purpose of each function in the contract code, especially for beginners who might be new to CosmWasm development.
Line range hint
133-139: Clear instructions for compiling the contract!The command provided for compiling the contract is straightforward, and it's good that you set the expectation of no errors.
Consider adding a note on what to do if errors occur during compilation, such as double-checking the code or seeking help in the Discord community.
Line range hint
141-146: Good inclusion of the optimization step!The command for optimizing the compiled Wasm code using
wasm-optis correct and clearly formatted. This step is crucial for reducing contract size and gas costs.Consider briefly explaining the benefits of optimization (e.g., reduced gas costs, improved performance) to help users understand its importance.
Line range hint
148-152: Concise instruction for running the chain!The command to start the local chain is clear, and it's good that you consider the possibility that the chain might already be running.
Consider adding a note on how to check if the chain is already running, to help users avoid starting multiple instances unnecessarily.
Line range hint
154-170: Clear instructions for storing the contract on-chain!The commands provided for storing the contract on the Warden chain are clear and well-explained. The use of tabs for different node settings is very helpful, providing flexibility for users with different setups.
Consider adding a brief explanation of what the
--gas-adjustmentand--gas-pricesparameters do, to help users understand their purpose and how they might need to adjust them.
Line range hint
172-203: Well-explained steps for getting the code ID and instantiating the contract!The instructions for retrieving the code ID and instantiating the contract are clear and detailed. The use of tabs for different node settings is consistent and helpful. The explanation about admin options provides valuable information for users.
Consider adding a brief explanation of what "instantiating" a contract means in this context, as it might not be immediately clear to beginners.
Line range hint
205-240: Comprehensive instructions for interacting with the contract!The steps for getting the contract address, executing the contract, and querying it are well-explained and follow a logical sequence. The use of tabs for different node settings in the execution command is consistent with previous sections. Providing the expected output for the query is particularly helpful for users to verify their results.
Consider adding brief explanations of what "executing" and "querying" a contract mean in this context, to help beginners understand the difference between these operations.
Line range hint
242-244: Great conclusion with support information!Providing links to Discord and Twitter for support is very helpful for users who might encounter issues. The encouraging message at the end adds a positive tone to the guide.
Consider adding a brief summary of what the reader has accomplished by following this guide, to reinforce their learning and provide a sense of achievement.
docs/developer-docs/docs/build-a-keychain/operate-a-keychain/create-a-keychain.md (2)
135-135: Improved clarity in command description.The change from 'my-keychain-name' to 'my-keychain-description' for the
--descriptionparameter is a good improvement. It more accurately reflects the expected input for this field.Consider adding a brief explanation of what constitutes a good keychain description, either in the command example or in a separate note. This could help users provide more meaningful descriptions.
Line range hint
1-338: Overall improvement in document clarity and usability.The changes made to this document have significantly enhanced its clarity and usability. The instructions are clearer, and the code snippets are well-organized, which will greatly aid users in understanding keychain operations and validator creation.
To further improve the document:
- Conduct a final proofreading to ensure consistency in terminology and command usage throughout the document.
- Consider adding a table of contents at the beginning of the document for easier navigation, especially given its length and the multiple sections it contains.
docs/developer-docs/docs/build-a-keychain/operate-a-keychain/fulfill-requests-from-cli.md (6)
Line range hint
9-21: Consider clarifying the purpose of CLIChain in the Overview.The Overview section provides a good introduction to the document's content. To enhance clarity, consider explicitly stating the purpose of CLIChain in the context of fulfilling key and signature requests. This will help readers better understand its role in the process.
Suggested addition after the second paragraph:
CLIChain is used specifically for generating cryptographic keys and signing messages, which are essential steps in fulfilling key and signature requests.
Line range hint
23-68: Ensure consistent formatting for command outputs.The Prerequisites section provides clear instructions for both local and Buenavista setups. However, there's a minor inconsistency in the formatting of command outputs.
For consistency, consider using code blocks for all command outputs. For example, modify the Space ID instruction as follows:
- Query Spaces. The list will contain Space IDs and account addresses. You should note down the Space ID associated with your address.wardend query warden spaces
--node https://rpc.buenavista.wardenprotocol.org:443The output will look similar to this:spaces:
- account_address: warden1...
id: "1"- account_address: warden2...
id: "2"This change will make the document more consistent and easier to read.
Line range hint
70-76: Provide more context for the CLIChain installation location.The installation instructions for CLIChain are clear, but they assume the reader knows where the
wardenprotocoldirectory is located.Consider adding a note to clarify the location of the
wardenprotocoldirectory. For example:## 1. Install CLIChain To install CLIChain, navigate to the `wardenprotocol` directory (this is typically the root directory of the Warden Protocol repository) and run this command: ```bash go install ./cmd/clichainIf you haven't cloned the Warden Protocol repository yet, you can do so with:
git clone https://github.com/warden-protocol/wardenprotocol.git cd wardenprotocolThis additional context will help users who might be unfamiliar with the project structure. --- Line range hint `78-124`: **Improve formatting consistency for variable explanations.** The "Export variables" section is well-organized and provides clear instructions for different setups. However, there's a minor inconsistency in the formatting of the variable explanations. Consider using a consistent format for all variable explanations. For example: ```markdown - `CHAIN_ID`: The chain ID you used when running a node. - Returned by: `wardend status` in the `network` field. - `KEY_NAME`: Your local account name, or key name. - Returned by: `wardend keys list`. - `SPACE_ID`: Your Space ID. - Returned by: `wardend query warden spaces`. - `KEYCHAIN_ID`: Your Keychain ID obtained when [registering a Keychain](create-a-keychain#2-register-a-keychain). - Returned by: `wardend query warden keychains` in the `id` field. - `KEYCHAIN_WRITER_NAME`: Your Keychain Writer name specified when [adding a Keychain Writer](create-a-keychain#3-add-a-keychain-writer). - Returned by: `wardend keys list`. - `RPC_URL`: The RPC URL for interacting with Buenavista.This format makes it easier for readers to quickly understand what each variable represents and how to obtain its value.
Line range hint
126-226: Improve consistency in step numbering and command output formatting.The "Fulfill a key request" section provides clear instructions, but there are some minor inconsistencies in step numbering and command output formatting.
Consider the following improvements:
- Ensure consistent numbering of steps. Currently, steps 3 and 4 are not numbered.
- Use code blocks consistently for all command outputs. For example, in step 2, the command output should be in a code block.
- Consider adding a brief explanation before each command to clarify its purpose.
Here's an example of how step 2 could be improved:
```bash wardend query warden key-requests --keychain-id $KEYCHAIN_ID --node $RPC_URL ```2. Get all key requests: <Tabs> <TabItem value="local" label="Local node"> ```bash wardend query warden key-requests --keychain-id $KEYCHAIN_IDThis command will return a list of key requests. Your request ID will be in the
idfield of the output:key_requests: - creator: warden1d652c9nngq5cneak2whyaqa4g9ehr8pstxj0r5 deducted_keychain_fees: [] id: "1" key_type: KEY_TYPE_ECDSA_SECP256K1 keychain_id: "1" space_id: "1" status: KEY_REQUEST_STATUS_PENDING pagination: total: "1"
Export the request ID:
export KEY_REQUEST_ID=1Replace
1with the actual ID you obtained from the previous step.```bash wardend query warden sign-requests --keychain-id $KEYCHAIN_ID --node $RPC_URL ```Applying similar improvements throughout the section will enhance readability and consistency. --- Line range hint `228-352`: **Enhance consistency in command output formatting and step numbering.** The "Fulfill a signature request" section provides comprehensive instructions, but there are some minor inconsistencies in command output formatting and step numbering. Consider the following improvements: 1. Use code blocks consistently for all command outputs. For example, in steps 2 and 6, the command outputs should be in code blocks. 2. Ensure consistent numbering of steps. Currently, the step after the tip is not numbered. 3. Consider adding brief explanations before each command to clarify its purpose. Here's an example of how step 2 could be improved: ```markdown 2. Get all signature requests: <Tabs> <TabItem value="local" label="Local node"> ```bash wardend query warden sign-requests --keychain-id $KEYCHAIN_IDThis command will return a list of signature requests. Your request ID and data for signing will be in the
idanddata_for_signingfields of the output:pagination: total: "1" - Result: null creator: warden1d652c9nngq5cneak2whyaqa4g9ehr8pstxj0r5 data_for_signing: MrT1dvxgez7QoVFudyVn5S8xCTJjxUi5xxZyWHcji5Q= deducted_keychain_fees: [] id: "1" key_id: "1" status: SIGN_REQUEST_STATUS_PENDING
Export the request details:
export DATA=MrT1dvxgez7QoVFudyVn5S8xCTJjxUi5xxZyWHcji5Q= export SIGN_REQUEST_ID=1Replace the values with the actual data and request ID you obtained from the previous step.
Applying similar improvements throughout the section will enhance readability and consistency. </blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **Configuration used: .coderabbit.yaml** **Review profile: CHILL** <details> <summary>📥 Commits</summary> Files that changed from the base of the PR and between db10f6ef19312689280b80fb5d808940c5c8350c and 65681d6d2332ec2d0e55a1b15fa33bc4d286ccd4. </details> <details> <summary>📒 Files selected for processing (4)</summary> * docs/developer-docs/docs/build-a-keychain/operate-a-keychain/create-a-keychain.md (5 hunks) * docs/developer-docs/docs/build-a-keychain/operate-a-keychain/fulfill-requests-from-cli.md (1 hunks) * docs/developer-docs/docs/build-an-app/deploy-smart-contracts-on-warden/deploy-a-wasm-contract.md (1 hunks) * docs/developer-docs/docs/operate-a-node/create-a-validator.md (1 hunks) </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>📓 Path-based instructions (4)</summary><blockquote> <details> <summary>docs/developer-docs/docs/build-a-keychain/operate-a-keychain/create-a-keychain.md (1)</summary> Pattern `**/*.md`: "Assess the documentation for misspellings, grammatical errors, missing documentation and correctness" </details> <details> <summary>docs/developer-docs/docs/build-a-keychain/operate-a-keychain/fulfill-requests-from-cli.md (1)</summary> Pattern `**/*.md`: "Assess the documentation for misspellings, grammatical errors, missing documentation and correctness" </details> <details> <summary>docs/developer-docs/docs/build-an-app/deploy-smart-contracts-on-warden/deploy-a-wasm-contract.md (1)</summary> Pattern `**/*.md`: "Assess the documentation for misspellings, grammatical errors, missing documentation and correctness" </details> <details> <summary>docs/developer-docs/docs/operate-a-node/create-a-validator.md (1)</summary> Pattern `**/*.md`: "Assess the documentation for misspellings, grammatical errors, missing documentation and correctness" </details> </blockquote></details> </details> <details> <summary>🔇 Additional comments (5)</summary><blockquote> <details> <summary>docs/developer-docs/docs/build-an-app/deploy-smart-contracts-on-warden/deploy-a-wasm-contract.md (1)</summary><blockquote> Line range hint `47-52`: **Clear instructions for creating a CosmWasm project!** The use of `cargo-generate` with a template from GitHub simplifies the process for users. The instructions are concise and easy to follow. </blockquote></details> <details> <summary>docs/developer-docs/docs/build-a-keychain/operate-a-keychain/create-a-keychain.md (3)</summary><blockquote> Line range hint `9-15`: **Great addition of the Overview section!** The new Overview section provides valuable context for becoming a Keychain operator and clearly outlines the options available to users. It enhances the document's clarity and user-friendliness. --- `282-282`: **Consistent keychain ID usage.** The change of `--keychain-id` from 2 to 1 aligns with the previously created Keychain ID in the document, improving consistency. To ensure this change is correct and consistent across the documentation, please run the following verification script: <details> <summary>✅ Verification successful</summary> <!-- [monologue] [task verify_review_comment_1/1] [observations] - The `rg` command found two instances of `wardend tx warden add-keychain-writer` with `--keychain-id` set to 1 in the specified markdown file. - No instances with `--keychain-id` set to 2 were found. [analysis] - The change from `--keychain-id` 2 to 1 in the review comment aligns with all occurrences in the documentation. - There are no remaining instances of `--keychain-id` 2, indicating consistency. [actions] - Conclude that the verification is successful and the change is consistent across the documentation. --> **Keychain ID Consistency Verified** All instances of `--keychain-id` in `wardend tx warden add-keychain-writer` commands are set to 1, ensuring consistency throughout the documentation. </details> <details> <summary>🏁 Scripts executed</summary> The following scripts were executed for the analysis: Script: ```shell #!/bin/bash # Description: Verify the usage of '--keychain-id' in wardend commands # Test: Search for occurrences of 'wardend tx warden add-keychain-writer' with '--keychain-id' rg --type md 'wardend tx warden add-keychain-writer.*--keychain-id'Length of output: 385
97-97: Correct update of command syntax.The change from
-addressto--addressin the command syntax appears to be a correction. This update likely reflects the correct usage of the command.To ensure this change is correct and consistent across the documentation, please run the following verification script:
✅ Verification successful
Verification Successful: Command Syntax is Correct
The usage of
--addressin thewardend keys showcommand is correct and consistent throughout the documentation. No instances of the deprecated-addressflag were found.🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash # Description: Verify the usage of '--address' flag in wardend commands # Test: Search for occurrences of 'wardend keys show' with '-address' or '--address' rg --type md 'wardend keys show.*-{1,2}address'Length of output: 385
docs/developer-docs/docs/build-a-keychain/operate-a-keychain/fulfill-requests-from-cli.md (1)
Line range hint
1-352: Overall, excellent improvements to the documentation.The document has been significantly enhanced with clearer instructions, better organization, and more comprehensive content. The addition of the Overview section, expanded Prerequisites, and detailed step-by-step instructions for fulfilling key and signature requests greatly improve the user experience.
Key improvements:
- Clear separation of instructions for local and Buenavista setups using tabs.
- Detailed explanations of environment variables and their purposes.
- Helpful tips, such as creating a Base64-encoded hash for testing.
- Consistent use of code blocks for commands and their outputs.
The minor suggestions provided in the review comments, if implemented, will further enhance the document's consistency and readability. Great job on improving this crucial piece of documentation!
Summary by CodeRabbit
New Features
Documentation