Skip to content

Docs/miners documentation improvements#77

Merged
torrejonv merged 25 commits into
bsv-blockchain:mainfrom
torrejonv:docs/miners-documentation-improvements
Oct 30, 2025
Merged

Docs/miners documentation improvements#77
torrejonv merged 25 commits into
bsv-blockchain:mainfrom
torrejonv:docs/miners-documentation-improvements

Conversation

@torrejonv

Copy link
Copy Markdown
Contributor

No description provided.

- 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.
@torrejonv torrejonv force-pushed the docs/miners-documentation-improvements branch 2 times, most recently from a7df993 to 2a9e094 Compare October 29, 2025 17:26
@github-actions

github-actions Bot commented Oct 30, 2025

Copy link
Copy Markdown
Contributor

🤖 Claude Code Review

Status: Complete


Review Summary

This PR comprehensively improves Teranode documentation with focus on:

  • Miner/operator guides (Docker & Kubernetes)
  • Service API reference documentation
  • Developer setup and debugging workflows

Files reviewed: 37 changed files (+1,952 / -605 lines)

Findings

✅ All previously reported issues have been resolved:

  • Docker Compose CLI syntax standardized to docker compose (v2) throughout
  • All inline comment feedback has been addressed

✅ No new issues found

The documentation changes are well-structured and improve clarity for users. Key improvements include:

  1. New configuration template (settings_local.conf.template) with comprehensive inline documentation
  2. Standardized Docker Compose syntax from deprecated docker-compose to modern docker compose
  3. Enhanced debugging guide - now IDE-agnostic (previously VS Code-only)
  4. OrbStack recommendation for Mac developers as faster Docker Desktop alternative
  5. Service reference updates - synchronized with actual protobuf/implementation
  6. Better organization - deployment-specific guides split between Docker/Kubernetes paths

Recommendation: This PR is ready to merge. The documentation improvements enhance usability and accuracy across miner guides, developer setup, and API references.

@torrejonv torrejonv enabled auto-merge (squash) October 30, 2025 11:31
Comment thread docs/howto/miners/docker/minersHowToInstallation.md Outdated
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.
@torrejonv torrejonv force-pushed the docs/miners-documentation-improvements branch from 26425f4 to 5c11e3d Compare October 30, 2025 18:03
@torrejonv torrejonv requested a review from oskarszoon October 30, 2025 18:19
Comment thread docs/howto/miners/docker/minersHowToInstallation.md Outdated
Comment thread docs/tutorials/miners/minersGettingStarted.md Outdated
Comment thread docs/tutorials/miners/minersGettingStarted.md Outdated
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
@torrejonv torrejonv force-pushed the docs/miners-documentation-improvements branch from 0f07384 to 8f4355a Compare October 30, 2025 18:35
@sonarqubecloud

Copy link
Copy Markdown

@torrejonv torrejonv requested a review from oskarszoon October 30, 2025 19:02
@torrejonv torrejonv merged commit 4556e82 into bsv-blockchain:main Oct 30, 2025
10 of 11 checks passed
@torrejonv torrejonv deleted the docs/miners-documentation-improvements branch October 31, 2025 09:13
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants