How milkyway-labs/milkyway works
Project Overview and Purpose
• MilkyWay is a blockchain-based protocol that provides liquid staking and restaking capabilities. It is a modular layer-1 coordination chain built on Cosmos SDK that allows diverse modules (assets, liquidvesting, operators, pools, restaking, rewards, services, tokenfactory, IBC hooks, etc.) to plug into the system.
• The README makes it clear that the project is designed to provide a secure and flexible staking infrastructure while allowing external tools (CLI, wallets, block explorers) to interact with the chain.
• The file structure contains directories for application logic (“app”), command-line interface (“cmd”), module implementations under “x”, and APIs and protobuf definitions (in “api” and “proto”), all indicative of a complex, modular blockchain ecosystem.
Major Components
Breaking the system into these high-level components:
A. Node and Core Application:
• “app” – Contains core blockchain application logic (ABCI, genesis, encoding, forks, upgrades, simulation, etc.).
• “cmd/milkywayd” – Provides the CLI/node daemon to start a MilkyWay blockchain node.
B. Modules/Subsystems:
• “x” directory – Includes all functional modules such as assets, bank, ibc-hooks, liquidvesting, operators, pools, restaking, rewards, services, and tokenfactory.
• Each module has its keeper, message server, client CLI, and testing utilities to encapsulate its functionality.
C. API and Communication Layer:
• “api” directory – Contains REST and gRPC endpoints for the modules (with versioned subdirectories and auto-generated protobuf files). This indicates support for client communication.
• “proto” directory – Provides protobuf definitions for all modules and external compatibility; this is essential for both the gRPC services and integration with CosmJS-compatible client libraries.
D. Development, Testing, and Build Infrastructure:
• “client”, “tools”, “scripts”, and “Makefile” – Components that support documentation generation, consensus testing, mock generation, and overall build/deployment.
E. External Interactions:
• Integration with wallets (Keplr, Cosmos Station, Leap) and external blockchain explorers as mentioned in the README.
• GitHub workflows, CI/CD configurations, and Dockerfiles for deployment.
Relationships and Data Flow
• The CLI daemon (milkywayd) initializes the core “app” which acts as a container for all individual modules (from “x”) that run the on-chain logic. The “app” communicates with the Tendermint-based consensus engine using ABCI.
• When transactions are submitted (from external wallets or direct CLI commands), they get normalized by the API layer (REST/gRPC as defined in “api” and “proto” directories) and then processed by the appropriate module (e.g., liquidvesting, rewards, operators).
• Internal state transitions, genesis initialization, and upgrades are handled within the “app” and through module-specific upgrade logic.
• Various “keepers” in the modules encapsulate business logic and ensure safe manipulation of the blockchain state.
Architectural Patterns and Design Principles
• Modular Architecture: The use of separate modules (each in the “x” folders) reflects a microkernel design where common infrastructure (e.g., account management, staking) is decoupled from application-specific logic.
• API-Driven Communication: The clearly separated “api” and “proto” directories indicate a well-defined communication layer using gRPC and protocol buffers.
• Separation of Concerns: The organization keeps CLI commands, application logic, module-specific keepers, and tests in different directories, enforcing a clear separation between interface, implementation, and testing.
• Extensibility: The number of modules and available hooks (for instance, IBC hooks) demonstrates the system’s flexibility and extensibility.
Assembly of the Components
• Branch it out to two major sections: “Core Application (app)” and “Module Services (x/*)”. Inside the module section, show individual modules grouped logically.
• Also plot “External Clients” (CLI, Wallets, Third-party Explorers) and show their communication channels into the API layer.
Final Advice to the Principal Software Engineer
• That architectural patterns such as modularity, separation of concerns, and resiliency are visually evident.
• Don’t hesitate to break down complex modules into further sub-components if necessary, especially if they own several “keeper”, “msg_server”, and “client” elements.