How moonsong-labs/storage-hub works
Based on our analysis of the file tree and README, StorageHub is a storage-optimized parachain designed to operate in the Polkadot and Kusama ecosystems. The project is a complex full-stack Substrate-based blockchain system that includes client-side modules, node implementation, a runtime composed of multiple pallets, underlying primitives, type definitions (via types-bundle), and a robust testing suite including Zombienet integration. The primary goal is to ensure efficient and decentralized storage with both primary (MSP) and backup (BSP) storage providers, supporting interoperability via XCM.
Main Components
• Runtime: This is the core Cumulus-based parachain runtime found in the “runtime” directory. It includes the configuration, genesis, and weights along with interface APIs.
• Pallets: Modular runtime components (under the “pallets” directory) that implement various on-chain functionalities such as file storage, payment streams, proofs-dealer, provider randomness, and more. Each pallet might represent a distinct business capability (e.g., file-system operations, bucket NFTs).
• Primitives: Fundamental definitions, constants, types, and traits shared across the runtime and pallets. They add consistency to the overall chain logic and are located in the “primitives” directory.
• Node: The “node” directory contains the implementation of the StorageHub node, including service configuration, RPC services, CLI and task scheduling. This component ties together the runtime execution and off-chain services.
• Client Modules: Components in “client” (including ledger services such as actors-framework, blockchain-service, file-manager, file-transfer-service, forest-manager, indexer-db, indexer-service, and rpc) represent various client-side interactions and service orchestration.
• Types Bundle: The “types-bundle” package contains the shared type definitions (rpc, runtime, types) necessary for frontend clients and API interactions, ensuring consistency with the on-chain types.
• Testing and Dev Tools: The “test” directory provides integration tests (with Zombienet, TypeScript tests, etc.), and additional support files, scripts, and configuration files (e.g., Docker, GitHub workflows) provide deployment and CI/CD capabilities.
Relationships and Interactions
• The client-side modules interact with the node via RPC and CLI interfaces.
• The node orchestrates the execution of the runtime, facilitating communication with clients, and managing off-chain tasks (e.g., handling MSP and BSP specific tasks like fee charging, file upload/download, moving buckets, and submitting proofs).
• RPC endpoints, defined in the runtime and updated via the “types-bundle” package, provide external interfaces for clients and third-party applications.
• The pallets (each representing discrete on-chain functionality) are integrated into the runtime and may rely on primitives for shared types and logic.
• Testing components simulate network behavior and validate functionality; they also interact with the node and runtime.
Architectural Patterns and Technologies
• Micro-modular design: Each major service (client, node, pallets) is kept isolated in its own directory and works together through well-defined interfaces.
• Substrate/Cumulus Framework: The storage-hub uses a Substrate-based runtime structure with a Cumulus parachain layer, emphasizing module reusability and interoperability.
• XCM Integration: The design supports cross-chain message passing, as evidenced by XCM configuration files in the xcm-simulator directory.
• Strong Type Safety and API Consistency: Via centralized definitions in “types-bundle” and the primitives.
• DevOps and CI/CD: With GitHub Actions workflows and Docker configurations for deployment and testing.
Elements
• Optionally, sketch out sub-components such as the XCM interface, detailing how messages route between parachains.
• Configuration and CI/CD integration as a side note to emphasize deployment and operational readiness.