INTMAX2 Contract

Installation

As a Git Repository

# Clone the repository
git clone https://github.com/InternetMaximalism/intmax2-contract.git
cd intmax2-contract

# Install dependencies
npm install

As an NPM Package

# Install from npm
npm install intmax2-contract

For Foundry Projects

In your foundry.toml file, add:

[profile.default]
libs = ['node_modules']

Then install the package:

# Install the package
npm install intmax2-contract

# Or with Forge
forge install --no-git intmax2-contract

Project Structure

• contracts/: Smart contract source code
  • block-builder-registry/: Block builder registration and management
  • claim/: Claim processing and verification
  • common/: Shared libraries and utilities
  • contribution/: Contribution management
  • liquidity/: Liquidity pool management
  • permitter/: Permission management
  • rollup/: Rollup functionality
  • withdrawal/: Withdrawal processing
  • verifiers/: Proof verification contracts
  • test/: Test contracts
• scripts/: Deployment and operational scripts
• test/: Test files
• test_data/: Test data files
• test_data_generator/: Tools for generating test data

Contract Overview

Rollup

A smart contract responsible for handling operations related to Intmax blocks.

• Deployment: Scroll
• Functions:
  • Block Posting: Allows posting blocks.
  • Deposit Processing: Integrates deposits from the liquidity contract into the Rollup state.
  • Penalty Fee Management: Enables withdrawal and adjustment of penalty fees associated with rate limiting.

Liquidity

This contract manages asset transfers between the Ethereum and Intmax networks. It handles user deposit and withdrawal operations and maintains asset states.

• Deployment: Ethereum
• Functions:
  • Asset Deposits: Users can deposit tokens (native tokens, ERC20, ERC721, ERC1155) from Ethereum into Intmax.
  • AML Check: Performs AML checks upon deposits and rejects deposits from non-compliant addresses.
  • Asset Withdrawals: Sends tokens withdrawn from Intmax to users on Ethereum.
  • Deposit Management: Stores deposited tokens in a queue, and a Deposit Relayer communicates this information to the Intmax network.
  • Contribution Recording: Records addresses executing essential transactions (such as withdrawals).

Withdrawal

Manages withdrawal processes from the Intmax network to Ethereum, verifies withdrawal proofs, and manages eligible token indices for direct withdrawals.

• Deployment: Scroll
• Functions:
  • Withdrawal Request Submission: Allows submission and verification of withdrawal proofs from Intmax.
  • Token Management for Direct Withdrawals: Manages token indices eligible for direct withdrawals.

Claim

Used to claim rewards from privacy mining, distributing ITX tokens on Ethereum.

• Deployment: Scroll
• Functions:
  • Claim Proof Submission: Submit claim proof from Intmax network.
  • Token Management for Direct Withdrawals: Manages tokens eligible for direct withdrawals.

Block Builder Registry

Maintains a registry of active block builders via heartbeat signals.

• Deployment: Scroll
• Functions:
  • Heartbeat Emission: Enables periodic signals indicating active status.

L1/L2 Contribution

Manages user contributions, tracking allocations, weights, and reward distributions.

• Deployment: Ethereum and Scroll
• Functions:
  • Contribution Recording: Records user contributions with tags for specific periods.
  • Period Management: Manages periodic increments and resets for contributions.
  • Weight Management: Assigns and manages tag weights for each period.

Permitter Contract

This contract uses a service called Predicate to verify AML checks and to determine whether the transaction originates from valid mining activities. It is invoked by the Liquidity contract whenever a user deposits funds. Deposits from addresses that do not comply with predetermined policies will be rejected.

• Deployment: Ethereum
• Functions:
  • Policy Verification: Rejects transaction executions from addresses not compliant with AML and mining validation policies.

Environment Setup

Create a .env file in the root directory with the following variables:

Required Variables

• DEPLOYER_PRIVATE_KEY: Deployer's private key for contract deployment
• ADMIN_ADDRESS: Admin's address for contract initialization and management
• RELAYER_ADDRESS: Relayer's address for the Liquidity contract
• INTMAX_TOKEN_ADDRESS: INTMAX token address. If set to empty string, use the address of TestERC20 token instead.
• WBTC_ADDRESS: Wrapped Bitcoin token address.
• USDC_ADDRESS: USDC token address.
• CONTRIBUTION_PERIOD_INTERVAL: Contribution period interval in seconds
• CLAIM_PERIOD_INTERVAL: Claim period interval in seconds

API Keys

• ALCHEMY_KEY: Key for Alchemy API access
• ETHERSCAN_API_KEY: Key for Etherscan contract verification
• SCROLLSCAN_API_KEY: Key for Scrollscan contract verification

Optional Variables with Defaults

• ADMIN_PRIVATE_KEY: Admin's private key (required if GRANT_ROLE=true)
• RELAYER_PRIVATE_KEY: Relayer's private key (required for running relay scripts like relayDeposits.ts)
• GRANT_ROLE: Set to true to grant roles during deployment (default: false)
• DEPLOY_MOCK_MESSENGER: Set to true to deploy mock messenger contracts for testing (default: false)
• PLONK_VERIFIER_TYPE: Type of Plonk verifier to deploy. Options are mock, faster-mining, normal (default: normal)
• SLEEP_TIME: Sleep time in seconds between deployments (default: 30)

Rate Limiting Parameters (for Rollup contract)

• RATELIMIT_THRESHOLD_INTERVAL: Target interval for rate limiting (default: 10^18 * 30 - 30 seconds in fixed point)
• RATELIMIT_ALPHA: Alpha parameter for rate limiting (default: 10^18 / 3 - 1/3 in fixed point)
• RATELIMIT_K: K parameter for rate limiting (default: 10^18 / 1000 - 0.001 in fixed point)

You can use the provided .env.example file as a template.

Deployment

The deployment process consists of 3 sequential stages. Each stage must be completed before proceeding to the next.

Network Configuration

Set the appropriate network variables before running the deployment scripts:

For localhost environment:

L1_NETWORK=localhost
L2_NETWORK=localhost

For testnet environment:

L1_NETWORK=sepolia
L2_NETWORK=scrollSepolia

For mainnet environment:

L1_NETWORK=mainnet
L2_NETWORK=scroll

Deployment Steps

Execute the following scripts in sequence:

# Step 1: Deploy contracts to L2
npx hardhat run ./scripts/deploy/1_deployToL2.ts --network $L2_NETWORK

# Step 2: Deploy contracts to L1
npx hardhat run ./scripts/deploy/2_deployToL1.ts --network $L1_NETWORK

# Step 3: Initialize L2 contracts
npx hardhat run ./scripts/deploy/3_initializeOnL2.ts --network $L2_NETWORK

Testing and Operational Scripts

The following scripts can be used to test and operate the INTMAX2 protocol:

Deposit and Withdrawal Operations

1. Deposit ETH and Cancel Deposit

Users can deposit ETH to the contract and cancel the deposit if needed:

npx hardhat run scripts/test/depositEth.ts --network $L1_NETWORK
npx hardhat run scripts/test/depositAndCancelEth.ts --network $L1_NETWORK

2. Deposit ERC20 and Cancel Deposit

Users can deposit ERC20 tokens to the contract and cancel the deposit if needed:

npx hardhat run scripts/test/depositAndCancelErc20.ts --network $L1_NETWORK

3. Relay Deposits to L2

The relayer transfers analyzed deposits from L1 to L2:

npx hardhat run scripts/test/relayDeposits.ts --network $L1_NETWORK

4. Post Block

Block builders post blocks to the contract:

npx hardhat run scripts/test/postBlock.ts --network $L2_NETWORK

5. Submit Withdrawal Proof on L2

When a user wants to withdraw assets from INTMAX2, the withdrawal aggregator submits the withdrawal proof:

npx hardhat run scripts/test/submitWithdrawalProof.ts --network $L2_NETWORK

6. Relay Withdrawals to L1

The withdrawal aggregator relays user withdrawals from L2 to L1:

npx hardhat run scripts/test/relayClaims.ts --network $L2_NETWORK

Claim Operations

Submit Claim Proof

npx hardhat run scripts/test/submitClaimProof.ts --network $L2_NETWORK

Utility Scripts

Get Token Information

npx hardhat run scripts/test/getTokenInfo.ts --network $L2_NETWORK

Development

Linting

npm run lint

Testing

npm test

Documentation

Generate documentation from NatSpec comments in the contracts:

npx hardhat docgen