Smart Contracts play a critical role in the Metis Layer 2 ecosystem, enabling secure and decentralized management of Sequencer operations and network activities. This section provides detailed natSpec (Ethereum Natural Specification Format) documentation for both Mainnet and Testnet contracts. By adhering to natSpec standards, we ensure clarity and transparency for developers and auditors alike.

The Smart Contract (natSpec) section is split into two key guides:

1. Mainnet Smart Contract (natSpec): Detailed documentation for contracts deployed on Ethereum Mainnet, covering production-grade operations and locking mechanisms for METIS tokens.

2. Testnet Smart Contract (natSpec): Documentation for contracts deployed on Sepolia Testnet, offering a sandbox environment for testing and experimentation.

All locking, reward distribution, and additional locking operations for Sequencers are executed on the Sepolia Testnet. These contracts are integral to managing the Sequencer lifecycle and ensuring smooth participation in the network.

Key Contracts

The following contracts are essential for Sequencer operations:

Sequencers can perform all operations, including managing rewards and lock-ups, directly through these contracts without needing frontend access.

Key Contract Functionalities

The following methods are provided to manage Sequencers efficiently. These include querying and updating your Sequencer's status, locking tokens, and handling rewards.

Read Contract Information

1. seqOwners

   • Retrieves all operational details of a Sequencer using the owner address.

   • Parameter:

     • seqId (uint256): Sequencer ID.

   • Response: Detailed Sequencer operational state.

2. seqSigners

   • Retrieves Sequencer information using the signer address.

   • Parameter:

     • seqId (uint256): Sequencer ID.

   • Response: Detailed Sequencer operational state.

3. sequencers

   • Accesses all relevant details of a Sequencer using its ID.

   • Parameter:

     • seqId (uint256): Sequencer ID.

   • Response:

     Copy

     pythonCopy codeamount (uint256) : Locked token amount
     reward (uint256) : Accrued rewards
     activationBatch (uint256) : Activation batch number
     updatedBatch (uint256) : Last updated batch number
     deactivationBatch (uint256) : Deactivation batch number
     deactivationTime (uint256) : Time of deactivation
     unlockClaimTime (uint256) : Time for claiming unlocked tokens
     nonce (uint256) : Nonce value
     owner (address) : Owner's address
     signer (address) : Signer's address
     pubkey (bytes) : Signer's public key
     rewardRecipient (address) : Address for reward distribution
     status (uint8) : Current Sequencer status

Write Contract Information

1. lockFor

   • Locks METIS tokens and assigns Sequencer ownership.

   • Parameters:

     • _signer (address): Sequencer signer address.

     • _amount (uint256): Amount of METIS to lock.

     • _signerPubkey (bytes): Uncompressed public key of the signer.

2. lockWithRewardRecipient

   • Similar to lockFor, but allows specifying a reward recipient at the outset.

   • Parameters:

     • _signer (address): Sequencer signer address.

     • _rewardRecipient (address): Reward recipient address.

     • _amount (uint256): Amount of METIS to lock.

     • _signerPubkey (bytes): Uncompressed public key.

3. relock

   • Adds additional tokens to an existing lock or locks accrued rewards.

   • Parameters:

     • _seqId (uint256): Sequencer ID.

     • _amount (uint256): Amount to relock.

     • _lockReward (bool): Whether to lock rewards.

4. setSequencerRewardRecipient

   • Updates or assigns a reward recipient for a Sequencer.

   • Parameters:

     • _seqId (uint256): Sequencer ID.

     • _recipient (address): New reward recipient address.

5. withdrawRewards

   • Withdraws accrued rewards to the specified address.

   • Parameters:

     • _seqId (uint256): Sequencer ID.

     • _l2Gas (uint32): Gas limit for the operation.

6. unlock

   • Initiates the unlocking process for METIS tokens.

   • Parameters:

     • _seqId (uint256): Sequencer ID.

     • _l2Gas (uint32): Gas limit for the bridge operation.

7. unlockClaim

   • Claims unlocked tokens after the 21-day waiting period.

   • Parameters:

     • _seqId (uint256): Sequencer ID.

     • _l2Gas (uint32): Gas limit.

8. withdraw

   • Partially withdraws locked tokens, ensuring the remaining balance meets the minimum lock requirement.

   • Parameters:

     • _amount (uint256): Amount to withdraw.

     • _seqId (uint256): Sequencer ID.

All activities related to locking, rewards, and additional locking operations for Sequencers are executed on the Ethereum L1 mainnet (chainid: 1). These smart contracts form the backbone of Sequencer lifecycle management, enabling seamless integration into the Metis ecosystem.

Key Contracts

The following contracts are critical for Sequencer operations:

Sequencers can interact directly with these contracts to manage rewards, lock-ups, and related activities without requiring frontend tools.

Sequencer Lifecycle: Step-by-Step Guide

