Smart Contracts Architecture

CompetitionFactory

The CompetitionFactory contract serves as a factory for creating and managing two types of contracts: competition contracts and modeler contracts.

Contract Initialization: After deployment the smart contract is initialized with an address for a MathHelper contract. The MathHelper contract provides a simple sorting function as well as a hashing algorithm for generating unique IDs. The contract deployer is set as the admin of the contract.

Versioning: The contract implements UUPS proxy upgradeability, and maintains several version numbers to keep track of its own upgrades and the versions of competition and modeler contracts it deploys.

• version: The contract's version.

• competitionVersion: The version of the competition contracts.

• modelerVersion: The version of the modeler contracts.

Deployment of Competition Contracts:

• The deployCompetition function is used to create new competition contracts.

• It requires a number of parameters, the admin address, an IPFS reference to competition data, a topN parameter which refers to the number of active modelers in the system, and service agreement parameters.

• The contract deploys a new competition contract using a proxy pattern and initializes it with the provided parameters.

• The address of the newly deployed competition contract is stored in contract storage, and an event is emitted, that is consumed by web2 services.

Deployment of Modeler Contracts:

• The deployModeler function is used to create new modeler contracts.

• It requires a number of parameters, such as the address of the competition contract, validator token address, validator stake amount, and maximum validators allowed.

• Similar to competition contracts, the contract deploys a new modeler contract using a proxy pattern and initializes it with the provided parameters.

• The address of the newly deployed modeler contract is stored, and an event is emitted.

Upgrading Competition and Modeler Contracts:

• The contract owner can upgrade the logic of competition and modeler contracts using the upgradeCompetition and upgradeModelerContract functions.

• These functions require the address of the new logic contract to replace the existing one.

• When an upgrade occurs, the contract version and the respective contract's version are incremented, and an event is emitted.

Querying Contracts:

• The smart contract provides functions to query the list of all deployed competition and modeler contracts, as well as their respective lengths.

• Users can fetch information about all the competition and modeler contracts created by the factory.

Changing Admin:

• The contract owner can change the admin address using the setNewAdmin function. This is used to transfer administrative control to another address.

Upgrade Authorization:

• The contract uses the OpenZeppelin UUPSUpgradeable pattern to handle upgrade authorization.

• The _authorizeUpgrade function ensures that only the contract owner can authorize upgrades to the implementation contract.

The CompetitionFactory smart contract's utility is to deploy, manage, and upgrade competition and modeler contracts. It offers modularity, version control, and the ability to change administrators when necessary.

Competition

The Competition contract represents a distinct machine learning challenge in the Spectral Machine Learning Platform.

Contract Initialization:

The contract is initialized with various parameters, including the admin address, math helper contract address, IPFS hash for competition details, top N modelers parameter, and service agreement parameters.

It sets up the initial configuration for the competition and deploys a new service agreement contract for participants.

Registration of Modelers:

Modelers can sign up for the competition by calling the signUpToCompetition function. To participate, modelers must provide a unique model hash and stake a certain amount of tokens as defined in the service agreement.

The contract ensures that the model hash is not empty and transfers the staked tokens to the modeler contract. It then registers the modeler's participation and emits an event.

Management of Modelers' Performance:

The contract maintains a list of top N modelers who serve inferences during a consumption window. If there are fewer top N modelers than the defined parameter, new modelers are added to the list and may provide inferences during the consumption window.

When a new modeler's performance result surpasses the lowest performing modeler in the list, the contract replaces the lowest with the new modeler.

Replacing Opted-Out Modelers

Modelers can opt out of the competition, and the contract allows the admin to replace an opted-out modeler with a new one. The replaceOptOutTopNModeler function facilitates this replacement.

Setting Modeler and Consumption Contracts

The admin can set the addresses of the modeler contract and the consumption contract using the setModelerContract and setConsumptionContract functions, respectively.

Updating Competition Details

The admin can update the IPFS hash for the competition description and the IPFS hash for the training dataset using the setIPFSCompetitionDescriptionHash and setIPFSTrainingDataSet functions, respectively.

Service Agreement Management

The contract manages the service agreement for participants. The admin can set a new service agreement using the setNewServiceAgreement function. Participants can sign the service agreement through the signUpToCompetition function.

Emergency Opt-Out

The admin has the authority to perform an emergency opt-out for a validator in the modeler contract by calling the emergencyOptOutValidator function.

Admin Management

The admin address can be changed by the current admin using the setAdmin function.

View Functions

The contract provides various view functions to retrieve information, such as the list of top N modelers, their length, a modeler's median performance result, and service agreement parameters.

Service Agreement

The Service Agreement contract defines a list of rules and parameters for a given Competition.

Contract Initialization

