doc: add guide to use chopsticks

[1xstj]

Summary of changes
Changes introduced in this pull request:

Reference issue to close (if applicable)

Closes

[claude]

Claude finished @1xstj's task —— View job

---

PR Review Complete

Todo List:

• Read and analyze README.md changes
• Read and analyze the new chopsticks.yml configuration file
• Evaluate documentation quality and completeness
• Check for potential security implications
• Assess configuration best practices
• Provide comprehensive review feedback

---

Review Feedback

This PR adds valuable development tooling documentation for Chopsticks integration. The changes are well-structured and provide a good foundation for developers. Here's my detailed feedback:

✅ Strengths

1. Clear Documentation: The README section explains Chopsticks well with proper context and use cases
2. Practical Configuration: The chopsticks.yml provides a ready-to-use development setup
3. Good Structure: Proper integration into the existing README structure with ToC updates
4. Development-Focused: Pre-funded accounts and instant block mode improve developer experience

🔍 Areas for Improvement

Documentation Issues (README.md:91-125)

1. Missing Version Compatibility: Consider adding a note about which Chopsticks version was tested

   # Suggestion: Add after line 100
   # Note: Tested with Chopsticks v0.12.3
   

2. No Cleanup Instructions: Missing information about stopping the Chopsticks service

   # Suggestion: Add section about stopping the service
   To stop the Chopsticks fork, press Ctrl+C in the terminal where it's running.
   

3. Limited Troubleshooting: Could benefit from common Chopsticks issues and solutions

Configuration Issues (scripts/chopsticks.yml)

1. Lack of Comments: The YAML file would benefit from inline comments explaining each setting:

   # Connect to Tangle testnet
   endpoint: wss://rpc.tangle.tools
   # Enable instant block production for faster development
   build-block-mode: Instant

2. Hardcoded Addresses: The account addresses (lines 13, 19, 25) lack explanation:

   # Consider adding comments identifying what these addresses represent
   - 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY # Alice
   - ZAP5o2BjWAo5uoKDE6b6Xkk4Ju7k6bDu24LNjgZbfM3iyiR # Bob (example)

3. Runtime Log Level: Level 5 might be too verbose. Consider documenting this choice or making it configurable.

🔒 Security Considerations

1. Development Context: ✅ Alice as sudo is appropriate for development/testing
2. Test Accounts: ✅ Pre-funded accounts are clearly for development use
3. Network Isolation: ✅ Forks don't affect the live network

Recommendation: Add a security note in the documentation:

**Note**: This configuration is for development purposes only. The sudo account and pre-funded addresses should never be used in production environments.

⚡ Performance Considerations

1. Instant Block Mode: ✅ Good choice for development speed
2. Log Level: Consider if level 5 is necessary for typical development workflows

📝 Missing PR Details

The PR description is incomplete. Consider updating it to include:

• What Chopsticks enables for Tangle development
• Brief description of the configuration provided
• Any testing performed

🎯 Minor Suggestions

1. Line 105: Consider adding a brief explanation of what "forking" means in the Chopsticks context
2. Line 115: The command could include a flag explanation: --config=scripts/chopsticks.yml

Overall Assessment

This is a solid contribution that adds valuable development tooling. The documentation is clear and the configuration is practical. With the suggested improvements, this will be an excellent resource for Tangle developers.

Status: ✅ Approve with minor suggestions

The changes are safe to merge, and the suggested improvements can be addressed in follow-up PRs if needed.

---