How morpheusais/smartcontracts works
1. This repository is a Solidity/Hardhat monorepo for the Morpheus Network. The architecture is centered on three product areas: the MOR token, the Capital Protocol, and the Builders Protocol. TypeScript is used for deployment scripts, tests, and helper tooling.
2. The main on-chain boundary is the contracts/ tree. It contains the project’s own protocol contracts, shared libraries, interfaces, mocks, and older contract versions kept for migration and regression purposes. It also vendors LayerZero packages under contracts/@layerzerolabs/..., which is important because the token and cross-chain messaging depend on LayerZero abstractions.
3. The token subsystem is the MOR OFT implementation. Its purpose is to make the Morpheus token omnichain via LayerZero OFT mechanics, so token transfers are not limited to a single chain. The repo includes tests and deployment scripts for this token path separately from the capital and builder protocols.
4. The Capital Protocol is the largest subsystem and is split by role and chain. On L1, DistributionV6, DepositPool, ChainLinkDataConsumer, L1SenderV2, RewardPool, and Distributor work together. Distributor is the orchestration layer that aggregates reward/yield logic, while RewardPool handles MOR reward curves and DepositPool handles staking and yield accounting for multiple stake tokens.
5. The L1 capital flow is: user staking enters DepositPool, protocol yield is accumulated and interpreted by Distributor, and L1SenderV2 collects yield, converts it to wstETH, and forwards it cross-chain. ChainLinkDataConsumer supplies price feeds used in valuation and conversion decisions, so Chainlink is an external data dependency in the architecture.
6. On L2, L2TokenReceiverV2 and L2MessageReceiver are the receiving side of the same capital flow. L2TokenReceiverV2 is for token transfer reception and market-making-related handling, while L2MessageReceiver accepts cross-chain messages from the L1 sender. This creates a clear L1-to-L2 boundary: value is generated and consolidated on L1, then delivered and consumed on L2.
7. The Builders Protocol is a separate on-chain subsystem with its own stake and fee logic. BuilderSubnets is the primary contract that accepts user stakes, calculates rewards, and distributes them. FeeConfig defines protocol fee behavior. The presence of BuilderSubnets migration scripts and subnet configuration data indicates this protocol is operated as a configurable network of builder subnets rather than a single isolated contract.
8. The repo keeps previous generations of contracts under old/ directories and corresponding test folders. That suggests a versioned protocol evolution strategy, where new releases are verified against historical behavior and migration paths. This is reinforced by multiple migration scripts in deploy/ and by fork tests that validate behavior against real-chain state.
9. The code depends on several external DeFi and oracle integrations, but only where they matter to core flows: Chainlink for pricing, LayerZero for omnichain transport, Uniswap for swap/market-making behavior, Aave for capital-side integrations, and an Arbitrum bridge mock for cross-chain simulation. These appear mostly through interfaces and mocks, indicating the repository is contract-centric and integration-heavy rather than using off-chain services.
10. Deployment is configuration-driven. deploy/deploy-all.sh orchestrates the rollout across L1 and L2 networks using network-specific config files under deploy/data/. There are separate deployment subflows for capital, builders, MOR token, mocks, and fee config, which reflects that the system is deployed as coordinated protocol modules rather than one monolithic contract set.
11. Testing is a major architectural boundary. There are unit tests, fork tests against mainnet state, and helper deployers/mocks for isolated protocol composition. The test/helpers/ tree builds complete protocol fixtures, while test/fork/ validates integrations with real external systems and protocol state. This indicates the repo is designed for strong simulation of multi-contract behavior before deployment.
12. The documentation layout mirrors the architecture: docs/capital-protocol/ and docs/builder-protocol/ map directly to the protocol domains, with separate docs for contract responsibilities like distribution, deposit pools, senders, receivers, and fee configuration. For an architecture diagram, the clearest structure is: shared libs/interfaces at the base, protocol modules above them, and cross-chain/external integrations on the boundary edges.
Main entry points: deploy-all.sh Deploy all · capital-protocol Capital L1 · contracts MOR OFT · helpers Test fixtures
Components 18
Contracts
On-chain protocol code and vendored dependencies
- Core contracts · Shared libraries, interfaces, mocks, extensions, and legacy contract generations that support the main protocol modules.
contracts - LayerZero vendored · Vendored LayerZero OApp/OFT and messaging libraries used by the MOR token and cross-chain flows.
contracts/@layerzerolabs - MOR OFT · Omnichain MOR token implementation built on LayerZero OFT mechanics.
contracts - Capital L1 · L1 capital contracts for deposit accounting, reward curves, price consumption, and cross-chain yield forwarding.
contracts/capital-protocol - Capital L2 · L2 receivers for token delivery and L1 message consumption.
contracts/capital-protocol - Builders protocol · Builder subnet staking, reward, and fee logic for the builders network.
contracts/builder-protocol
Deploy
TypeScript deployment and migration flows
- Deploy all · Top-level shell orchestration for coordinated deployment across networks and protocol modules.
deploy/deploy-all.sh - Capital deploy · Capital protocol deployment and upgrade flows, including testnet and mainnet versioned migrations.
deploy/capital-protocol - Builders deploy · Builders protocol deployment, subnet initialization, and version migration flows.
deploy/builders-protocol - Token deploy · Deployment path for the MOR token and related bridge/bootstrap migrations.
deploy/mor - Fee deploy · Standalone deployment flow for protocol fee configuration.
deploy/fee-config - Network config · Network-specific configuration inputs used to parameterize deployment flows.
deploy/data/config.json
Tests
Unit, fork, and fixture-based validation
- Test fixtures · Reusable deployers and mocks for composing isolated protocol environments in tests.
test/helpers - Capital tests · Capital protocol unit and fork tests covering distribution, deposits, senders, receivers, and rewards.
test/capital-protocol - Builders tests · Builders protocol tests covering subnet accounting, treasury behavior, fee config, and versioned migrations.
test/builder-protocol - MOROFT tests · Unit and fork coverage for the omnichain MOR token path.
test/MOROFT.test.ts - Fork tests · Fork-based validation against mainnet-like state for protocol integrations and upgrades.
test/fork
Docs
Architecture and contract behavior documentation
- Protocol docs · Documentation for MOROFT, capital protocol, and builder protocol responsibilities and flows.
docs
Connections 24
- Core contracts → MOR OFT: shared base · Core contracts and interfaces provide the local foundation for the token implementation.
- LayerZero vendored → MOR OFT: omnichain · LayerZero libraries enable MOR cross-chain messaging and transfer behavior.
- Core contracts → Capital L1: shared base · Capital L1 contracts depend on shared interfaces, libraries, mocks, and legacy compatibility layers.
- Core contracts → Capital L2: shared base · Capital L2 receivers reuse shared interfaces and compatibility code.
- Core contracts → Builders protocol: shared base · Builder protocol contracts are built atop the shared repository libraries and interfaces.
- Capital L1 → Capital L2: cross-chain flow · L1 sender and distributor logic forward value and messages to L2 receivers.
- Deploy all → Capital deploy: orchestrates · The top-level rollout script invokes the capital deployment flow.
- Deploy all → Builders deploy: orchestrates · The top-level rollout script invokes the builders deployment flow.
- Deploy all → Token deploy: orchestrates · The top-level rollout script invokes the MOR token deployment flow.
- Deploy all → Fee deploy: orchestrates · The top-level rollout script invokes fee configuration deployment.
- Deploy all → Network config: uses config · Deployment orchestration is parameterized by network-specific config data.
- Capital deploy → Capital L1: deploys · Capital deployment scripts configure and upgrade the L1 capital subsystem.
- Capital deploy → Capital L2: deploys · Capital deployment scripts configure the L2 receiver side.
- Builders deploy → Builders protocol: deploys · Builders deployment scripts initialize and migrate the builders subsystem.
- Token deploy → MOR OFT: deploys · Token deployment scripts bootstrap the MOR omnichain token path.
- Test fixtures → Capital tests: fixtures · Reusable deployers and mocks assemble capital protocol test environments.
- Test fixtures → Builders tests: fixtures · Reusable deployers and mocks assemble builders protocol test environments.
- Test fixtures → MOROFT tests: fixtures · Reusable deployers and mocks assemble MOR token test environments.
- Fork tests → Capital L1: validates · Fork tests validate L1 capital behavior against real-chain state.
- Fork tests → Capital L2: validates · Fork tests validate cross-chain receiver behavior against real-chain state.
- Fork tests → MOR OFT: validates · Fork tests validate the MOR omnichain token path.
- Protocol docs → Capital L1: documents · Documentation covers the capital protocol contracts and flow.
- Protocol docs → Builders protocol: documents · Documentation covers the builders protocol contracts and flow.
- Protocol docs → MOR OFT: documents · Documentation covers the MOR token omnichain design.