World

Operator Payouts

The OperatorPayoutsWorldchain contract enables the transfer of WLD token payouts by an authorized relayer, which is intended to be the Operator backend. The contract accepts a reward amount specified in USD, as a whole number with zero decimals, and converts it to the equivalent WLD amount using the WLD/USD price provided by the Chainlink oracle.

The contract exposes two main functions for token transfers:

function transfer(address payable to, uint256 dollarAmount) external onlyRelayer

This function transfers WLD tokens to the specified recipient address based on the current Chainlink oracle price. Transfers are executed through Worldcoin’s allowance module.

function transferWithMinimumWLDPrice(
        address payable to,
        uint256 dollarAmount,
        uint256 minWldPrice
) external onlyRelayer

This variant allows the relayer to specify a minimum acceptable WLD/USD price. If the oracle price falls below this minimum, the transfer will use the specified minimum price instead, resulting in a lower WLD payout. This function is used as a safeguard in cases of large WLD price drops.

Software documentation refers to the written or visual information that describes the functionality, architecture, design, and implementation of software. It provides a comprehensive overview of the software system and helps users, developers, and stakeholders understand how the software works, how to use it, and how to maintain it. Software documentation can take different forms, such as user manuals, system manuals, technical specifications, requirements documents, design documents, and code comments. Software documentation is critical in software development, enabling effective communication between developers, testers, users, and other stakeholders. It helps to ensure that everyone involved in the development process has a shared understanding of the software system and its functionality. Moreover, software documentation can improve software maintenance by providing a clear and complete understanding of the software system, making it easier for developers to maintain, modify, and update the software over time. Smart contracts can use various types of software documentation. Some of the most common types include:

• Technical whitepaper: A technical whitepaper is a comprehensive document describing the smart contract’s design and technical details. It includes information about the purpose of the contract, its architecture, its components, and how they interact with each other;
• User manual: A user manual is a document that provides information about how to use the smart contract. It includes step-by-step instructions on how to perform various tasks and explains the different features and functionalities of the contract;
• Code documentation: Code documentation is a document that provides details about the code of the smart contract. It includes information about the functions, variables, and classes used in the code, as well as explanations of how they work;
• API documentation: API documentation is a document that provides information about the API (Application Programming Interface) of the smart contract. It includes details about the methods, parameters, and responses that can be used to interact with the contract;
• Testing documentation: Testing documentation is a document that provides information about how the smart contract was tested. It includes details about the test cases that were used, the results of the tests, and any issues that were identified during testing;
• Audit documentation: Audit documentation includes reports, notes, and other materials related to the security audit of the smart contract. This type of documentation is critical in ensuring that the smart contract is secure and free from vulnerabilities.

These types of documentation are essential for smart contract development and maintenance. They help ensure that the contract is properly designed, implemented, and tested, and they provide a reference for developers who need to modify or maintain the contract in the future.

Worldcoin's smart contract documentation was provided within the PR description, which thoroughly explained the contract's purpose and implementation logic.

Each function in the codebase is accompanied by NatSpec comments that describe its purpose and input parameters. Additionally, the Worldcoin team provided a comprehensive walkthrough of the project during the kick-off call, addressing all questions and concerns raised by the Nethermind Security team.

The Worldchain Operator Payouts's test suite is robust and clearly outlines the contract specifications. The test suite catches changes to the business logic. To assess the test coverage for these files, the Nethermind Security team applied a technique called mutation testing to uncover the untested paths. This technique introduces slight modifications to the code called "mutations" or "mutants." An example of a mutation is, for example, changing the operator in an expression (a + b) to (a - b), or removing a require(a > b) statement entirely from the code. With these changes, the code no longer follows the expected business logic of the application, and the test suite should reflect that by failing.

Evaluation of the test suite with mutation testing consists of two phases:

1. Generating the modified version of each contract, called "mutants."
2. Inserting the mutant into the original codebase and running the test suite.

Only one modification can be tested at a time. If the contract has ten mutations, the test suite must run ten times (once for every mutation). If any of the tests fail, it means that the test suite caught the change in the code. Whenever that happens, the particular mutant is considered "slain" or "killed" and is removed from the mutant's set. If that does not occur, a new test case can be added to cover the code branch to "kill" the mutant.

The following table outlines the results of the analysis performed on the Worldchain Operator Payouts' core smart contract. The first column lists the contracts that were tested using mutation testing. The second column indicates the number of mutants generated and how many were "slain" (i.e., caught by the test suite). The third column provides the percentage of mutants slain, reflecting the effectiveness of the test suite in covering the particular contract. The higher the score, the better the test suite is at finding bugs.

The following is a list of code modifications not caught by the existing test suite. Each point highlights a scenario that could benefit from higher test coverage to enhance the protocol's overall security and resilience in the next code change iterations as the project evolves:

OperatorPayoutsWorldchain.sol

• The transferWithMinimumWLDPrice(...) function is only tested in scenarios where the provided to address is non-zero. Consider adding a test case that triggers the ZeroAddress error.
• The transferWithMinimumWLDPrice(...) function doesn't test the scenarios where the answer value returned by the oracle is zero or less. Consider adding a test case that triggers the InvalidOraclePrice error.

Remarks about the Worldchain Operator Payouts Test Suite

The test suite for the Worldchain Operator Payouts Protocol is robust in terms of unit testing for core functionality. Changes in business logic are effectively caught, ensuring that key components behave as expected under various conditions. However, the suite currently relies on mock contracts, such as the mock implementation of the allowance module. While this approach is useful for isolating components during unit testing, it limits the ability to detect integration issues that may arise in production. The test suite can be improved by incorporating more end-to-end tests using actual contract implementations and by addressing the missing flows outlined earlier.

All the relevant issues raised by the AuditAgent have been incorporated into this report. The AuditAgent is an AI-powered smart contract auditing tool that analyses code, detects vulnerabilities, and provides actionable fixes. It accelerates the security analysis process, complementing human expertise with advanced AI models to deliver efficient and comprehensive smart contract audits. Available at https://app.auditagent.nethermind.io.