Smart Contract Architecture

6.1 Contract Overview

Network: Celo Mainnet

Deployed Contract Address: https://celoscan.io/address/0xbA8247a2D2AF8D5D61Cb61e7e31737Af8c3B9bff (Verified on chain)

Security Features:

• Reentrancy protection (OpenZeppelin ReentrancyGuard)

• Pausable functionality for emergency situations

• World ID verification for sybil resistance

• Non-upgradeable for maximum trust and transparency

6.2 Core Data Structures

Issue Struct

solidity

struct Issue {
    uint256 id;
    address creator;
    string githubIssueUrl;
    string description;
    uint256 bounty;
    address assignedTo;
    bool isCompleted;
    uint256 percentageCompleted;
    uint256 claimedPercentage;
    bool isUnderReview;
    uint256 createdAt;
    Difficulty difficulty;           // EASY/MEDIUM/HARD
    uint256 deadline;
    uint256 easyDuration;
    uint256 mediumDuration;
    uint256 hardDuration;
    uint256 presentHackerConfidenceScore;
    uint256 minimumBountyCompletionPercentageForStakeReturn;
}

Key Mappings

• issues: Issue ID → Issue details

• contributorStakes: Contributor address → Total staked amount

• creatorIssues: Creator address → Array of issue IDs

• contributorAssignedIssues: Contributor address → Array of assigned issue IDs

• issuePreviousContributors: Issue ID → Array of contributors who attempted it

• hasAttemptedIssue: Issue ID → Contributor → Boolean (one-attempt-per-issue rule)

• addressToNullifier: Address → World ID nullifier (verification)

6.3 Key Functions

For Issue Creators

storeNullifier(uint256 _nullifier)

• Store World ID nullifier for verification

• Required before creating or interacting with issues

• One-time setup per address

createIssue(...)

• Create new bounty issue with customizable parameters

• Requires: World ID verification, payment > AI service fee

• Parameters: GitHub URL, description, difficulty, durations, minimum completion percentage

• AI service fee: 0.00001 ETH sent to AI agent

• Returns: Issue ID

completeIssue(uint256 _issueId)

• Mark issue as fully completed

• Transfers bounty + contributor stake to contributor

• Only callable by issue creator

• Requires: Issue assigned and not already completed

increaseIssueDeadline(uint256 _issueId, uint256 _time)

• Extend deadline for assigned contributor

• Only callable by issue creator

• Useful for complex issues requiring more time

increaseIssueDifficulty(uint256 _issueId, Difficulty _difficulty)

• Upgrade issue difficulty level

• New difficulty must be higher than current

• Automatically adjusts expectations

submitIssuePercentageClaimResponse(uint256 _issueId, bool _isAccepted)

• Accept or reject contributor's partial completion claim

• Updates percentageCompleted if accepted

• Resets claim review state

increaseBounty(uint256 _issueId)

• Add more funds to existing issue bounty

• Only callable by issue creator

• Cannot increase bounty for completed issues

For Contributors

takeIssue(uint256 _issueId)

• Stake and claim exclusive assignment to an issue

• Requires: World ID verification, stake between 5-20% of bounty

• Sets deadline based on difficulty

• One attempt per contributor per issue (prevents gaming)

• Stores stake in escrow

submitIssuePercentageClaim(uint256 _issueId, uint256 _claimedPercentage)

• Claim partial completion percentage

• Puts issue under review by creator

• Must be greater than previously completed percentage

• Range: 1-100%

claimExpiredIssue(uint256 _issueId)

• Recover stake and partial bounty after deadline expires

• Payout = (bounty × percentageCompleted) + stake

• Stake forfeiture: If completion < minimum threshold, stake is added to bounty pool

• Automatically unassigns issue for next contributor

• Only callable by assigned contributor after deadline

For AI Agents

gradeIssueByAI(uint256 _issueId, uint256 _confidenceScore)

• Submit AI confidence score (0-100) for PR quality assessment

• Only callable by whitelisted AI agent address

• Used for automated verification and reputation building

• Score stored in presentHackerConfidenceScore

6.4 Security Guarantees

Economic Security

• Minimum stake requirements: 5-20% of bounty prevents spam and ensures skin-in-the-game

• Two-sided staking: Both creators and contributors have economic incentives aligned

• Automatic stake forfeiture: Contributors who fail to meet minimum completion threshold forfeit stake to bounty pool

• AI service fee: 0.00001 ETH per issue creation funds AI infrastructure

Technical Security

• Reentrancy guards: All state-changing functions with transfers protected by OpenZeppelin's nonReentrant modifier

• Access control:

  • onlyAIAgent: Restricts AI functions to whitelisted agent

  • onlyVerified: Requires World ID verification for all interactions

• Pausable: Emergency pause capability for critical vulnerabilities

• No upgradeable proxies: Immutable contract rules ensure trustless operation

Operational Security

• World ID integration: Prevents sybil attacks through unique human verification

• Nullifier tracking: Each verified human can only register once

• Deadline system: Prevents indefinite issue blocking (7/30/150 days for easy/medium/hard)

• One-attempt-per-issue rule: Contributors can only attempt each issue once, preventing DoS and gaming

• Previous contributors tracking: Transparent history of all attempt attempts

• Partial completion system: Flexible percentage-based payouts reduce all-or-nothing risk

Additional Safeguards

• Stake escrow: Contributor stakes held in contract until completion or expiry

• Transparent state: All issue states publicly queryable via view functions

• Event emission: Comprehensive event logging for off-chain monitoring

• Zero address checks: Validation prevents accidental fund loss

• Percentage validation: Claims bounded to 0-100% range

6.5 Constants

• AI_SERVICE_FEE: 0.00001 ETH

• MIN_CONTRIBUTOR_STAKE_PERCENTAGE: 5%

• MAX_CONTRIBUTOR_STAKE_PERCENTAGE: 20%

• DEFAULT_EASY_DURATION: 7 days

• DEFAULT_MEDIUM_DURATION: 30 days

• DEFAULT_HARD_DURATION: 150 days