How codefox-inc/sparkn-contracts works
Main Components
• Smart Contracts:
• ProxyFactory.sol – the central entry point for creating new contest proxies and controlling fund distribution.
• Distributor.sol – the logic implementation contract used to handle prize distribution via delegatecall.
• Proxy.sol – a minimal proxy contract deployed per contest, forwarding calls to the Distributor.
• External Roles:
• Organizer – creates contests and, using the factory, deploys proxies and distributes prizes.
• Sponsor – funds the contest by sending whitelisted ERC20 tokens to the anticipated proxy address.
• Supporter – participants who help solve problems, with winners eventually receiving prize funds.
• Owner – the protocol administrator who can execute critical functions (including rescue operations).
• Off-Chain Components:
• Web2 integrations or interfaces (as indicated by hybrid design notes), deployment scripts (Makefile, script folder), and CI/CD workflows (GitHub Action workflows) that support the development, testing, and deployment processes.
Relationships and Interactions
• The central orchestrator is the ProxyFactory which:
• Configures contests via setContest().
• Offers a function to pre-calculate proxy contract addresses (getProxyAddress()).
• Deploys Proxy contracts which then perform a delegatecall to the Distributor for distributing funds.
• Proxy contracts themselves are lightweight containers that rely on the logic housed in the Distributor contract.
• Roles interact with the system through these contracts:
• For example, organizers and sponsors send funds to the Proxy contract address prior to deployment.
• Depending on the contest lifecycle, the functions deployProxyAndDistribute(), deployProxyAndDistributeBySignature(), or deployProxyAndDistributeByOwner() are invoked.
Architectural Patterns and Design Principles
• Proxy Pattern: To minimize gas costs by deploying minimal proxy contracts for each contest while sharing the distribution logic from a single Distributor instance.
• Delegation via delegatecall: Allows Proxy contracts to execute Distributor functions in their own context, preserving storage and efficiency.
• Use of Immutable Variables: The design makes heavy use of immutability to prevent state variable collisions.
• Meta Transaction and EIP712: To support off-chain signing and safe on-chain operations.
• Separation of Concerns: Clear distinction between contest orchestration (factory), contract logic (distributor), and the minimal proxy layer.
Technology Stack and Supporting Elements
• Solidity smart contracts under the src/ directory.
• Testing with Foundry (evident from Makefile, foundry.toml, test folder with fuzz, integration, unit tests).
• Use of libraries from OpenZeppelin (for access control and signature verification).
• GitHub CI/CD integration (GitHub workflows) for automated testing.
• External ABI files and deployment scripts assist with integration in various EVM networks.