The contract is initialized with the address of the admin (contract owner) and a data structure of type DataTypes.SAParams representing the terms and conditions of the service agreement. The contract stores the admin's address, the agreement details, and the timestamp of the last service agreement update.

Service Agreement Creation

When the contract is deployed, a service agreement is created with the provided initial parameters. An event named ServiceAgreementCreated is emitted to record the creation of the service agreement.

Admin-Only Functions

The contract includes a modifier called onlyAdmin that ensures that only the contract owner (admin) can call certain functions. This is enforced through the require statement within the modifier.

Updating the Service Agreement:

The admin can update the service agreement by calling the updateServiceAgreement function. However, there is a time-based restriction in place to prevent frequent updates. The agreement can only be updated once every 28 days, as enforced by the require statement.

When the service agreement is updated, the new parameters are provided as input, and the agreement details are replaced with the new values. The timestamp of the last update is also updated to the current block timestamp.

View Functions

The contract provides a series of view functions that allow external parties to retrieve specific parameters from the service agreement.

These view functions include:

• agreementParams(): Returns the complete set of service agreement parameters as a DataTypes.SAParams structure.

• bountyAmount(): Retrieves the bounty amount defined in the service agreement.

• requestPaymentAmount(): Retrieves the payment amount for service requests.

• requestExpirationTime(): Returns the expiration time for service requests.

• responseDataType(): Retrieves the data type expected in response to service requests.

• endAt(): Returns the end timestamp of the service agreement.

• competitionContractAddress(): Retrieves the address of the competition contract associated with the service agreement.

• stakedToken(): Retrieves the address of the token used for staking within the agreement.

• stakedAmount(): Returns the amount required for staking as defined in the agreement.

• disputeStake(): Retrieves the dispute stake amount.

• slashAmount(): Retrieves the slash (penalty) amount for violations of the agreement.

Contract Ownership:

The contract owner (admin) has the authority to update the service agreement and manage its parameters.

Modeler

The Modeler contract facilitates interactions between validators and modelers for a specific machine learning competition.

Initialization

The contract is initialized with the address of the competition contract, the validator staking token address, the validator stake amount, and the maximum number of validators allowed, as arguments.

Role Management

The contract supports two primary roles: validators and modelers. Validators are entities responsible for challenging modelers and providing proofs of randomness.

Modelers are participants who register their model commitments, respond to challenges, and aim to achieve top performance to modeler challenges.

Validator Registration

Validators can register themselves using the registerValidator function. This function verifies whether the maximum allowed number of validators has been reached and initializes validator-specific data, including their stake amount.

Modeler Registration

Modelers can register themselves through the registerModeler function. During registration, they provide their model commitment, staked amount, and other relevant information. Modelers are added to an array of modeler addresses for easy reference.

Model Updates

Modelers can update their model commitments using the updateModel function. However, top modelers are restricted from doing so. When a model is updated, related challenge data and performance results are reset.

Challenges and Responses

Validators can issue challenges to specific modelers using the giveChallengeToModeler function. These challenges are recorded along with associated Drand proofs. Modelers respond to challenges through the respondToChallenge function, providing their responses to the challenges.

Challenge Grading

Validators can post graded results for modeler's challenge results using the postGraded function. Graded results include the IPFS link to the grading information and performance results. Grading triggers the calculation of median performance results for the modeler.

Modeler Net Performance Result

The contract allows validators to set the net performance result for a modeler using the setModelerNetPerformanceResultAndUpdate function. This is utilized by the competition contract.

ZKML Challenges

Validators can also issue Zero-Knowledge Machine Learning (ZKML) challenges to modelers using the ZKMLChallengeModeler function, to ensure that modelers are using the models that they were graded on, during the consumption window or challenge window.

Opting In and Out

Both validators and modelers have the ability to opt in and out of the competition using functions like optOutModeler, optInModeler, optOutValidator, and optInValidator.

Emergency Opt-Out

• In case of an emergency, the competition contract can trigger an emergency opt-out for a validator.

Stake Management

Modelers can add tokens as stake to their account using the addStakeToModeler function, while validators can do the same using addStakeToValidator. These functions facilitate the management of stakes within the competition and are used in the case that a modeler or validator is slashed for not adhering to the Service Agreement parameters or acting maliciously.

View and Query Functions

The contract offers various view functions to retrieve information, such as querying whether an address is a validator or modeler, fetching the details of a specific modeler, and listing all registered validators.

Contract Pausing

The contract inherits from OpenZeppelin's PausableUpgradeable, allowing the pausing and resuming of certain contract functions.

Event Logging

The contract emits numerous events, such as ChallengeGiven, ModelerResponds, ModelerGraded, and others, to record important actions and transactions.

Consumption Contract

The contract allows the competition contract to set the consumption contract address.

Consumption

In Development