1. Review Technical Documentation Thoroughly review all technical documentation to understand the operational and technical requirements for running a Sequencer.

2. Apply for Whitelist Submit an application to join the Sequencer whitelist, which is required to begin operations.

3. Set Up and Run Your Sequencer Deploy your Sequencer node, configure it correctly, and securely back up your private keys. Detailed setup instructions are available in the README.md file.

4. Submit Sequencer Information Provide your Sequencer details via a pull request to the GitHub repository. This should include:

   • name: Your Sequencer's name.

   • avatar: URL for your Sequencer's logo or avatar.

   • url: Website or social profile link (must start with https://).

   • address: Whitelist address for Sequencer lock-up.

   • seq_addr: Sequencer address generated by the node.

   • pubkey: Uncompressed public key generated by your server (ensure to remove any extra 04 characters).

   • desc: A brief description of your organization or individual setup.

5. Approve Locking Tokens Approve the desired amount of METIS tokens to be locked using the LockingInfo contract as the spender.

6. Lock METIS Tokens Use the LockPool contract to lock METIS tokens by calling either the lockFor or lockWithRewardRecipientmethod, depending on whether you are assigning a reward recipient.

7. Check Sequencer Status Use the sequencers method in the LockingPool contract to verify your Sequencer's status and rewards.

8. Claim Mining Rewards Retrieve accrued mining rewards using the withdrawRewards method. If you have not assigned a reward recipient, use the setSequencerRewardRecipient method to configure one before claiming rewards.

Contract Functionalities

The LockingPool contract provides key methods to efficiently manage Sequencer operations, including querying status, locking tokens, and handling rewards.

Reading Contract Information

1. seqOwners Retrieves comprehensive Sequencer status using the owner's address.

   • Parameter: seqId (uint256) - The Sequencer ID.

   • Response: Returns details of the Sequencer's operational state.

2. seqSigners Retrieves Sequencer information using the signer's address.

   • Parameter: seqId (uint256) - The Sequencer ID.

   • Response: Returns details of the Sequencer's operational state.

3. sequencers Accesses all detailed information about a Sequencer using its ID.

   • Parameter: seqId (uint256) - The Sequencer ID.

   • Response:

     Copy

     amount (uint256): Locked METIS tokens.
     reward (uint256): Accrued rewards.
     activationBatch (uint256): Activation batch number.
     updatedBatch (uint256): Last updated batch number.
     deactivationBatch (uint256): Deactivation batch number.
     deactivationTime (uint256): Time of deactivation.
     unlockClaimTime (uint256): Time for claiming unlocked tokens.
     nonce (uint256): Nonce value.
     owner (address): Owner's address.
     signer (address): Signer's address.
     pubkey (bytes): Signer's public key.
     rewardRecipient (address): Reward distribution address.
     status (uint8): Current Sequencer status.

Writing Contract Information

1. lockFor Locks METIS tokens and assigns Sequencer ownership.

   • Parameters:

     • _signer (address): Sequencer signer address.

     • _amount (uint256): Amount of METIS tokens to lock.

     • _signerPubkey (bytes): Uncompressed public key of the signer.

2. lockWithRewardRecipient Similar to lockFor, but includes an additional parameter to specify a reward recipient.

   • Parameters:

     • _signer (address): Sequencer signer address.

     • _rewardRecipient (address): Reward recipient address.

     • _amount (uint256): Amount of METIS tokens to lock.

     • _signerPubkey (bytes): Uncompressed public key.

3. relock Adds more tokens to an existing lock or locks accrued rewards.

   • Parameters:

     • _seqId (uint256): Sequencer ID.

     • _amount (uint256): Additional tokens to lock (can be 0 if relocking rewards).

     • _lockReward (bool): Whether to lock current rewards.

4. setSequencerRewardRecipient Updates or assigns a reward recipient address.

   • Parameters:

     • _seqId (uint256): Sequencer ID.

     • _recipient (address): New reward recipient address.

5. withdrawRewards Withdraws accrued rewards to the specified address.

   • Parameters:

     • _seqId (uint256): Sequencer ID.

     • _l2Gas (uint32): Gas limit for the operation.

6. unlock Initiates the unlocking process for METIS tokens.

   • Parameters:

     • _seqId (uint256): Sequencer ID.

     • _l2Gas (uint32): Gas limit for the bridge operation.

7. unlockClaim Claims unlocked tokens after the mandatory 21-day waiting period.

   • Parameters:

     • _seqId (uint256): Sequencer ID.

     • _l2Gas (uint32): Gas limit.

8. withdraw Partially withdraws locked tokens while maintaining the minimum lock balance.

   • Parameters:

     • _amount (uint256): Amount to withdraw.

     • _seqId (uint256): Sequencer ID.

Best Practices

• Always verify recipient addresses before submitting transactions, especially for rewards or withdrawals.

• Securely manage and back up private keys for long-term Sequencer integrity.

• Monitor gas parameters closely to avoid transaction failures.