# morpheusais/smartcontracts architecture

> Architecture diagram of the GitHub repository morpheusais/smartcontracts, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/morpheusais/smartcontracts
- Repository: https://github.com/morpheusais/smartcontracts

## Overview

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/deploy-all.sh`](https://github.com/morpheusais/smartcontracts/blob/main/deploy/deploy-all.sh) (Deploy all), [`contracts/capital-protocol`](https://github.com/morpheusais/smartcontracts/tree/main/contracts/capital-protocol) (Capital L1), [`contracts`](https://github.com/morpheusais/smartcontracts/tree/main/contracts) (MOR OFT), [`test/helpers`](https://github.com/morpheusais/smartcontracts/tree/main/test/helpers) (Test fixtures)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_contracts["Contracts"]
  node_contracts_core["Core contracts<br/>shared libs + versions"]
  node_contracts_layerzero["LayerZero vendored<br/>omnichain deps"]
  node_mor_oft["MOR OFT<br/>token omnichain"]
  node_capital_l1["Capital L1<br/>yield orchestration"]
  node_capital_l2["Capital L2<br/>cross-chain receivers"]
  node_builders_protocol["Builders protocol<br/>subnet staking"]
end

subgraph group_deploy["Deploy"]
  node_deploy_all["Deploy all<br/>rollout orchestration<br/>[deploy-all.sh]"]
  node_deploy_capital["Capital deploy<br/>capital migrations"]
  node_deploy_builders["Builders deploy<br/>builders migrations"]
  node_deploy_token["Token deploy<br/>MOR deployment"]
  node_deploy_fee["Fee deploy<br/>fee config"]
  node_deploy_data["Network config<br/>deployment config<br/>[config.json]"]
end

subgraph group_test["Tests"]
  node_test_fixtures["Test fixtures<br/>protocol deployers"]
  node_test_capital["Capital tests<br/>integration tests"]
  node_test_builders["Builders tests<br/>integration tests"]
  node_test_moroft["MOROFT tests<br/>token tests<br/>[MOROFT.test.ts]"]
  node_test_fork["Fork tests<br/>real-chain validation"]
end

subgraph group_docs["Docs"]
  node_docs_protocols["Protocol docs<br/>architecture docs"]
end

node_contracts_core -->|"shared base"| node_mor_oft
node_contracts_layerzero -->|"omnichain"| node_mor_oft
node_contracts_core -->|"shared base"| node_capital_l1
node_contracts_core -->|"shared base"| node_capital_l2
node_contracts_core -->|"shared base"| node_builders_protocol
node_capital_l1 -->|"cross-chain flow"| node_capital_l2
node_deploy_all -->|"orchestrates"| node_deploy_capital
node_deploy_all -->|"orchestrates"| node_deploy_builders
node_deploy_all -->|"orchestrates"| node_deploy_token
node_deploy_all -->|"orchestrates"| node_deploy_fee
node_deploy_all -->|"uses config"| node_deploy_data
node_deploy_capital -->|"deploys"| node_capital_l1
node_deploy_capital -->|"deploys"| node_capital_l2
node_deploy_builders -->|"deploys"| node_builders_protocol
node_deploy_token -->|"deploys"| node_mor_oft
node_test_fixtures -->|"fixtures"| node_test_capital
node_test_fixtures -->|"fixtures"| node_test_builders
node_test_fixtures -->|"fixtures"| node_test_moroft
node_test_fork -->|"validates"| node_capital_l1
node_test_fork -->|"validates"| node_capital_l2
node_test_fork -->|"validates"| node_mor_oft
node_docs_protocols -->|"documents"| node_capital_l1
node_docs_protocols -->|"documents"| node_builders_protocol
node_docs_protocols -->|"documents"| node_mor_oft

click node_contracts_core "https://github.com/morpheusais/smartcontracts/tree/main/contracts"
click node_contracts_layerzero "https://github.com/morpheusais/smartcontracts/tree/main/contracts/@layerzerolabs"
click node_mor_oft "https://github.com/morpheusais/smartcontracts/tree/main/contracts"
click node_capital_l1 "https://github.com/morpheusais/smartcontracts/tree/main/contracts/capital-protocol"
click node_capital_l2 "https://github.com/morpheusais/smartcontracts/tree/main/contracts/capital-protocol"
click node_builders_protocol "https://github.com/morpheusais/smartcontracts/tree/main/contracts/builder-protocol"
click node_deploy_all "https://github.com/morpheusais/smartcontracts/blob/main/deploy/deploy-all.sh"
click node_deploy_capital "https://github.com/morpheusais/smartcontracts/tree/main/deploy/capital-protocol"
click node_deploy_builders "https://github.com/morpheusais/smartcontracts/tree/main/deploy/builders-protocol"
click node_deploy_token "https://github.com/morpheusais/smartcontracts/tree/main/deploy/mor"
click node_deploy_fee "https://github.com/morpheusais/smartcontracts/tree/main/deploy/fee-config"
click node_deploy_data "https://github.com/morpheusais/smartcontracts/blob/main/deploy/data/config.json"
click node_test_fixtures "https://github.com/morpheusais/smartcontracts/tree/main/test/helpers"
click node_test_capital "https://github.com/morpheusais/smartcontracts/tree/main/test/capital-protocol"
click node_test_builders "https://github.com/morpheusais/smartcontracts/tree/main/test/builder-protocol"
click node_test_moroft "https://github.com/morpheusais/smartcontracts/blob/main/test/MOROFT.test.ts"
click node_test_fork "https://github.com/morpheusais/smartcontracts/tree/main/test/fork"
click node_docs_protocols "https://github.com/morpheusais/smartcontracts/tree/main/docs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_contracts_core,node_contracts_layerzero,node_mor_oft,node_capital_l1,node_capital_l2,node_builders_protocol toneBlue
class node_deploy_all,node_deploy_capital,node_deploy_builders,node_deploy_token,node_deploy_fee,node_deploy_data toneAmber
class node_test_fixtures,node_test_capital,node_test_builders,node_test_moroft,node_test_fork toneMint
class node_docs_protocols toneRose
```

## Components

### Contracts

On-chain protocol code and vendored dependencies

- [Core contracts](https://github.com/morpheusais/smartcontracts/tree/main/contracts): shared libs + versions · Shared libraries, interfaces, mocks, extensions, and legacy contract generations that support the main protocol modules. · `contracts`
- [LayerZero vendored](https://github.com/morpheusais/smartcontracts/tree/main/contracts/@layerzerolabs): omnichain deps · Vendored LayerZero OApp/OFT and messaging libraries used by the MOR token and cross-chain flows. · `contracts/@layerzerolabs`
- [MOR OFT](https://github.com/morpheusais/smartcontracts/tree/main/contracts): token omnichain · Omnichain MOR token implementation built on LayerZero OFT mechanics. · `contracts`
- [Capital L1](https://github.com/morpheusais/smartcontracts/tree/main/contracts/capital-protocol): yield orchestration · L1 capital contracts for deposit accounting, reward curves, price consumption, and cross-chain yield forwarding. · `contracts/capital-protocol`
- [Capital L2](https://github.com/morpheusais/smartcontracts/tree/main/contracts/capital-protocol): cross-chain receivers · L2 receivers for token delivery and L1 message consumption. · `contracts/capital-protocol`
- [Builders protocol](https://github.com/morpheusais/smartcontracts/tree/main/contracts/builder-protocol): subnet staking · Builder subnet staking, reward, and fee logic for the builders network. · `contracts/builder-protocol`

### Deploy

TypeScript deployment and migration flows

- [Deploy all](https://github.com/morpheusais/smartcontracts/blob/main/deploy/deploy-all.sh): rollout orchestration · Top-level shell orchestration for coordinated deployment across networks and protocol modules. · `deploy/deploy-all.sh`
- [Capital deploy](https://github.com/morpheusais/smartcontracts/tree/main/deploy/capital-protocol): capital migrations · Capital protocol deployment and upgrade flows, including testnet and mainnet versioned migrations. · `deploy/capital-protocol`
- [Builders deploy](https://github.com/morpheusais/smartcontracts/tree/main/deploy/builders-protocol): builders migrations · Builders protocol deployment, subnet initialization, and version migration flows. · `deploy/builders-protocol`
- [Token deploy](https://github.com/morpheusais/smartcontracts/tree/main/deploy/mor): MOR deployment · Deployment path for the MOR token and related bridge/bootstrap migrations. · `deploy/mor`
- [Fee deploy](https://github.com/morpheusais/smartcontracts/tree/main/deploy/fee-config): fee config · Standalone deployment flow for protocol fee configuration. · `deploy/fee-config`
- [Network config](https://github.com/morpheusais/smartcontracts/blob/main/deploy/data/config.json): deployment config · Network-specific configuration inputs used to parameterize deployment flows. · `deploy/data/config.json`

### Tests

Unit, fork, and fixture-based validation

- [Test fixtures](https://github.com/morpheusais/smartcontracts/tree/main/test/helpers): protocol deployers · Reusable deployers and mocks for composing isolated protocol environments in tests. · `test/helpers`
- [Capital tests](https://github.com/morpheusais/smartcontracts/tree/main/test/capital-protocol): integration tests · Capital protocol unit and fork tests covering distribution, deposits, senders, receivers, and rewards. · `test/capital-protocol`
- [Builders tests](https://github.com/morpheusais/smartcontracts/tree/main/test/builder-protocol): integration tests · Builders protocol tests covering subnet accounting, treasury behavior, fee config, and versioned migrations. · `test/builder-protocol`
- [MOROFT tests](https://github.com/morpheusais/smartcontracts/blob/main/test/MOROFT.test.ts): token tests · Unit and fork coverage for the omnichain MOR token path. · `test/MOROFT.test.ts`
- [Fork tests](https://github.com/morpheusais/smartcontracts/tree/main/test/fork): real-chain validation · Fork-based validation against mainnet-like state for protocol integrations and upgrades. · `test/fork`

### Docs

Architecture and contract behavior documentation

- [Protocol docs](https://github.com/morpheusais/smartcontracts/tree/main/docs): architecture docs · Documentation for MOROFT, capital protocol, and builder protocol responsibilities and flows. · `docs`

## Connections

- 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.
