Docs/miners documentation improvements#77
Merged
torrejonv merged 25 commits intoOct 30, 2025
Merged
Conversation
- Add missing ResetBlockAssemblyFully method to service documentation - Remove non-existent resetWaitCount and resetWaitTime fields from StateMessage - Correct GetBlockAssemblyBlockCandidate method description - Ensure documentation matches actual protobuf definition and implementation Fixes #4287
- Add missing GetNextBlockID method to service documentation - Add missing GetBlocksByHeight method for retrieving full blocks by height range - Add missing FindBlocksContainingSubtree method for subtree hash searches - Add missing GetBlockHeadersFromCommonAncestor method for header retrieval - Add missing ReportPeerFailure method for peer failure notifications - Fix InvalidateBlock return type from Empty to InvalidateBlockResponse - Correct GetBlockHeadersToCommonAncestor method description - Update Table of Contents with all missing message types - Ensure all 49 methods are properly documented and match proto definition Related to #4287
- Add missing base_url and peer_id fields to ProcessBlockRequest - Add missing is_revalidation field to ValidateBlockRequest - Fix timestamp field type reference formatting in HealthResponse - Ensure all field types use consistent markdown link format - Verify all 4 methods match actual protobuf definition and implementation Related to #4287
- Remove unused GetRequest and GetResponse message types from documentation - Update Table of Contents to remove references to unused messages - Ensure documentation only includes message types used by service methods - Verify all 3 service methods match actual protobuf definition and implementation - Clean up documentation to avoid confusion with unused legacy message types Related to #4287
- Fix timestamp field type reference formatting in HealthResponse - Ensure consistent markdown link format with proper hyphen usage - Verify all 3 service methods match actual protobuf definition and implementation - Confirm all message types and field descriptions are accurate - Validate markdown formatting passes validation script checks Related to #4287
- Fix AddBlock options format from old protobuf wrappers to direct boolean fields - Add missing methods: FindBlocksContainingSubtree, ReportPeerFailure, SetBlockProcessedAt - Add FSM-related methods: GetStoreFSMState, ResetFSMS, IsFullyReady, SetSubscriptionManagerReadyForTesting - Remove duplicate GetNextBlockID section - Correct GetBlocksByHeight description to clarify it returns full blocks - Update method signatures and descriptions to match current implementation Addresses task #4287 - Periodic review of service and store reference documentation
- Add missing Server struct fields: blockchainClient and state - Add WithSetInitialState configuration function - Add missing internal methods: getNextBlockToProcess, readSubtreeData, readSubtree, processTxMetaUsingStore - Fix ProcessSubtree method signature to include utxoDiff parameter - Update method descriptions to match current implementation - All changes verified against actual source code implementation Addresses task #4287 - Periodic review of service and store reference documentation
- Add missing Server struct fields: blockPriorityQueue, blockClassifier, forkManager, catchupAlternatives - Fix incorrect field name from processSubtreeNotify to processBlockNotify - Add missing blockAssemblyClient parameter to New function signature - Fix Start method signature to include readyCh parameter - Add missing ValidateBlock public API method - Add internal processing methods: processBlockFound, checkParentProcessingComplete, startBlockProcessingSystem, blockProcessingWorker, addBlockToPriorityQueue, processBlockWithPriority - Document priority-based processing system and fork management architecture - All changes verified against actual source code implementation Addresses task #4287 - Periodic review of service and store reference documentation
- Add missing Server struct fields: validationClient, subtreeStore, tempStore, utxoStore, subtreeValidation, blockValidation, blockAssemblyClient - Complete Server struct definition to match actual implementation - Add internal methods documentation: banPeer and logPeerStats - Verify all method signatures match implementation - All changes verified against actual source code in Server.go Addresses task #4287 - Periodic review of service and store reference documentation
- Fix Server struct field names: P2PNode -> P2PClient, bitcoinProtocolID -> bitcoinProtocolVersion - Add missing Server struct fields: subtreePeerMap, startTime, peerRegistry, peerSelector, peerHealthChecker, syncCoordinator, syncConnectionTimes, peerMapCleanupTicker, peerMapMaxSize, peerMapTTL - Update NewServer function signature to include missing parameters: blockAssemblyClient, invalidBlocksKafkaConsumerClient, invalidSubtreeKafkaConsumerClient - Add missing public API methods: GetPeers, BanPeer, UnbanPeer, IsBanned - Update message handlers list to match actual implementation - All changes verified against actual source code in Server.go Addresses task #4287 - Periodic review of service and store reference documentation
- Verify and update PropagationServer struct and method documentation against actual implementation - Add missing configuration settings (HTTPAddresses, AlwaysUseHTTP, SendBatchSize, SendBatchTimeout, GRPCAddresses) - Correct HTTP integration details and remove incorrect middleware information - Add missing processTransactionInternal method documentation - Enhance transaction processing flow with sanity checks and size-based routing details - Add batch processing limits (1024 transactions, 32MB data size) - Fix markdown formatting issues with validation script All documentation now accurately reflects the current implementation in services/propagation/Server.go
- Verify and update RPCServer struct definition against actual implementation - Add missing blockValidationClient field to RPCServer struct - Update NewServer function signature to include blockValidationClient parameter - Add missing supported RPC commands (getrawmempool, getchaintips) - Correct getrawmempool documentation to reflect Teranode's subtree-based architecture - Remove mempool-related references that don't apply to Teranode's design - Update configuration settings to match actual implementation - Correct default values for rpc_max_clients and rpc_quirks - Add rpc_cache_enabled setting documentation - Remove non-existent TLS and security settings from documentation All documentation now accurately reflects the current RPC service implementation in Teranode's subtree-based architecture.
- Verify and validate all struct definitions against actual implementation - Fix ValidateSubtreeInternal method signature to include missing return value - Correct return type from (err error) to (subtree *subtreepkg.Subtree, err error) - Apply markdown formatting fixes via validation script (6 issues resolved) - Ensure all method signatures match current implementation exactly - Validate Server struct, New function, and core method definitions - Confirm ValidateSubtree and missingTx struct definitions are accurate All documentation now accurately reflects the current subtree validation service implementation with proper markdown formatting.
- Verify and validate all struct definitions against actual implementation - Fix UTXOWrapper struct definition to include missing UTXOTotalValue field - Add UTXOTotalValue uint64 field with proper documentation - Confirm all other struct definitions (Server, UTXOSet, UTXO, UTXODeletion, BlockIndex) match implementation - Verify constructor function signatures (New and NewDirect) are accurate - Validate all method signatures match current implementation exactly - Ensure comprehensive coverage of UTXO persistence service functionality All documentation now accurately reflects the current UTXO Persister service implementation with complete struct definitions.
- Verify and validate all struct definitions against actual implementation - Fix Validator struct definition to include missing blockchainClient field - Add blockchainClient blockchain.ClientI field with proper documentation - Fix New function signature to include missing blockchainClient parameter - Add blockchainClient blockchain.ClientI parameter to constructor - Confirm all other struct definitions (Server) match implementation exactly - Verify all method signatures match current implementation - Ensure comprehensive coverage of transaction validation service functionality All documentation now accurately reflects the current TX Validator service implementation with complete struct definitions and function signatures.
- Verify and validate all struct definitions against actual implementation - Fix MinedBlockInfo struct to include missing OnLongestChain field - Add OnLongestChain bool field with proper documentation - Fix UnminedTransaction struct to include missing fields (Skip, UnminedSince, BlockIDs) - Add Skip bool, UnminedSince int, and BlockIDs []uint32 fields - Fix GetUnminedTxIterator method signature to include fullScan parameter - Add missing MarkTransactionsOnLongestChain method to Store interface - Update Key Functions section to include new method - Confirm all other struct definitions match implementation exactly - Ensure comprehensive coverage of UTXO store functionality All documentation now accurately reflects the current UTXO Store implementation with complete struct definitions and interface methods.
- Verify and validate all protobuf message definitions against actual implementation - Fix KafkaSubtreeTopicMessage to include missing peer_id field - Add peer_id field (string peer_id = 3) with proper documentation - Update field specifications, examples, and code samples for subtree messages - Fix KafkaRejectedTxTopicMessage to include missing peer_id field - Add peer_id field for tracking rejection source (internal vs external peer) - Update field specifications, examples, and code samples for rejected transaction messages - Confirm all other message definitions match protobuf implementation exactly - Ensure comprehensive coverage of all Kafka message formats used in Teranode All documentation now accurately reflects the current protobuf definitions with complete message structures and proper field documentation.
- Remove non-existent files from root level (docker-compose.yml, settings_local.conf) - Add missing cmd/ directories to match actual implementation: - checkblock/ (tool to check individual blocks) - resetblockassembly/ (tool to reset block assembly state) - utxovalidator/ (UTXO validation utility) - Add topics/ directory to docs/ structure (major documentation directory) - Verify all other directories match actual project structure Documentation now accurately reflects the current Teranode project organization.
- Verify all struct definitions against actual implementation - Add missing chaos/ directory to test directory structure - Confirm TeranodeTestEnv, TeranodeTestClient, and SVNodeTestClient structs match exactly - Verify all function signatures and method definitions are accurate - Ensure comprehensive coverage of testing framework functionality Documentation now accurately reflects the current testing framework implementation with complete directory structure.
- Add test comment to Alert Protobuf documentation - Verify proper Git identity attribution (Vicente Torrejon) - Test SSH key signing functionality - Ensure commits are no longer attributed to machine hostname This is a test commit to validate the Git configuration changes.
Reorganize documentation to better separate Docker and Kubernetes deployment concerns: - Move backup, reset, and sync guides to deployment-specific directories - Update teranode-cli references and usage examples throughout - Consolidate navigation structure in mkdocs.yml - Update cross-references between related documentation pages
Create comprehensive configuration template to guide Docker users: - Add deploy/docker/base/settings_local.conf.template with detailed documentation - Document all settings managed by teranode-teratestnet (network mode, endpoints, RPC, mining, etc.) - Include educational comments explaining purpose, usage, and examples for each setting - Update Docker installation and configuration docs to reference the template file - Add clickable GitHub links to template in documentation This template helps miners and operators understand Docker-specific configuration options without requiring them to parse the entire settings.conf file.
a7df993 to
2a9e094
Compare
Contributor
|
🤖 Claude Code Review Status: Complete Review SummaryThis PR comprehensively improves Teranode documentation with focus on:
Files reviewed: 37 changed files (+1,952 / -605 lines) Findings✅ All previously reported issues have been resolved:
✅ No new issues found The documentation changes are well-structured and improve clarity for users. Key improvements include:
Recommendation: This PR is ready to merge. The documentation improvements enhance usability and accuracy across miner guides, developer setup, and API references. |
oskarszoon
requested changes
Oct 30, 2025
This commit addresses documentation improvements across multiple guides: ## Miner Documentation Fixes - Standardize Docker Compose syntax from `docker-compose` to `docker compose` (modern CLI v2) - Standardize CLI flag syntax from `-fsmstate` to `--fsmstate` for consistency - Updated both Docker and Kubernetes sync guides ## Debugging Documentation - Make remote debug guide IDE-agnostic (previously VS Code-specific) - Add support documentation for VS Code, GoLand, and Delve CLI - Add debugging section to Developer Setup guide with cross-references - Include local and remote debugging scenarios ## Developer Setup Improvements - Replace Docker Desktop references with OrbStack for Mac developers - Highlight OrbStack benefits (2-3x faster, lighter, native macOS integration) - Fix all pre-existing markdownlint issues (MD012, MD031, MD035, MD051) - Improve document formatting and consistency All changes validated with markdownlint and validate-markdown.py with zero errors.
26425f4 to
5c11e3d
Compare
oskarszoon
requested changes
Oct 30, 2025
Replace all occurrences of 'docker-compose' (hyphenated) with 'docker compose' (space-separated) for CLI commands throughout documentation. This aligns with Docker Compose V2 CLI syntax which is the current standard. Note: File references (docker-compose.yml, docker-compose-3blasters.yml, etc.) retain hyphens as per actual filenames. Files updated: - docs/howto/miners/docker/*.md (5 files) - docs/tutorials/miners/minersGettingStarted.md - docs/references/testingTechnicalReference.md
0f07384 to
8f4355a
Compare
|
oskarszoon
approved these changes
Oct 30, 2025
galt-tr
pushed a commit
to galt-tr/teranode
that referenced
this pull request
Oct 31, 2025
Co-authored-by: oskarszoon <1449115+oskarszoon@users.noreply.github.com>
9 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.



No description provided.