kfastov / worldcoin-bridge-linea

World ID state bridge for Linea

World ID State Bridge for Linea

Description

This repository will contain the code for the Worldcoin state bridge, specifically designed for the Linea blockchain. The bridge facilitates state synchronization between the WorldID Ethereum mainnet deployment and the Linea network.

Deployments

The addresses of the contract deployments for production and staging will be available in docs/deployments.md.

Supported Networks

• Linea (zkEVM Layer 2 on Ethereum)

Usage

This is a list of the most frequently needed commands.

Build

Build the contracts:

$ forge build

Clean

Delete the build artifacts and cache directories:

$ forge clean

Compile

Compile the contracts:

$ forge build

Coverage

Get a test coverage report:

$ forge coverage

Deploy

Deploy to Anvil:

$ forge script script/Deploy.s.sol --broadcast --fork-url http://localhost:8545

For this script to work, you need to have a MNEMONIC environment variable set to a valid BIP39 mnemonic.

For instructions on how to deploy to a testnet or mainnet, check out the Solidity Scripting tutorial.

Format

Format the contracts:

$ forge fmt

Gas Usage

Get a gas report:

$ forge test --gas-report

Lint

Lint the contracts:

$ bun run lint

Test

Run the tests:

$ forge test

Generate test coverage and output result to the terminal:

$ bun run test:coverage

Generate test coverage with lcov report (you'll have to open the ./coverage/index.html file in your browser, to do so simply copy paste the path):

$ bun run test:coverage:report

Contributing

We welcome contributions to improve and expand the functionality of the Worldcoin state bridge for Linea. Please feel free to open issues or submit pull requests.

Credits

This repo uses code from the Worldcoin State Bridge for Polygon and Optimism, which can be found here.

This repo uses Paul Razvan Berg's foundry template: A Foundry-based template for developing Solidity smart contracts, with sensible defaults.

worldcoin-bridge-linea's Issues

Audit the bridge contracts

Finally, when we test and debug our contracts, we'll need to have them audited.

This issue is now blocked by #4 , #13 , and maybe even more.

Update and clean up dependencies

Description

Upgrade the project dependencies to more recent versions, remove unused dependencies, and ensure compatibility with the currently used Solidity version (0.8.19).

Tasks

1. Review and upgrade all dependencies in package.json that can be updated without breaking changes
2. Remove unused dependencies from package.json (e.g., solmate)
3. Upgrade the Bun version used in GitHub Actions
4. Verify that contracts still build successfully after each update
5. Read changelogs for each updated dependency and apply any necessary code changes for compatibility

Acceptance Criteria

• All upgradeable dependencies in package.json are updated to their latest stable versions
• Unused dependencies (including solmate) are removed from package.json
• Bun version in GitHub Actions is updated to the latest stable version
• Contracts build successfully with the updated dependencies
• All tests pass with the updated dependencies
• Any necessary code changes for compatibility are implemented and documented

Caveats

• Only update to release, battle-tested versions (avoid bleeding edge and beta versions)
• Be prepared to revert changes if unexpected issues arise
• Determining the latest compatible version for each dependency may take time

Resources

• OpenZeppelin Contracts Changelog
• Bun releases

tests: Implement end-to-end tests for the entire World ID state bridge system

Description

You need to create comprehensive end-to-end tests for the entire World ID state bridge system. to ensure that all components work together correctly and that the cross-chain functionality operates as expected.

Tasks

1. Look up the best practices of how cross-domain messaging is tested on Linea (see linea-contracts repo, any other repos and sources that may be helpful)
2. Write automated tests for our bridge according to those best practices. They should cover all basic functionality: initialization of both contracts, propagating roots from L1 using LineaStateBridge, receiving and processing those roots on L2 with LineaWorldID contract
3. Test various scenarios, including:
   • Normal operation (successful state updates by authorized senders)
   • Edge cases (e.g., fraud updates from unauthorized addresses)

Acceptance Criteria

• Tests cover all major components and their interactions.
• All methods of LineaStateBridge and LineaWorldID are covered by tests
• Both success and failure scenarios are tested.
• All tests pass consistently (it's fine for tests to fail if you detect bugs in our contracts while writing these tests)

Caveats

• You may need to write a [simple] mock for the WorldIDIdentityManager (its latestRoot() method is used for receiving Merkle tree roots that are propagated to L2)
• I don't yet know how to test L1->L2 interaction, you should be able to figure it out yourself and come up with a good way of doing it (please provide a good explanation of your choice)

Resources

• Foundry Testing Documentation
• Linea contracts repo

dev: add state bridge contract for Linea

Add State Bridge Contract for Linea

Objective

Implement a State Bridge contract for Linea to enable secure propagation of Merkle roots from the main World ID Identity Manager on Ethereum to the World ID contract on Linea L2.

Tasks

1. Research Linea's L1<>L2 messaging system, including:
   • Ownership model
   • Gas fee handling
   • Message passing mechanisms
2. Implement a LineaStateBridge contract on Ethereum.
3. Develop functionality to propagate Merkle roots to the World ID contract on Linea.

Implementation Details

• Use OpStateBridge.sol from the world-id-state-bridge repository as a reference.
• Implement or adapt a mechanism similar to Optimism's CrossDomainOwnable to ensure that only the LineaStateBridge contract on Ethereum can update the World ID contract on Linea.
• Ensure proper handling of gas fees for cross-chain message passing.

Acceptance Criteria

• LineaStateBridge contract is implemented and compiles successfully.
• Contract can securely propagate Merkle roots from Ethereum to Linea.
• Ownership and permission system is implemented to prevent unauthorized updates.
• Gas fee handling is properly implemented for cross-chain messages.
• Contract passes all relevant tests.
• The contract is properly documented to reflect its functionality

Resources

• OpStateBridge.sol
• Linea Documentation

Deploy and test the bridge on testnet against real Worldcoin contracts

Description

Deploy the bridge on the testnet and test it against real Worldcoin contracts that are already deployed there.

Tasks

1. Deploy the LineaStateBridge on Ethereum Sepolia.
2. Deploy the LineaWorldID on Linea Sepolia, setting the authorized sender to LineaStateBridge on L1.
3. Test the cross-layer operation by propagating the root from WorldIDIdentityManager on Ethereum Sepolia to LineaWorldID on Linea Sepolia, and querying it later on L2 (you may need to figure out how those roots are used on other L2s to send meaningful calls).
4. Encapsulate all these actions into a script that anyone can run (providing it with pre-funded accounts on Ethereum and Linea testnets).

Acceptance Criteria

• LineaStateBridge is deployed on Ethereum Sepolia.
• LineaWorldID is deployed on Linea Sepolia with the authorized sender set to LineaStateBridge.
• Successful cross-layer operation by propagating the root from WorldIDIdentityManager on Ethereum Sepolia to LineaWorldID on Linea Sepolia.
  • Transaction hashes of the corresponding transactions should be posted into the issue or PR comment.
• A script is provided that can automate all the deployment and testing steps, using pre-funded accounts on Ethereum and Linea testnets.

Caveats

• You may need to figure out how the roots are used on other L2s to send meaningful calls.
• Ensure the script can handle pre-funded accounts on both Ethereum and Linea testnets for seamless operation.

Resources

• https://github.com/worldcoin/world-id-state-bridge - may contain some clues on how the bridge can be deployed on testnet

Update the contracts to use CrossDomainOwnableLinea

Motivation

Implementing CrossDomainOwnableLinea improves the manageability of the bridge, aligning it with best practices used in other chains. This abstraction enhances the contract's flexibility and security by allowing addresses on L1 to be owners of contracts on L2, which is particularly important for cross-chain systems.

Description

Modify the contracts to use CrossDomainOwnableLinea instead of MessageServiceBase.sol. This will improve the manageability of the bridge in a manner similar to existing bridges on other chains.

Tasks

1. For LineaWorldID (L2):
   • Inherit from CrossDomainOwnableLinea
   • Change "onlyMessagingService onlyAuthorizedRemoteSender" to "onlyOwner"
2. For LineaStateBridge (L1):
   • Split transferOwnershipLinea into two methods:
     • Simple transferOwnership
     • setMessagingService that calls corresponding methods on L2 contracts inherited from CrossDomainOwnableLinea
3. Update any related tests to reflect these changes
4. Ensure all existing functionality remains intact

Acceptance Criteria

• LineaWorldID contract inherits from CrossDomainOwnableLinea
• LineaWorldID uses "onlyOwner" modifier instead of "onlyMessagingService onlyAuthorizedRemoteSender"
• LineaStateBridge has separate transferOwnership and setMessagingService methods
• All tests pass after the modifications
• No regression in existing functionality

Caveats

• Ensure that the security model remains intact with these changes
• Be cautious of any potential side effects when changing the ownership model

Resources

• CrossDomainOwnableLinea.sol (already implemented)
• Optimism's CrossDomainOwnable3 contract

Write the deploy script for all contracts

We need to create the deploy script for automating the deployment process across multiple networks and managing various configuration settings.

• It should read the configuration from the json configuration file (defaults) and environment variables (overrides).
• It should be able to deploy contracts to mainnet, testnet and local devnet
• You may adapt the script from the world-id-state-bridge repo (if the license permits it)

Useful links:
Deploy script from World ID State bridge repo
PaulRBerg's template

Add the schema of the state bridge

Draw a schema like this
It should feature WoridIDIdentityManager, LineaStateBridge and LineaWorldID, and no other chains except for Ethereum and Linea.
The schema will be used in Readme and docs

Possible tool: https://app.diagrams.net/

Upgrade the Solidity version

Hey team,

I'm thinking about importing Linea base contracts and interfaces directly from their repository. However, there's an issue: Linea contracts require Solidity v0.8.19, while our repo is on v0.8.15.

We chose this version to match the original state bridge repo. But do we really need to stick with v0.8.15, or can we upgrade to v0.8.19?

---

Updates from smart guys in the comments:

• Yes we can "safely" upgrade the compiler because world-id-state-bridge contracts use caret version
• Solidity changelog (we need to read between these two anchors):
  • v0.8.15: https://github.com/ethereum/solidity/blob/develop/Changelog.md#0815-2022-06-15
    ...
  • v0.8.19: https://github.com/ethereum/solidity/blob/develop/Changelog.md#0819-2023-02-22

Fix the build process

The worldcoin dependency is not being installed after one of the Bun upgrades.
We need to find the latest stable version of Bun which doesn't cause the bug(?) and pin it for now.

Setup the repo (part 2)

• Apply suggestions from Github Insights
• Try switching to release versions of dependencies
• Add any common docs that are missing

dev: Determine typical gas limits for relaying messages to Linea

Description

We need to calculate and set appropriate gas limits for relaying messages from Ethereum to Linea in our World ID State Bridge contract.

Tasks

1. Find a method to calculate gas needed for relaying messages from Ethereum to Linea.
2. Estimate gas limits required for each type of message sent from the state bridge on Ethereum to the World ID contract on Linea.
3. Modify the LineaStateBridge contract to include default gas limits for each message type.

Acceptance Criteria

• Gas calculation method is documented
• Gas estimates for each message type are provided and justified.
• LineaStateBridge contract is updated with appropriate gas limit constants or variables.
• Code changes are thoroughly tested and reviewed.

Resources

• Linea Documentation

chore: setup the repo and fix build process

• Update package.json (author, title, description)
• Remove template-specific files and links
• Fix CI/build errors

dev: add World ID contract for Linea

Add World ID contract for Linea

Objective

Implement a World ID contract for the Linea network, enabling cross-chain communication between Linea L1 and L2.

Tasks

1. Research and implement the mechanism to receive messages from the Linea L1<>L2 bridge.
2. Add necessary dependencies and imports for Linea integration.
3. Create a new LineaWorldID contract that extends the abstract WorldIDBridge contract.
4. Implement functionality to receive messages from the StateBridge on L1.

Implementation Details

• Use OpWorldID.sol as a reference for the overall structure and functionality.
• Ensure that all state-changing calls come from the authorized address on L1 (address of the LineaStateBridge contract).
• Implement or adapt a mechanism similar to Optimism's CrossDomainOwnable class for Linea to manage ownership and permissions.

Acceptance Criteria

• LineaWorldID contract is implemented and compiles successfully.
• Contract can receive and process messages from Linea L1 bridge.
• All state-changing functions are properly secured and can only be called by the authorized L1 address.
• Contract passes all relevant tests.
• Contract is properly documented to reflect its functionality

Resources

• OpWorldID.sol
• Linea Documentation

Add proper documentation for the bridge

• Create docs directory
• Write spec for the state bridge (you may look at Worldcoin's repo as a reference)
• Describe unique features of this exact bridge, and changes to the protocol, llke using Linea's messaging system instead of CrossDomainOwnable

Fix ambiguity in LineaStateBridge

transferOwnership method that initiates ownership transfer in Linea has the same name as "normal" transferOwnership from Ownable2Step. It's better to rename it back to transferOwnershipLinea.

Don't forget to update all mentions in tests and scripts