diff --git a/.gitignore b/.gitignore
index 2bfbac730..0eb11aa9d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,8 +2,8 @@
/node_modules
# Production
-# /build
-# build/
+/build
+build/
# Generated files
.docusaurus
diff --git a/MakefileEks.mk b/MakefileEks.mk
index 66cb42a31..dbf947c7d 100644
--- a/MakefileEks.mk
+++ b/MakefileEks.mk
@@ -6,6 +6,7 @@ LDFLAGSSTRING +=-X main.GitDate=$(GITDATE)
LDFLAGS := -ldflags "$(LDFLAGSSTRING)"
build-bk-test-morph-test-qanet-to-morph-doc-qanet:
+ ./resolve_innerbuild.sh
source ./makefile-function.sh && MFPnpmInstall && pnpm run build:qanet
cp -rf nginx_sub_qanet.conf nginx_sub.conf
@@ -21,6 +22,7 @@ healthcheck-bk-test-morph-test-qanet-to-morph-doc-qanet:
build-bk-prod-morph-prod-mainnet-to-morph-doc:
+ ./resolve_innerbuild.sh
source ./makefile-function.sh && MFPnpmInstall && pnpm run build:mainnet
cp -rf nginx_sub_mainnet.conf nginx_sub.conf
diff --git a/build/.nojekyll b/build/.nojekyll
deleted file mode 100644
index e69de29bb..000000000
diff --git a/build/2-morph-staking-system-design.md b/build/2-morph-staking-system-design.md
deleted file mode 100644
index 1bbe9dfec..000000000
--- a/build/2-morph-staking-system-design.md
+++ /dev/null
@@ -1,217 +0,0 @@
----
-title: Morph's Staking System Design
-lang: en-US
-keywords: [morph,ethereum,rollup,layer2,validity proof,optimistic zk-rollup]
-description: Upgrade your blockchain experience with Morph - the secure decentralized, cost0efficient, and high-performing optimistic zk-rollup solution. Try it now!
----
-
-# What is Morph Staking System?
-
-:::tip
-Currently the Staking System is in beta testing phase, the design described in this document will change as the testing process progresses, and does not represent the final experience on the Mainnet.
-:::
-
-Morph Staking is a complete economic and engineering system built upon the decentralized sequencer network to ensure the operation and security of the network.
-
-It can be divided into 2 parts:
-
-**ETH Staking**
-
-On Ethereum, potential sequencers are required to stake ETH in the layer 1 staking contract to become a staker first.
-
-The ETH staking serves to increase the cost of malicious behavior by sequencers.
-
-In case of confirmed dishonesty or negligence by a sequencer, the staked ETH will be slashed. The required ETH staking amount is immutable.
-
-**Morph token Staking**
-
-Morph token is the governance token of Morph (Gas token is ETH). In the staking system, it will play the following roles:
-
-Staker is elected as the sequencer according to the amount of Morph tokens that token holders have delegated to them. So stakers need to attract Morph token holders to delegate their tokens to them. Only sequencers can receive network rewards.
-Morph token holders can delegate stake their tokens to any stakers, which will determine whether stakers can be selected as sequencer. Sequencers receive rewards from the inflation of the Morph token based on the sequencer’s contribution, and delegators share a portion of the rewards based on their delegation amount.
-
-## Roles within the Staking System:
-
-1. Staker (Sequencer Candidate): Anyone (required in the whitelist in the early stage) can stake ETH to L1 staking contract and become a staker. Only stakers can join the sequencer election.
-2. Sequencer: Sequencers are able to perform the sequencer tasks and get reward from it. Sequencers are selected according to the delegation amount of Morph tokens.
-3. Delegator: Morph token holders can delegate stake their tokens to any of the stakers. Delegators can share the rewards gained by delegated sequencer based on the delegation amounts.
-
-## Details of sequencer set election:
-
-The determination of the sequencer set will be based on two points:
-
-1. Sequencers must have staked a fixed amount of ETH in Layer 1 staking contract.
-2. Assuming the maximum size of the sequencer set is X, based on the delegation amount of Morph token, select up to X sequencers from all valid candidates as sequencer set.
-
-
-The sequencer set will be updated in real-time based on the above principles.
-
-When there's a new MorphToken stake, the L2 staking contract will check if this would cause the sequencer set to change, and update the sequencer set if needed.
-
-Joining the sequencer set means that all sequencers will have the right to participate in the current network operations to earn rewards, while also bearing the responsibility of maintaining the network's efficient and normal operation.
-
-In practice, each sequencer, regardless of the delegation amount, has the same weight.
-
-Sequencers can exit at any time. They need to submit an exit request on Layer 1 staking contract, then enter a lock-up period. After Layer 2 contracts complete the exit process and reach the unlocking block height, they are unlocked and could claim the staked ETH.
-
-
-## Rewards & Slash
-
-### Rewards
-
-There are 3 potential rewards for sequencers within the Morph ecosystem.
-
-**L2 MorphToken staking rewards.**
-
-The Morph token is inflationary that increases 6% of the initial max total supply each year as the L2 Morph token staking rewards.
-
-These 6% will be distributed everyday (one day is an epoch) to all the current running sequencers.
-
-Sequencers will take commission first and distribute the rest to the delegators based on their delegation amount.
-
-**L2 Gas Income:**
-
-Sequencers take ETH from layer 2 users (Layer2 income) and spend ETH to submit batches to layer1 (Layer1 cost).
-
-If the Layer1 cost is less than Layer2 income, the remaining value theoretically becomes the profit of Layer 2.
-
-At the very beginning, the network collects all the Layer2 incomes and pays ETH to sequencers to cover their Layer 1 cost. In the future, we’ll have a more detailed plan about how this part of the funds will be utilized.
-
-**ETH Re-staking yield:**
-
-To improve capital efficiency, we plan to leverage staker’s ETH deposit to generate yield in restaking products, and the yield will still be allocated to stakers.
-
-
-
-#### How to decide each sequencer’s MorphToken rewards?
-
-This is based on the block production records.
-
-In each epoch, the total reward received by each sequencer and their delegators is calculated as follows:
-
-**sequencer_reward = (sequencer_produced_block / total_produced_blocks) * total_morph_token_inflation**
-
-
-The sequencer rewards are eventually distributed to delegators (although sequencers can be their own delegators too). Sequencer can set a commission rate to take a share from it and the rate is adjustable.
-
-**sequencer_commission = sequencer_reward * commission_rate**
-
-
-The reward each delegator of this sequencer receives is the remaining portion multiplied by the percentage of their staked amount:
-
-**delegator_reward = (sequencer_reward - sequencer_commission) * delegation_amount / total_delegation_amount**
-
-The user’s delegation rewards will be calculated starting from the next epoch after the user stakes.
-
-**Example:**
-
-If today’s (this epoch’s) total Morph Inflation is 100, and there are 100 blocks produced in this epoch.
-
-Sequencer A produced 10 blocks within this epoch, so he will receive:
-
-**sequencer_reward = (sequencer_produced_block / total_produced_blocks) * total_morph_token_inflation = (10/100) * 100 = 10 MorphToken.**
-
-If sequencer’s commission rate is 5%
-
-**sequencer_commission = sequencer_reward * commission_rate = 10 * 0.05 = 5 MorphToken**
-
-If one delegator staked 100 MorphToken and then there are a total 1000 MorphToken delegated to the sequencer.
-
-**delegator_reward = (sequencer_reward - sequencer_commission) * delegation_amount / total_delegation_amount = (100 - 5) * (100/1000) = 9.5 MorphToken**
-
-Ideally, since the weights for each sequencer is the same, each sequencer will be able to produce the same amount of blocks within a certain epoch. Thus their rewards should be the same.
-
-However, if the sequencer failed to perform their duties, the block production will be much lower thus their rewards would be much lower too.
-
-
-### Slash
-
-Based on the optimistic zkEVM design, there will be validators constantly verifying the batch submitted by sequencers, and if they think sequencers committed fraud, validators will start a challenge through the L1 rollup contract.
-
-[Read more about the challenge here:](../3-optimistic-zkevm.md)
-
-To prevent fraudulent behavior by Sequencers from affecting network security, the following rules need are established:
-
-- Validators will challenge a fixed batch, and all sequencers who signed that batch will collectively be challenged.
-- When a sequencer takes on the role of batch submitter, repeated instances of timeouts accumulating to a certain extent will result in a deduction of rewards or removal from the sequencer set (not fully implemented yet).
-- Sequencers with long periods that have not produced blocks will be removed from the sequencer set (not fully implemented yet).
-
-:::tip
-The submitter rotation and submission timeout is part of decentralized rollup design, you can read the details [here](../general-protocol-design/1-rollup.md).
-:::
-
-For the reward and slash functionalities, we have 2 contracts:
-
-- L2 Record Contract: The off-chain data affecting rewards and penalties will be collected and recorded in the L2 Record contract through an Oracle, primarily consisting of rollup data and Block data.
-- L2 Distribute Contract: Sequencers and Delegator will manually claim rewards based on the Record.
-
-## Governance:
-
-We have a governance contract right now that decides some of the network parameters. Currently, only sequencers can create proposals and vote.
-
-In the next phase of the roadmap, we are planning to build a complete governance system that allows all Morph token holders to decide every aspect of the network.
-
-## Major Process
-
-### Staking & Sequencer Selection
-
-Morph token staking will be divided into 2 stages based on the network status:
-
-- Phase 1: Morph token inflation and staking rewards not started yet.
-Sequencer elections will be FCFS at the beginning, but delegate stake is allowed. No morph token rewards since there is no new token generation yet.
-
-- Phase 2: Morph token inflation and staking rewards is started.
-The sequencer election will officially start and based on the delegation amount of Morph token, the rewards will start to be distributed too.
-
-How is the sequencer set generated?
-
-1. `L1` Staking Contract: Add potential sequencers to the whitelist.
-2. `L1` Staking Contract: Potential sequencer will be able to register and stake eth on Ethereum to become eligible for sequencer election (become staker).
-3. An `add staker` message will be sent as a cross-layer message from L1 staking contract to L2 staking contract.
-4. `L2` Staking Contract: Will update stakers with the message synced.
-5. `L2` Staking Contract: Users will be able to delegate/undelegate stake MorphToken to a staker.
-6. `L2` Sequencer Contract: L2 staking contract will update the sequencer set by calling L2 sequencer contact based on the ranking of the Morph token delegation amount, the top staker will be elected as sequencer.
-
-### Sequencer network consensus & Verification on Layer 1
-
-- Every submitted batch requires the BLS signature of more than 2/3 of the sequencers within the sequencer set to be accepted by the L1 rollup contract.
-
-Notice: Currently, the BLS 12-381 signature pre-compiled contract has not been implemented on Ethereum. Therefore, the L1 rollup contract cannot verify whether the batch is signed by the L2 sequencer set.
-Until this functionality is available, the rollup contracts only allow batch submission from stakers included in the whitelist. This measure is in place to enable us to slash the ETH deposit in case of fraudulent submissions. After signature verification is implemented, the submitter will be permissionless and the sequencers which signed the fraudulent batch will be slashed instead of the submitter.
-
-
-1. `L1` Rollup Contract: Batch submitter commits the batch to rollup contract.
-2. `L1` Rollup Contract: Rollup contract verifies the batch’s BLS signature and compares it with the sequencer set sync from L1 staking contract. It will only accept the batch if the verification passed.
-
-### Slash for Sequencers
-
-#### What happens if validators successfully challenge sequencers?
-
-- Sequencer will be slashed all staked ETH and removed from sequencer set if challenger succeeds.
-- Even if get proven fraud by multiple challenges, each sequencer will only be slashed once.
-- The challenger reward for a successful challenge is a fixed proportion of the staking amount.
-- If the slash makes all the sequencers go down, then the L2 will stop running. We can restart by upgrading the L1 staking contract, reset stakers and sequencer sets. This does not affect the Layer 2 state as no transactions will be processed because of this.
-
-Process:
-
-1. `L1` Staking Contract: Slash staked ETH of sequencers who signed the fraud batch and remove them from sequencer set.
-2. `L1` Staking Contract: Distribute validator rewards.
-3. A `remove staker` message will be sent as a cross-layer message from L1 staking contract to L2 staking contract.
-4. `L2`Staking Contract: Update sequencer set.
-
-### Delegation Stake
-
-1. `L2` Staking Contract: Staker set delegation commission rate by their own will.
-2. `L2` Oracle: Upload sequencers work records (block production records, submitter work records, expect work records) on the epoch basis (an epoch is a day).
-3. `L2` MorphToken Contract: Mint MorphToken (inflation) as delegation reward and sent to L2 distributor contract.
-4. `L2` Staking Contract: Users claim delegation reward, sequencers claim commission.
-
-### Staker/Sequencer exit
-
-The exit lock period should be long enough to ensure that stakers and sequencers in L2 have been updated and greater than the challenge period of sequencer’s last produced block (if staker is also sequencer).
-
-
-1. `L1` Staking Contract: Stakers apply to exit, the stake ETH is locked to enter the lock period.
-2. A `remove staker` message will be sent as a cross-layer message from L1 staking contract to L2 staking contract.
-3. `L2` Staking Contract: Received the message, remove staker, and sequencers (if the staker is also sequencer).
-4. `L1` Staking Contract: Withdraw allowed until reach unlock block height,remove staker info after claiming.
\ No newline at end of file
diff --git a/build/404.html b/build/404.html
deleted file mode 100644
index 8d6516462..000000000
--- a/build/404.html
+++ /dev/null
@@ -1,17 +0,0 @@
-
-
-
-
-
-Page Not Found | Morph docs – The Optimistic zkEVM Scaling Solution docs
-
-
-
-
-
-
-
-
-
Morph uses a hybrid rollup model called "Optimistic zkEVM & RVP". This combines the strengths of both zkRollups and Optimistic Rollups, optimizing for efficiency, cost, and speed. This unique approach places Morph at the cutting edge of rollup technology.
State Verification: The Optimistic zkEVM & RVP method enhances efficiency by combining zkRollups and Optimistic Rollups.
-
Efficiency and Cost Reduction: Morph ensures fast transaction execution and cost-effectiveness while maintaining decentralization.
-
Decentralized Sequencer Network: This pioneering network setup addresses security concerns and ensures robustness at a Layer 1 level.
-
Modular Architecture: Morph’s adaptable and composable architecture fosters a flexible and interactive ecosystem.
-
As a Solidity Developer, Will I Notice Differences Deploying on Morph Compared to Ethereum?
-
Deploying on Morph is very similar to deploying on Ethereum, thanks to its EVM compatibility. Ethereum applications can be migrated to Morph with minimal adjustments. For more detailed guidance, check out the Development Guides section.
-
The L2 gas price is too high to execute transactions or deploy contracts, what should i do?
-
The L2 Gas Price you obtained from external resources (eg. RPC) is typically derived from the average or median of confirmed transactions over a certain period. This figure reflects the recommended settings to ensure your transaction gets confirmed, rather than representing the most cost-effective value.
-
In some cases, certain users may intentionally raise the priority fee (hence the total gas fee) to earn more campaign points, resulting in abnormally high Gas Prices. We recommend that you can reduce your transaction costs by manually setting the L2 Gas Price.
-
Currently, Morph's L2 Base Fee is 0.001 gwei, and as long as the number of transactions per block does not reach the limit, you only need to pay the Base Fee to ensure your transaction confirmation, without needing to pay an excess Priority Fee.
-
Here is a transaction example that only pays the L2 Base Fee and got confirmed:
How long should I wait for my funds to withdraw from Morph?
-
Currently, the Morph mainnet has a 48-hour (2 days) challenge window. This means that if you are using our canonical bridge, you need to wait 48 hours (2 days) to receive your funds. There are several third-party bridges that offer a faster withdrawal experience by using a liquidity pool mechanism.
Same like Ethereum mainnet and any other EIP 1559 chains. If your transaction is pending and not confirmed, you can replace it with a new one that has a higher gas price. This involves sending the same transaction again but with an incrementally higher gas price, using the same nonce as the original.
-
A lot of the wallet have built in features to help you do this.
For the testnet, if the priority fee you paid is too low, less than 0.01 gwei, your transaction will not be processed. This is to prevent spam transactions from impacting the whole network. If you encounter this situation, please accelerate your transaction by providing a higher priority fee that meets the requirements.
-
For the mainnet, this is usually because each block is currently full, so you need to provide a more competitive priority fee to ensure your transaction is confirmed.
-
Additionally, if your previous transaction has not yet been confirmed, your newly submitted transaction will wait for the previous transaction to be fully confirmed.
Optimistic rollups are a Layer 2 scaling solution for blockchains that enhance transaction throughput and reduce costs by assuming transactions are valid and only verifying them if a challenge is raised. This method relies on a challenge period during which validators can dispute transactions they believe to be incorrect. If no disputes are raised, the transactions are considered final. Optimistic rollups significantly improve scalability while maintaining security, making them an efficient solution for handling a higher volume of transactions on blockchain networks.
ZK rollups, or zero-knowledge rollups, are a Layer 2 scaling solution that uses cryptographic proofs to verify the validity of transactions off-chain before bundling them and submitting a proof to the main blockchain. Each batch of transactions is accompanied by a zero-knowledge proof, which ensures that all transactions within the batch are valid without revealing the underlying data. This method provides immediate finality and high security, as the main chain only needs to verify the proof rather than each individual transaction, significantly reducing the computational load and enhancing scalability.
Sequencers are specialized nodes responsible for ordering and bundling transactions in Layer 2 scaling solutions like rollups. They play a crucial role in determining the sequence of transactions, creating blocks, and periodically committing these blocks to the main blockchain. In decentralized systems, multiple sequencers work together to enhance security and prevent single points of failure. By ensuring transactions are processed efficiently and securely, sequencers help maintain the integrity and performance of Layer 2 networks.
Fraud proof is a mechanism used in blockchain scaling solutions like optimistic rollups to ensure transaction validity. When a sequencer submits a batch of transactions, they are assumed to be valid unless contested. During a designated challenge period, any validator or network participant can submit a fraud proof if they detect an incorrect transaction. This proof involves verifying the transaction data and demonstrating the error to the main blockchain. If the fraud proof is validated, the incorrect transaction is rejected, ensuring the integrity and security of the network while minimizing computational costs.
Validity proof is a cryptographic method used to ensure that transactions within a rollup are correct before they are finalized on the main blockchain. In systems like ZK rollups, each batch of transactions is accompanied by a validity proof that verifies the correctness of all transactions within the batch. This approach enhances security and efficiency by eliminating the need for individual transaction verification on the main chain, providing immediate finality and reducing computational overhead.
zkEVM, or Zero-Knowledge Ethereum Virtual Machine, is an advanced implementation of the Ethereum Virtual Machine that integrates zero-knowledge proofs to enhance scalability and security. By using zk proofs, zkEVM allows for the validation of transactions off-chain, ensuring that only valid state transitions are submitted to the main chain. This method provides high throughput and lower transaction costs while maintaining the security and trustlessness of Ethereum.
BLS (Boneh-Lynn-Shacham) signatures are a cryptographic technique used to aggregate multiple signatures into a single compact signature. This is particularly useful in blockchain networks for reducing the data size and improving the efficiency of transaction verification. BLS signatures enable multiple validators to sign a message collectively, resulting in a single signature that can be verified quickly and cost-effectively, enhancing the overall scalability of the network.
Data availability refers to the assurance that all necessary data for verifying blockchain transactions is accessible and retrievable. In the context of rollups, ensuring data availability is crucial for maintaining the integrity and security of off-chain transactions. It guarantees that anyone can download and verify the data used in rollup proofs, preventing scenarios where transactions are finalized without the possibility of verification.
EIP-4844, also known as Proto-Danksharding, is an Ethereum Improvement Proposal aimed at introducing a new type of transaction that reduces data costs and improves scalability. It involves adding a new transaction format that can efficiently handle large amounts of data, laying the groundwork for future sharding implementations. This proposal enhances the network's ability to manage data more effectively, contributing to overall improvements in throughput and cost-efficiency.
This overview offers a concise introduction to Morph’s rollup technology stack. For an in-depth understanding, please refer to the "How Morph Works" section of our documentation.
Traditionally, the concept of modularity has been applied to Layer 1 blockchains, segmenting them into distinct layers. At Morph, we've extended this modular philosophy to Layer 2, building our platform around this principle.
-
In a typical Layer 1 blockchain, the architecture consists of four major layers:
-
-
Consensus: The mechanism through which network agreement is achieved.
-
Execution: Where transaction processing and smart contract operations occur.
-
Settlement: The process of finalizing transactions.
-
Data Availability: Ensuring that necessary information is accessible for validation.
-
-
In the context of Layer 2, Morph reinterprets these layers with unique functionalities:
-
-
Consensus and Execution via Decentralized Sequencer Network: At Morph, these functions are integrated and handled by our decentralized sequencer network. Sequencers orchestrate, process, and achieve consensus on Layer 2 transactions, forming the primary interface for user interactions.
-
-
-
-
Settlement with Optimistic zkEVM: Settlement in Morph refers to the finalization of Layer 2 transactions at the Ethereum level. It involves the crucial step of validating Layer 2 states. Morph employs the optimistic zkEVM for this purpose, a hybrid approach blending the best of optimistic rollups and zk-rollups. Layer 2 states will be eventually finalized by a significantly shorter challenge period or if gets challenged, a corresponding zk-proof.
-
-
-
-
Data Availability through 'Rollup' Process: This entails transferring essential Layer 2 data to Ethereum. In Morph, this is achieved through the 'Rollup' process, where a batch submitter compiles blocks into batches and submits them as Layer 1 transactions on Ethereum.
Morph’s architecture is further defined by five pivotal roles: Sequencers, Validators, Nodes, Provers, and Layer 1 (Ethereum). Each role carries specific responsibilities and utilizes distinct components to fulfill its function, contributing to the seamless operation of the network.
-
For a deeper understanding of Morph’s architecture, please visit our comprehensive Developer Docs.
We place the highest priority on security and are committed to providing users with a safe and trustworthy environment. To achieve this, we’ve implemented multiple measures, including making our codebase open-source, engaging leading third-party firms for audits, and continuously improving our systems to uphold the highest standards of transparency and security. Below are some specific efforts we’ve undertaken:
Additionally, we enlisted the renowned Trail of Bits team to conduct an in-depth audit of our codebase, including a review of implemented fixes. The full report is accessible.
The above audit reports cover the entirety of our codebase, including the bridge contract, ensuring that all critical components have undergone rigorous security assessments.
-
We firmly believe that transparency and security are the cornerstones of trust. We will continue to collaborate with the community and professional organizations to elevate our security standards and provide users with peace of mind. If you have any questions or suggestions, feel free to reach out to us at any time!
Morph is redefining the blockchain landscape with a clear focus on the consumer. Our vision is rooted in the belief that blockchain technology should be an accessible, practical tool for daily life, rather than a complex concept reserved for experts. We aim to transform how individuals interact with blockchain technology, making it as integral and user-friendly as any essential service in the digital age.
Our mission is to build an ecosystem of on-chain consumer applications on a completely decentralized infrastructure. Morph was created as a more approachable and practical blockchain solution in response to the gap in existing Layer 2 offerings – a lack of focus on the end-user experience and practicality.
The inspiration behind Morph is a fusion of dreams and precision. Our platform is named after Morpheus, the Greek god of dreams, symbolizing our ability to influence both the commonplace and the extraordinary. Morph also draws on the mathematical principle of morphology, representing transformations that maintain structure and integrity. The combination of these concepts represents our ability to bring revolutionary blockchain applications that focus on improving everyday life with precision and reliability.
At Morph, our commitment extends beyond technology. We prioritize:
-
-
Consumer-Centric Innovation: Focusing on the needs and experiences of users, ensuring that our platform is intuitive, efficient, and beneficial for everyday use.
-
Transparency and Trust: Building a community grounded in openness and mutual trust, where every step we take is communicated clearly and honestly.
-
Collaborative Ecosystem: Encouraging active participation and feedback from our community, ensuring that Morph evolves in alignment with the needs and demands of its users.
Welcome to Morph, a blockchain for consumers. At the core of Morph is a revolutionary approach to Ethereum Layer 2 scalability, harnessing the power of rollup technology.
-
Our platform is uniquely designed to enhance the blockchain experience, making it more accessible, efficient, and user-friendly for both developers and consumers. We achieve these innovations through a unique combination of cutting-edge technologies.
Given that our platform is built on the philosophy of consumer-centric innovation, we believe blockchain technology has the transformative power to enhance users’ daily lives. To accomplish this vision, our infrastructure has three core technological components that function as the foundation of a consumer blockchain.
Morph’s distribution of the sequencing role eliminates single points of failure, reduces transaction censorship, and prevents monopolies over Miner Extractable Value (MEV). Building on Morph means guaranteed high availability, resilience, and fairness in transaction processing.
Morph’s Optimistic zkEVM Integration combines the efficiency of optimistic rollups with the security of zero-knowledge proofs, using a novel method called Responsive Validity Proof (RVP). RVP reduces costs and shortens withdrawal periods while maintaining high security, enabling robust applications that don’t compromise on performance or security.
Morph's architecture is divided into three modules: Sequencer Network for consensus and execution, Optimistic zkEVM for state verification, and Rollup for data availability. Developers can build and maintain applications more efficiently, ensuring each component can be upgraded independently without disrupting the entire system.
-
Before you dive into a deeper exploration of our technology, understanding our Vision and Mission will offer a better idea of why Morph stands out in the industry.
Morph's Decentralized Sequencer Network is designed to enhance the security and reliability of the blockchain. Unlike traditional Layer 2 solutions that rely on a centralized sequencer, Morph employs a network of decentralized sequencers. This setup ensures that no single entity has control over the transaction sequencing process, thereby eliminating the risk of a single point of failure. If one sequencer fails or acts maliciously, the others can continue processing transactions, maintaining the system's integrity and uptime. This decentralization also prevents transaction censorship and ensures that no single entity can monopolize Miner Extractable Value (MEV), creating a fairer environment for all users.
-
This collaborative approach not only increases security but also improves the overall efficiency and reliability of the transaction processing system, making Morph a robust and resilient Layer 2 solution.
Optimistic and Zero-Knowledge (ZK) rollups are two distinct approaches to scaling blockchain transactions on layer 2. Optimistic rollups simply assume all transactions are valid when submitting a batch for settlement on Ethereum. However, the validity of any transaction can be contested by entities known as challengers, by submitting proof of fraudulent activity. If the fraud-proof is successful, the incorrect transaction is rejected, ensuring security but at the cost of some potential delays and high gas fees associated with the challenge process.
-
ZK rollups, on the other hand, use cryptographic proofs to verify the validity of transactions before these are submitted for settlement. All batches have their own ZK proof, allowing quick verification on the main chain without needing to review all the data associated with each transaction (hence “zero-knowledge”). This offers immediate finality with higher security, but generating these proofs is computationally intensive and costly.
-
Morph’s hybrid rollup combines the best of these two approaches. Initially, the system operates optimistically, assuming transactions are valid to allow for quick processing and low costs. When a transaction is contested within Morph’s challenge window, it’s the sequencer that is required to produce a ZK proof to validate the transaction. We call this approach Responsive Validity Proof (RVP). It comes with the following improvements:
-
-
Efficiency and Speed: A typical 7-day challenge window can be shortened to 1-3 days (a challenger no longer needs the extra time to identify malicious submissions, create a proof, and engage in multiple rounds of challenge procedures).
-
Reduced Costs: Employing ZK-proofs means that only minimal transaction information is retained, thereby significantly reducing the cost of L2 submissions. When no challenges arise, the cost of ZK-proof submission and verification can be ignored. RVP is therefore more cost-effective than both optimistic and ZK rollups.
At its core, Morph is constructed using a sophisticated modular design architecture. The platform is organized into three functional modules (Sequencer Network, Rollup, Optimistic zk-EVM), each defined by distinct roles that collaborate in various configurations to meet diverse requirements. Each role within these modules operates its specific components, maintaining functional independence. This modular structure not only fosters flexibility and adaptability but also bolsters the composability of the system. It enables an efficient and interactive ecosystem, supporting the varied operational needs of our platform.
We’re thrilled to have you here, exploring the world of Morph. If you’re a developer looking for technical documentation, head over to our For Developers section. But if you’re here to understand what Morph is all about, you’re in the right place!
Morph is a cutting-edge Layer 2 solution built on Ethereum, combining the best of optimistic rollups and zk technology. This makes us scalable, secure, and perfect for everyday applications. Our mission is to build the first blockchain for consumers, where user-friendly applications integrate seamlessly into everyday life, becoming indispensable utilities. We prioritize enabling blockchain applications that enhance daily experiences over chasing trivial technical milestones. Our focus is on creating meaningful, practical solutions that transform blockchain technology into core aspects of daily life
To help you navigate through our resources, here’s a quick guide:
-
Introductory Concepts: Get a general understanding of Morph, including what makes it unique, our vision and mission, key concepts, and a look at our roadmap. This section will help you grasp the basics and understand the foundation of Morph.
Step-by-Step Guides: Follow these practical tutorials for setting up your wallet, using the faucet, bridging assets, and exploring the Morph ecosystem. These guides are perfect for hands-on learning and getting started with Morph.
Links and Tools: Access useful tools such as the Morph Holesky Explorer and the official bridge. This section provides all the necessary links and resources to interact with and explore the Morph network effectively.
We believe in building a vibrant community around Morph. Join us on Discord to engage with other users and follow us on Twitter to stay updated with our latest news and developments.
As a developer keen on harnessing the innovative capabilities of the Morph network, your journey begins in the "Build on Morph" section of our documentation. Here, you'll find all the resources you need – from comprehensive guides and tutorials to practical examples. These materials are designed to elucidate the core concepts and features of Morph, enabling you to integrate with our APIs, deploy sophisticated smart contracts, and utilize an array of tools and libraries. The "Build on Morph" guide is your gateway to crafting powerful, decentralized applications that leverage the full potential of our network.
If you're eager to explore the possibilities within the Morph network, the "Quick Start" section in our documentation is your ideal starting point. Tailored for ease of understanding, this guide walks you through the essentials – from setting up your wallet to engaging in transactions on the network. It's designed to introduce you to the world of asset transfers, decentralized finance, and the diverse range of dApps available on Morph. Follow the "Quick Start" guide for a smooth, user-friendly introduction to leveraging Morph's functionalities in your everyday activities.
-
For Researchers: Unraveling The Technical Depth Of Morph
-
For those intrigued by the technical intricacies of the Morph network, the "How Morph Works" section offers an in-depth exploration of its underlying architecture and mechanisms. This comprehensive resource is rich in technical details, providing an extensive understanding of Morph's innovative features and foundational principles. Whether you're delving into research or seeking a thorough grasp of blockchain technology, this section unveils the nuances and sophisticated engineering that define the Morph network.
-
No matter your background – developer, user, or researcher – our documentation is structured to offer you a customized pathway into the Morph ecosystem. Each guide is designed to help you leverage and understand our state-of-the-art technology and features, ensuring a rewarding experience on the Morph network.
The Gateway Router allows ETH and ERC20 token bridging from L1 to L2 using the depositETH and depositERC20 functions respectively. It is a permissionless bridge deployed on L1. Notice that ERC20 tokens will have a different address on L2, you can use the getL2ERC20Address function to query the new address.
-
tip
depositETH and depositERC20 are payable functions, the amount of ETH sent to these functions will be used
-to pay for L2 fees. If the amount is not enough, the transaction will not be sent. All excess ETH will be sent back to
-the sender. 0.00001 ETH should be more than enough to process a token deposit.
-
When bridging ERC20 tokens, you don’t have to worry about selecting the right Gateway. This is because the L1GatewayRouter will choose the correct underlying entry point to send the message:
-
-
L1StandardERC20Gateway: This Gateway permits any ERC20 deposit and will be selected as the default by the L1GatewayRouter for an ERC20 token that doesn’t need custom logic on L2. On the very first token bridging, a new token will be created on L2 that implements the MorphStandardERC20. To bridge a token, call the depositERC20 function on the L1GatewayRouter.
-
-
All Gateway contracts will form the message and send it to the L1CrossDomainMessenger which can send arbitrary messages to L2. The L1CrossDomainMessenger passes the message to the L1MessageQueueWithGasPriceOracle. Any user can send messages directly to the Messenger to execute arbitrary data on L2.
-
This means they can execute any function on L2 from a transaction made on L1 via the bridge. Although an application could directly pass messages to existing token contracts, the Gateway abstracts the specifics and simplifies making transfers and calls.
-
When a new block gets created on L1, the Sequencer will detect the message on the L1MessageQueue, and submit the transaction to the L2 via the L2 node. Finally, the L2 node will pass the transaction to the L2CrossDomainMessenger contract for execution on L2.
The L2 Gateway is very similar to the L1 Gateway. We can withdraw ETH and ERC20 tokens back to L1 using the withdrawETH and withdrawERC20 functions. The contract address is deployed on L2. We use the getL1ERC20Address to retrieve the token address on L1.
-
tip
withdrawETH and withdrawERC20 are payable functions, and the amount of ETH sent to these functions will be used to pay for L1 fees. If the amount is not enough, the transaction will not be sent. All excess ETH will be sent back to the sender. Fees will depend on L1 activity but 0.005 ETH should be enough to process a token withdrawal.
-
tip
Ensure transactions won’t revert on L1 while sending from L2 There is no way to recover bridged ETH, tokens, or NFTs if your transaction reverts on L1. All assets are burned on Morph when the transaction is sent, and it's impossible to mint them again.
Besides starting a withdrawal request on Morph, there is one additional step to do. You need to finalize your withdrawal on Ethereum.
-
This is because of Morph's optimistic zkEVM design, you can read the details here:
-
To do this, first you need to make sure:
-
-
The batch containing the withdraw transactions has passed the challenge period and is marked as finalized (meaning in the Rollupcontract, withdrawalRoots[batchDataStore[_batchIndex].withdrawalRoot] = true).
-
-
Once confirmed, you can call our backend services interface:
-
/getProof?nonce=withdraw.index
-
to obtain all the information you need to finalize your withdraw, which include:
-
-
Index: The position of the withdrawal transaction in the withdraw tree, or rank of your transaction among all the L2->L1 transactions.
-
Leaf: The hash value of your withdraw transaction that stored in the tree.
-
Proof: The merkel proof of your withdraw transaction.
-
Root: The withdraw tree root.
-
-
you need to use the proveAndRelayMessage function of the L1CrossDomainMessenger contract.
-
After obtaining the above information, the finalization of the withdraw operation can be carried out by calling L1CrossDomainMessenger.proveAndRelayMessage().
_from, _to, _value, _nonce, and _message are the original content of the withdraw transaction, which can be obtained from the Event SentMessage included in the transaction initiated by the L2 layer withdraw.
-
_withdrawalProof and _withdrawalRoot can be obtained from the aforementioned backend API interface.
-
Use the SDK
You can also try our SDK to interact with the bridge system by referring to our SDK Doc.
Currently, our canonical bridge only supports certain pre-defined tokens to be bridged. If you want to bridge your own tokens, you need to manually add the token, and here is how to do it.
-
Add Tokens to the gateway through Morph Bridge Frontend
-
The easiest way to support your token is to manually add it on our canonical bridge frontend, you can simply do it with the following steps:
-
-
Click the token selection button on Morph Holesky Bridge
-
-
-
-
Input & Confirm your desire Ethereum token contract address under the custom token section
-
-
-
-
Get the Layer 2 token contract address and confirm it.
-
-
-
-
Now it is supported and you and other users can start to bridge it!
By adding your token to the gateway, you and other users can bridge the token by inputting the token address.You need to raise a PR to our bridge repo if you want your token shown on the bridge frontend token list.
Developing on Morph is as straightforward as developing on Ethereum.
-
To deploy contracts onto a MorphL2 chain, simply set the RPC endpoint of your target MorphL2 chain and deploy using your preferred Ethereum development framework:
To start building on Morph, you may need some testnet ETH. Use a faucet to acquire holesky Ether, then bridge the test Ethereum Ether to the Morph testnet.
-
Each faucet has its own rules and requirements, so you may need to try a few before finding one that works for you.
We have our own website faucet that can claim ETH & USDT for you initial usage.
-
Morph also offers a Discord faucet to obtain Morph Holesky USDT & Morph Holesky ETH.
-
Once you receive ETH on Holesky, you should see it in your wallet on the Holesky Network. It may take a few seconds for them to appear, but you can check the status by looking for a transaction to your address on a Holesky Block Explorer.
To notice, we have set a rate limit for the public RPC access, currently 600 requests per minute per IP.
-
If you need higher tps, please contact our team for private RPC access. You can also use our partner quicknode or tenderly to create your own private RPC.
For Ethereum Layer2, there are 2 part of fees: L1 fee and L2 fee.
-
For L2 fee, Morph currently using the EIP-1559 mechanism for transaction fees same as Ethereum mainnet. Each transaction will have a base fee and a priority fee. The base fee is set to 0.001 Gwei. If the block transaction limit (100 per block) is not reached, only pay base fee is enough.
-
tip
Please note we have a lowest L2 priority fee setting (0.01 gwei) for testnet, this is in order to prevent spams. For mainnet, we are able process transaction without priority fee.
-
Morph currently produce 1 block per second for non-empty block, if there is no new transaction, we will produce 1 empty block every 5 seconds.
-
Each block can have 100 transactions maximum and we will keep raising the limit.
Transaction fees on Morph work similarly to fees on Ethereum. However, Layer 2 introduces some unique aspects. Morph's optimistic zkEVM makes these differences easy to understand and even easier to handle.
-
This page includes the formula for calculating the gas cost of transactions on Morph.
-There are two kinds of costs for transactions on Morph: the L2 execution fee and the L1 data/security fee.
Like Ethereum, transactions on Morph incur gas costs for computation and storage usage.
-
Every L2 transaction will pay some execution fee, equal to the amount of gas used multiplied by the gas price of the transaction.
-
Morph supports EIP-1559 transaction type. The EIP-1559 pricing model, which comprises a base fee and a priority fee, contributes to a more predictable and stable transaction fee.
Morph transactions are also published to Ethereum, crucial to Morph’s security as it ensures all data needed to verify Morph's state is always publicly available on Ethereum.
-
Users must pay for the cost of submitting their transactions to Ethereum, known as the L1 data fee. This fee typically represents most of the total cost of a transaction on Morph.
commitScalar: a factor used to measure the gas cost for data commitment
-
l1BlobBaseFee: the blobBaseFee on L1
-
blobScalar: a factor used to measure the gas cost for one transaction to be stored in EIP-4844 blob
-
-
tip
You can read the parameter values from the GasPrice oracle contract. Morph has pre-deployed GasPriceOracle, accessible on Morph mainnet at GasPriceOracle.
You can utilize the pre-deployed L1GasPriceOracle at 0x530000000000000000000000000000000000000f. It offers a getL1Fee method to estimate the L1 data fee for the raw data of a given transaction.
Once the sequencer has processed a transaction, a user's L1 fee is secured, and any fluctuations will not impact what a user pays.
Due to Morph's ~1s block time, any changes in L1 gas between a transaction's submission and its inclusion in a block should be minimal. The sequencer will account for any variations in L1 gas costs between a transaction's inclusion in a block and when the sequencer commits the data to L1.
Sending the maximum amount of ETH that a user has in their wallet is a relatively common use case.
-
When doing this, you will need to subtract the estimated L2 execution fee and the estimated L1 data fee from the amount of ETH you want the user to send.
-
Use the logic described above for estimating the total fee.
Error message: invalid transaction: insufficient funds for l1Fee + l2Fee + value
-
-
You'll get this error when attempting to send a transaction and you don't have enough ETH to pay for the value of the transaction, the L2 execution fee, and the L1 data fee.
-You might get this error when attempting to send max ETH if you aren't properly accounting for both the L2 execution fee and the L1 data fee.
Error message: gas price too low: X wei, use at least tx.gasPrice = Y wei
-
-
This is a custom RPC error that Morph returns when a transaction is rejected because the gas price is too low.
-See the section on Responding to gas price updates for more information.
Error message: gas price too high: X wei, use at most tx.gasPrice = Y wei
-
-
This is a custom RPC error that Morph returns when a transaction is rejected because the gas price is too high.
-We include this as a safety measure to prevent users from accidentally sending a transaction with an extremely high L2 gas price.
After deploying your smart contracts, it's crucial to verify your code on our block explorer. This can be automated using your development framework, such as Hardhat.
Most smart contract tools have plugins for verifying contracts on Etherscan. Blockscout supports Etherscan's contract verification APIs, making it straightforward to use these tools with the Morph Mainnet & Testnet.
First, we need a token to bridge. There is no need for a particular ERC20 implementation in order for a token to be compatible with L2. If you already have a token, feel free to skip this step. If you want to deploy a new token, use the following contract of a simple ERC20 token that mints 1 million tokens to the deployer when launched.
Step 2: Launch the counterpart token on Morph Holesky testnet
-
Next, you'll launch a counterpart to this token on Morph, which will represent the original token on Holesky. This token can implement custom logic to match that of the L1 token or even add additional features beyond those of the L1 token.
-
For this to work:
-
-
The token must implement the IMorphStandardERC20 interface in order to be compatible with the bridge.
-
The contract should provide the gateway address and the counterpart token addresses (the L1 token we just launched) under the gateway() and counterpart() functions. It should also allow the L2 gateway to call the token mint() and burn() functions, which are called when a token is deposited and withdrawn.
-
-
The following is a complete example of a token compatible with the bridge. To the constructor, you will pass the official Morph Custom Gateway address (0x058dec71E53079F9ED053F3a0bBca877F6f3eAcf) and the address of the token launched on Holesky.
-
// SPDX-License-Identifier: MIT pragma solidity ^0.8.16; import "@openzeppelin/contracts/token/ERC20/ERC20.sol"; import "@Morph-tech/contracts@0.1.0/libraries/token/IMorphERC20Extension.sol"; contract L2Token is ERC20, IMorphERC20Extension { // We store the gateway and the L1 token address to provide the gateway() and counterpart() functions which are needed from the Morph Standard ERC20 interface address _gateway; address _counterpart; // In the constructor we pass as parameter the Custom L2 Gateway and the L1 token address as parameters constructor(address gateway_, address counterpart_) ERC20("My Token L2", "MTL2") { _gateway = gateway_; _counterpart = counterpart_; } function gateway() public view returns (address) { return _gateway; } function counterpart() external view returns (address) { return _counterpart; } // We allow minting only to the Gateway so it can mint new tokens when bridged from L1 function transferAndCall(address receiver, uint256 amount, bytes calldata data) external returns (bool success) { transfer(receiver, amount); data; return true; } // We allow minting only to the Gateway so it can mint new tokens when bridged from L1 function mint(address _to, uint256 _amount) external onlyGateway { _mint(_to, _amount); } // Similarly to minting, the Gateway is able to burn tokens when bridged from L2 to L1 function burn(address _from, uint256 _amount) external onlyGateway { _burn(_from, _amount); } modifier onlyGateway() { require(gateway() == _msgSender(), "Ownable: caller is not the gateway"); _; } }
You need to contact the Morph team to add the token to L2CustomERC20Gateway contract in Morph and L1CustomERC20Gateway contract in L1. In addition, follow the instructions on the token lists repository to add your token to the Morph canonical bridge frontend.
Once your token has been approved by the Morph team, you should be able to deposit tokens from L1. To do so, you must first approve the L1CustomGateway contract address on Holesky (0x31C994F2017E71b82fd4D8118F140c81215bbb37). Then, deposit tokens by calling the depositERC20 function from the L1CustomGateway contract. This can be done using our bridge UI, Etherscan Holesky, or a smart contract.
You will follow similar steps to send tokens back from L2 to L1. First, approve the L2CustomGateway address (0x058dec71E53079F9ED053F3a0bBca877F6f3eAcf) and then withdraw the tokens calling the withdrawERC20 from the L2CustomGateway contract.
Let’s start by deploying the target smart contract. We will use the Greeter contract for this
-example, but you can use any other contract. Deploy it to either Holesky or Morph. On Morph, L1
-and L2 use the same API, so it’s up to you.
-
// SPDX-License-Identifier: MIT pragma solidity ^0.8.16; // This Greeter contract will be interacted with through the MorphMessenger across the bridge contract Greeter { string public greeting = "Hello World!"; // This function will be called by executeFunctionCrosschain on the Operator Smart Contract function setGreeting(string memory greeting_) public { greeting = greeting_; } }
-
We will now execute setGreeting in a cross-chain way.
Switch to the other chain and deploy the GreeterOperator. So, if you deployed the Greeter contract on L1, deploy the GreeterOperator on L2 or vice versa.
-
// SPDX-License-Identifier: MIT pragma solidity ^0.8.16; // The Morph Messenger interface is the same on both L1 and L2, it allows sending cross-chain transactions // Let's import it directly from the Morph Contracts library import "@Morph-tech/contracts@0.1.0/libraries/IMorphMessenger.sol"; // The GreeterOperator is capable of executing the Greeter function through the bridge contract GreeterOperator { // This function will execute setGreeting on the Greeter contract function executeFunctionCrosschain( address MorphMessengerAddress, address targetAddress, uint256 value, string memory greeting, uint32 gasLimit ) public payable { IMorphMessenger MorphMessenger = IMorphMessenger(MorphMessengerAddress); // sendMessage is able to execute any function by encoding the abi using the encodeWithSignature function MorphMessenger.sendMessage{ value: msg.value }( targetAddress, value, abi.encodeWithSignature("setGreeting(string)", greeting), gasLimit, msg.sender ); } }
We pass the message by executing executeFunctionCrosschain and passing the following parameters:
-
-
MorphMessengerAddress: This will depend on where you deployed the GreeterOperator contract.
-
-
If you deployed it on Holesky use 0x50c7d3e7f7c656493D1D76aaa1a836CedfCBB16A. If you deployed on Morph Holesky use 0xBa50f5340FB9F3Bd074bD638c9BE13eCB36E603d.
-
-
-
targetAddress: The address of the Greeter contract on the opposite chain.
-
value: In this case, it is 0 because the setGreetingis not payable.
-
greeting: This is the parameter that will be sent through the message. Try passing “This message was cross-chain!”
-
gasLimit:
-
-
If you are sending the message from L1 to L2, around 1000000 gas limit should be more than enough. That said, if you set this too high, and msg.value doesn't cover gasLimit * baseFee, the transaction will revert. If msg.value is greater than the gas fee, the unused portion will be refunded.
-
If you are sending the message from L2 to L1, pass 0, as the transaction will be completed by executing an additional transaction on L1.
When a transaction is passed from L2 to L1, an additional "execute withdrawal transaction" must be sent on L1. To do this, you must call relayMessageWithProof on the L1 Morph Messenger
-contract from an EOA wallet.
-
You can do this directly on Etherscan Holesky.
-To do so, you will need to pass a Merkle inclusion proof for the bridged transaction and other parameters. You'll query these using the Morph Bridge API.
-
-
We're finalizing the API specifics, but for now, fetch or curl the following endpoint:
This API was made for our Bridge UI. It is not yet finalized and may change in the future. We will update this guide
-when the API is finalized.
-
Anyone can execute your message
relayMessageWithProof is fully permissionless, so anyone can call it on your behalf if they're willing to pay the L1
-gas fees. This feature allows for additional support infrastructure, including tooling to automate this process for
-applications and users.
-
After executing and confirming the transaction on both L1 and L2, the new state of greeting on the Greeter contract should be “This message was cross-chain!”. Sending a message from one chain to the other should take around 20 minutes after the transactions are confirmed on the origin chain.
-
Congratulations, you now executed a transaction from one chain to the other using our native bridge!
The Morph Holesky Testnet allows anyone to deploy a smart contract on Morph. This tutorial will guide you through deploying a contract on Morph Holesky using common Ethereum development tools.
Before you start deploying the contract, you need to request test tokens from a Holesky faucet and use the
-bridge to transfer some test ETH from Holesky to Morph Holesky.
Then run the following command to deploy the contract on the Morph Holesky Testnet. This will run the deployment script that set the initialing parameters, you can edit the script in scripts/deploy.ts
Thank you for participating in and developing on the Morph Holesky Testnet! If you encounter any issues, join our Discord and find us at #dev-support channel.
If you’re ready to build applications on Morph, you're in the right place.
-
For those who are regular users or visiting for the first time, we recommend starting with our For Users section to explore introductory content such as definitions, our vision, key concepts, and more.
Morph is the first optimistic zkEVM Ethereum Layer 2 solution that is 100% EVM compatible. Building on Morph is just like building on Ethereum. If you’re experienced in Ethereum development, you'll find your existing code, tooling, and dependencies are fully compatible with Morph.
-
We provide a one-page for Morph integration resources if you want to get started quickly.
To help you get started, here’s a recommended navigation through our documentation:
-
Fundamental Concepts: Start here to learn the core components of Morph, including Morph’s Modular Design, the Decentralized Sequencer Network, and the Responsive Validity Proof system.
We're actively enhancing our network with more integrations and support infrastructure, progressing towards our Mainnet release. Join our growing developer community. You can find us on Discord or follow our progress on Twitter.
We provide multiple example Dapps for developers, built on our Morph starter template, deployed on the Morph Testnet, and accompanied by corresponding frontends.
-
These examples are very helpful for developers to go through the entire development process on Morph. Below is a brief introduction of the example Dapps and tutorial links.
-
Morph Starter Template
The Morph starter kit helps developers quickly and efficiently, build dApps on the Morph blockchain. It is a comprehensive template for building fullstack dApps.
-
Example Dapp: Building a Decentralized Hotel Booking System on Morph
This guide walks you through the process of building a decentralized hotel booking system on the MorphL2 blockchain using Solidity smart contracts and a React & Wagmi front-end. This system allows hotel owners to add rooms, manage room availability, accept bookings, and receive reviews from guests.
-
Example Dapp: Building a fractionalized real-estate dApp
Imagine being able to invest in a high-value real estate property without needing to shell out a huge amount of money upfront. Sounds pretty appealing, right? This is the magic of fractionalization. By dividing a property into smaller, more affordable shares, fractionalization makes it possible for just about anyone to get in on the real estate action. It’s like turning a luxury mansion into a bunch of reasonably priced slices that you can buy and sell easily, just like stocks.
-
Our project today, Okido Finance, takes this idea and builds a decentralized application (DApp) around it. With Okido Finance, property owners can create shares of their real estate assets and investors can buy these shares using a custom ERC20 token. This not only democratizes real estate investment but also adds a layer of liquidity, making it easier to trade shares and get in or out of investments.
-
In this tutorial, I’ll walk you through building the Okido Finance DApp step by step. We’ll start with setting up the development environment, move on to deploying smart contracts, and finish with designing a user-friendly UI.
-
By the end, you’ll have a solid grasp of how to build a decentralized real estate fractionalization platform. Whether you’re looking to create something similar or just want to learn more about these technologies, you’ll be well-equipped to dive deeper into fractionalization. Let’s get started!
-
Query and Index Smart Contracts on Morph using Goldsky
Picture this: you're a developer with a brand-new smart contract deployed on the Morph. Your next challenge is to efficiently query and retrieve on-chain data for your decentralized application (dApp). That's where subgraphs come in. Subgraphs offer a powerful and flexible way to index and query blockchain data, making it easy to build responsive and data-rich dApps.
-
In this tutorial, we'll walk through deploying a smart contract on the Morph chain and setting up a subgraph to query this contract. We’ll also introduce Goldsky, a tool that makes creating and managing subgraphs a breeze. Let’s get started and see what we can build together!
Due to limitations in the current geth implementation, only archive mode is supported, meaning the storage size will continually increase with produced blocks.
The returned "catching_up" indicates whether the node is in sync or not. True means it is in sync. Meanwhile, the returned latest_block_height indicates the latest block height this node synced.
Returns information about a block by block number. In addition, it returns more fields than the standard eth_getBlockByNumber, such as withdrawTrieRoot, batchHash, nextL1MsgIndex and rowConsumption.
from: DATA, 20 Bytes - (optional) The address the transaction is sent from.
-
-
-
-
-
to: DATA, 20 Bytes - The address the transaction is directed to.
-
gas: QUANTITY - (optional) Integer of the gas provided for the transaction execution. eth_call consumes zero gas, but this parameter may be needed by some executions.
-
gasPrice: QUANTITY - (optional) Integer of the gasPrice used for each paid gas.
-
value: QUANTITY - (optional) Integer of the value sent with this transaction.
-
input: DATA - (optional) Hash of the method signature and encoded parameters.
-
-
-
QUANTITY|TAG - integer block number, or the string "latest", "earliest", "pending", "safe" or "finalized".
QUANTITY|TAG - integer of a block number, or the string "earliest", "latest", "pending", "safe" or "finalized", as in the default block parameter. Or DATA, 32 Bytes - Hash of a block.
-
tracerConfig(optional), see debug Namespace | go-ethereum
The instructions outlined below detail the procedure for running a full node on the mainnet. To set up and operate a Holesky node, you need to follow the tutorial on sync node from snapshot.
The command make run-node takes the ../mainnet as your node's Home directory by default. There will be two folders in the Home directory named geth-data and node-data, serving as data directories for the execution client and consensus client of the morph ndoe, respectively.
-
This command will also generate the secret-jwt.txt file under Home directory for the authentication during RPC calls between the execution client and consensus client.
With the Quick Start guide above, you can quickly start a node using the default configuration files. However, we also support customizing the node's data directory and parameter settings.
The host directory paths that are mounted by the Docker container are specified in the morph-node/.env file.
-
morph-node/.env
// HOME folder for morph node MORPH_HOME=../mainnet // Flag indicates the network for execution client. MORPH_FLAG=morph // Location of the jwt file for the authentication between clients JWT_SECRET_FILE=${MORPH_HOME}/jwt-secret.txt // The entrypoint shell script for start execution client GETH_ENTRYPOINT_FILE=./entrypoint-geth.sh // The snapshot name for Morph node MAINNET_SNAPSHOT_NAME=snapshot-20241218-1 ......
-
You have the flexibility to customize the directory paths as per your requirements.
-
Please note that if you have customized the HOME directory of your node, you need to copy the necessary configuration files to this directory. Specifically, you should copy the node-data and geth-data from ./mainnet to your HOME directory.
-
note
For running a testnet node, the morph-node/.env_holesky file should be used instead of the morph-node/.env file.
The default configuration required for mainnet node startup is located in the ./mainnet directory, while the files under ./holesky directory is used for testnet node startup.
If you wish to modify the Geth startup command, you can do so by editing the ./morph-node/entrypoint-geth.sh file. For adjustments to the Tendermint-related configuration parameters, you should modify the node-data/config/config.toml file.
The morph-node/.env configuration file in the repository you just cloned is designed for setting up the Morph node on the mainnet. By default, it is pre-configured to use the latest snapshot.
-
If you need a historical snapshot, you must manually update the SNAPSHOT_NAME in the morph-node/.env file. (Note: For the testnet, the corresponding file is morph-node/.env_holesky.)
After downloading, locate the snapshot by placing the decompressed data files in the correct directory specified by the MORPH_HOME path in your .env file. Ensure the data files align with the node's expected structure to allow seamless synchronization.
-
For example, if the snapshot folder is named snapshot-20241218-1,
-
-
move the directory snapshot-20241218-1/geth to the ${MORPH_HOME}/geth-data directory
-
move the contents from snapshot-20241218-1/data to the ${NODE_DATA_DIR}/data directory.
With the snapshot and configuration files ready, navigate to the morph-node folder under your cloned repository, and start the node using the provided command
According to limitations of the current geth implementation, we only support archive mode for launching a Geth. So the storage size of Geth will constantly increase along with blocks produced.
mkdir -p ~/.morph cd ~/.morph git clone https://github.com/morph-l2/morph.git
-
Next, you need to check out a release version. You can find the available release versions on the Morph Releases page. It is recommended to use the latest release version.
Mainnet nodes support synchronization from either the genesis block or a snapshot block, while testnet nodes only support synchronization from snapshots.
The performance of a full node will degrade when the storage size reaches a high volume. We suggest that the fullnode always keep light storage by pruning the storage.
Stop the node, including the consensus client(morphnode) and the execution client(geth)
-
Run nohup geth snapshot prune-zk-state --datadir "$GETH_DB_DIR" > prune.log &. It will take 5~7 hours to finish.
-
Start the node once it is done.
-
-
The hardware is important, make sure the SSD meets: solid-state drive(SSD), 8k IOPS, 500 MB/S throughput, read latency < 1ms.
-
note
To prune a Geth node at least 200 GB of free disk space is recommended. This means pruning cannot be used to save a hard drive that has been completely filled. A good rule of thumb is to prune before the node fills ~80% of the available disk space.
If you are running the Docker container for the node using a custom setup, you will need to manually update the Docker image version and restart the container.
Use the following commands to stop and restart the container. The updated Docker images will be pulled automatically.
-
// stop the docker containers make stop-node // start the docker container, it will automatically pull the updated docker images make run-node
-
If you are running a validator, use these commands instead:
-
make stop-validator make run-validator
-
note
Ensure that the startup parameters for the Docker container remain consistent with your previous configuration. If you previously used a custom setup, verify that the configuration and directory paths match your earlier setup. For details, please refer to Advanced Usage
Upgrading the node is straightforward. Simply install the new version of the node executable file and replace the previous version. Then, stop the currently running node and restart it with the updated version. Node will automatically use the data of your old node and sync the latest blocks that were mined since you shut down the old software.
-
Running the node requires two binary files: morphnode and geth. Choose to upgrade the binary files according to your specific needs.
You can have the released code version from Morph release page.
-
git clone https://github.com/morph-l2/morph.git // checkout the latest version of the source code you need git checkout ${latestVersion} // install geth make geth // install morphnode cd ./morph/node && make build
The following quick start steps are only applicable for running a validator node on the mainnet. To set up and operate a Holesky validator node, please refer to Sync from Snapshot.
-
note
Starting with the Quick Start initiates synchronization from height 0, which can be extremely time-consuming to reach the latest state. We highly recommend using the Sync from Snapshot approach outlined below for a faster and more efficient startup.
The morph-node/.env file defines the environment variables required for deploying a validator node. Below is an example configuration:
-
morph-node/.env
// General settings MORPH_HOME=../mainnet MORPH_FLAG=morph JWT_SECRET_FILE=${MORPH_HOME}/jwt-secret.txt GETH_ENTRYPOINT_FILE=./entrypoint-geth.sh // Environment variables for validator node L1_CHAIN_ID=1 L1_ETH_RPC=${your_layer1_execution_client_rpc_url} L1_BEACON_CHAIN_RPC=${your_layer1_beacon_client_rpc_url} L1MESSAGEQUEUE_CONTRACT=0x3931ade842f5bb8763164bdd81e5361dce6cc1ef ROLLUP_CONTRACY=0x759894ced0e6af42c26668076ffa84d02e3cef60 DERIVATION_START_HEIGHT=20996776 L1_MSG_START_HEIGHT=20996776
-
Default Directory:
-For running a validator on the mainnet, the MORPH_HOME directory defaults to ../mainnet. You can customize this path to suit your setup.
-
Layer1 RPC URLs:
-Ensure you provide the correct RPC URLs for the Layer 1 execution client (L1_ETH_RPC) and the beacon chain client (L1_BEACON_CHAIN_RPC). These URLs are essential for the validator to fetch rollup batches and maintain synchronization.
We recommend synchronizing blocks using snapshot data to reduce the time required for block synchronization. This approach allows you to start the node from a specific block height, significantly reducing the time needed to reach the latest state.
The morph-node/.env configuration file in the repository you just cloned is designed for setting up the Morph node on the mainnet. By default, it is pre-configured to use the latest snapshot.
-
If you need a historical snapshot, you must manually update the SNAPSHOT_NAME in the morph-node/.env file. (Note: For the testnet, the corresponding file is morph-node/.env_holesky.)
After downloading, locate the snapshot by placing the extracted data files in the correct directory specified by the MORPH_HOME path in your morph-node/.env file. Ensure the data files align with the node's expected structure to allow seamless synchronization.
-
For example, if the snapshot folder is named snapshot-20241218-1,
-
-
move the directory snapshot-20241218-1/geth to the ${MORPH_HOME}/geth-data directory.
-
move the contents from snapshot-20241218-1/data to the ${NODE_DATA_DIR}/data directory.
Before running the node, update the DERIVATION_START_HEIGHT and L1_MSG_START_HEIGHT variables in the morph-node/.env file (or .env_holesky for the testnet).
-
Refer to snapshot-information for the specific values of the configuration heights. Ensure that the corresponding height values match the snapshot version you are configuring.
-
// ... MAINNET_SNAPSHOT_NAME={your expected snapshot name} // ... DERIVATION_START_HEIGHT={the expected start height match the snapshot} L1_MSG_START_HEIGHT={the expected start height match the snapshot}
With the snapshot and configuration files ready, navigate to the morph-node folder under your cloned repository, and start the node using the provided command
-
cd morph-node make run-validator // or for testnet cd morph-node make run-holesky-validator
This guide describes the approach to running a Morph validator node. If you are unfamiliar with the validator duties, please refer to our optimistic zkEVM design.
-
Create the folder ~/.morph as our home directory for this example.
mkdir -p ~/.morph cd ~/.morph git clone https://github.com/morph-l2/morph.git
-
Next, you need to check out a release version. You can find the available release versions on the Morph Releases page. It is recommended to use the latest release version.
You need to set the DERIVATION_START_HEIGHT and L1_MSG_START_HEIGHT variables correctly to match the snapshot version you downloaded. From the snapshot information, you can find the corresponding height values.
export CHAIN_ID=17000 export L1MESSAGEQUEUECONTRACT=0x778d1d9a4d8b6b9ade36d967a9ac19455ec3fd0b export ROLLUP=0xd8c5c541d56f59d65cf775de928ccf4a47d4985c export DERIVATION_START_HEIGHT=${The height matches your snapshot} export L1_MSG_START_HEIGHT=${The height matches your snapshot}
-
note
Note the validator.privateKey is of no use to you. It is used to send challenges when the state root is found to be incorrect. However, we do not currently accept challenges from third party addresses. But it is also a required parameter for the morphnode command, so we give a 0x00... 1.
Make sure you check the validator status constantly, if you find response
-
[2024-06-14|16:43:50.904] root hash or withdrawal hash is not equal originStateRootHash=0x13f91d1c272e48e2d864ce7bfb421506d5b2a04def64d45c75391cdcdd69cd78 deriveStateRootHash=0x27e10420c0e34676a7d75c4189d7ccd1c3407cc8fd0b3eafb01c15e250a1215f batchWithdrawalRoot=0xa3e4a7cf45c7591a6bd9868f1fa7485ae345f10067acaade5f5b07d418b2e172 deriveWithdrawalRoot=0xa3e4a7cf45c7591a6bd9868f1fa7485ae345f10067acaade5f5b07d418b2e172
-
This means your validators find inconsistent between sequencer submission and your own observation.
The Biconomy SDK is an Account Abstraction toolkit that enables the simplest UX on your dApp, wallet, or appchain. Built on top of ERC 4337, Biconomy offer a full-stack solution for tapping into the power of our Smart Accounts Platform, Paymasters, and Bundlers.
We have partnered with Goldsky to provide indexing and subgraph services for Morph Holesky and Morph Mainnet.
-
Goldsky also allow us to grant selected developers with free subgraph services now. If you want to deploy a subgraph with Goldsky, please raise a ticket in our Discord to let us know how we can help.
Envio is a modern, multi-chain EVM blockchain indexing framework speed-optimized for querying real-time and historical data on Morph Holesky and Morph Mainnet.
-
Designed with a core focus on delivering superior performance and seamless developer experience, Envio empowers the next generation of consumer apps.
-
The Quickstart allows you to instantly autogenerate a basic indexer and query your smart contract data on Morph. This is the quickest way to get going and likely the starting point for most developers.
LayerZero is a messaging protocol, not a blockchain. Using smart contracts deployed on each chain, in combination with Decentralized Verifier Networks (DVNs) and Executors, LayerZero enables different blockchains to seamlessly interact with one another.
Space ID offers a universal namespace for blockchain, enabling users to register and manage domain names across different blockchains. It enhances cross-chain interoperability and simplifies user identification across the Web3 ecosystem. This project supports a broad range of applications, from crypto trading to token lending and NFT minting, showcasing a versatile approach to decentralized digital identities.
-
Space ID has launched the .mph domain specific for Morph. If you are looking for integration, please refer to this doc
SPACE ID aims to create a universal name service network that connects decentralized identities with the physical and digital worlds. It is progressing toward becoming a comprehensive digital identity solution for Web3. Read the details here
Among the top priorities of SPACE ID is supporting more blockchains and top-level domains (TLDs). Unlike SPACE ID 1.0, whose main emphasis was on .bnb Name Service, SPACE ID 2.0 instead focuses on multi-chain name service. SPACE ID has reached out to various blockchains for partnership discussions, and expects its ecosystem to flourish with time.
SPACE ID aims to streamline web3 services through the use of a single SDK to assist in the building of DApps. This saves developers time, since they don’t have to work with multiple protocols and be encumbered with issues of blockchain incompatibility. This vision is being realized by adding an all-in-one API over the SDK, allowing current and future partners to seamlessly integrate their web3 services with their unified Web3 Name SDK.
Simplified Address Management: Users can use easy-to-remember names instead of long hexadecimal addresses, reducing the risk of errors in transactions.
-
Interoperability: SpaceID names can point to various types of addresses and resources, supporting multiple blockchain networks and off-chain data.
-
Decentralization: SpaceID is built on blockchain, ensuring that no single entity controls the naming system, which enhances security and censorship resistance.
-
Flexibility: Domain owners have full control over their domains, including the ability to create subdomains, update addresses, and manage metadata.
Cryptocurrency Wallets: Users can receive payments using simple names instead of complex addresses.
-
Decentralized Websites: SpaceID names can point to Greenfield content, enabling decentralized websites.
-
Identity Management: SpaceID can be used as part of a decentralized identity system, linking a user’s SpaceID to their decentralized identifiers and attestations.
-
DApps and Smart Contracts: Developers can use SpaceID to provide human-readable names for their smart contracts and decentralized applications, improving user experience.
Morph Safe is a fork managed by the Morph team in collaboration with Protofire, an official partner of the Safe team. It is a multi-signature smart contract wallet, which means it requires a minimum number of signatures to approve a transaction before it can occur.
-
For example, if your business has three main stakeholders, you can configure the wallet to require approval from either two out of three or all three individuals before a transaction can proceed. This security measure ensures that no single person can compromise the funds.
-
In addition to robust security, Morph Safe offers complete self-custody over funds. The smart contract deployed for the wallet has full control over the wallet's contents and does not rely on any trusted external party for execution.
-
To create your Morph Mainnet Safe wallet click here.
AppKit is a powerful, free, and fully open-source SDK for developers looking to integrate wallet connections and other Web3 functionalities into their apps on any EVM and non-EVM chain. In just a few simple steps, you can provide your users with seamless wallet access, one-click authentication, social logins, and notifications—streamlining their experience while enabling advanced features like on-ramp functionality, in-app token swaps and smart accounts.
WalletKit is a robust, open-source SDK designed to empower seamless wallet connections and interactions across any blockchain. With WalletKit, you can offer your users a simple and secure way to connect with thousands of apps, enabling features like one-click authentication, secure transaction signing, and streamlined wallet address verification. Its chain-agnostic design ensures effortless multi-chain support, eliminating the need for complex integrations while delivering unmatched connectivity and security.
-
To summarize, AppKit is for Web3 applications and WalletKit is for Web3 wallets.
-
You will be able to use Reown AppKit to power end-to-end wallet interactions on your Web3 app deployed on Morph.
Are you eager to build applications on Morph but unsure where to start?
-
You're in the right place – we've got you covered!
-
-
As the first optimistic zkEVM Ethereum Layer 2 solution, Morph is 100% EVM compatible.
-
Building on morph is just like building on Ethereum. If you’re experienced in Ethereum development, you'll find your existing code, tooling, and dependencies are fully compatible with Morph.
Estimates the amount of gas required to fully execute a given message on L2. Only applies to
-L1 => L2 messages. You would supply this gas limit when sending the message to L2.