Yet another smart-contracts bundle for the ultimate funding tool for real Zakos only.
On-chain treasury management and fundraising platform for open-source development teams.
- 1. Overview
- 2. Architecture
- 3. Getting Started
- 4. Development
- 5. Deployment
- 6. Security
- 7. Documentation
- 8. Project Status
- 9. Contributing
- 10. Team
- 11. License
- 12. Links
ZakoBox/ZakoPako is a decentralized treasury management system designed specifically for open-source development teams and DAOs. Built as an on-chain alternative to OpenCollective, it combines the functionality of Guild.xyz, SAFE, and Snapshot/Aragon into a unified platform focused on internal team governance rather than large-scale community governance.
- Multi-Signature Treasury Management: Secure fund storage with configurable approval thresholds (minimum 2 for multi-owner)
- Multi-Token Support: PYUSD (priority), USDC, USDT, and native ETH
- PayPal USD (PYUSD) is the default primary donation token
- Supports PYUSD across all target networks (Ethereum, Sepolia, Polygon, Arbitrum, Base)
- Pre-configured token whitelist includes PYUSD + USDC + ETH
- Deterministic Deployment: CREATE2-based factory for predictable cross-chain addresses
- Transparent Fund Tracking: Complete on-chain transparency with Blockscout integration
- Flexible Withdrawal Controls: Daily limits, whitelisting, and vesting schedules
- Emergency Mechanisms: Higher-threshold emergency withdrawals requiring
emergencyThresholdapprovals - 7-Day Upgrade Timelock: Built-in protection with 7-day delay before contract upgrades take effect
The hackathon MVP focuses on two core contracts:
ZakoBox: Individual treasury contract with multi-sig protection and PYUSD supportZakoBoxFactory: CREATE2-based factory for deploying treasury instances
ETHOnline 2025 Highlights:
- PayPal USD (PYUSD) Track: First-class PYUSD integration as primary donation token
- Hardhat Track: Built with Hardhat 3.0+ and comprehensive test suite (91 tests)
- Blockscout Track: Complete on-chain transparency and event indexing
Note: DAO governance, voting mechanisms, and token economics are planned for post-hackathon releases.
ZakoBox uses a three-layer upgradeable architecture for maximum flexibility and gas efficiency:
Layer 1: ZakoBoxFactory (UUPS Proxy)
- Upgradeable factory contract
- Deploys treasury instances via EIP-1167 + CREATE2
- Owner-controlled upgrades
Layer 2: Treasury Instances (Minimal Proxies)
- Lightweight EIP-1167 clones (~45 bytes, ~100k gas)
- Each treasury has unique storage
- Deterministic addresses via CREATE2
Layer 3: ZakoBox Implementation (UUPS)
- Shared upgradeable logic contract
- Multi-sig controlled upgrades
- All instances delegate to this implementation
Benefits:
- β Both factory and treasuries are upgradeable
- β Massive gas savings (~97% cheaper deployment)
- β Independent upgrade control per treasury
- β CREATE2 deterministic addresses preserved
- UUPS upgradeable implementation contract
- Multi-signature fund management (configurable threshold, e.g., 3/5)
- Support for ETH and ERC-20 tokens
- Daily withdrawal limits and recipient whitelisting
- Vesting schedules with configurable unlock periods
- Emergency withdrawal mechanism with higher approval threshold
- UUPS upgradeable factory contract
- CREATE2-based deterministic deployment via EIP-1167 clones
- Registry of all deployed treasury contracts
- Batch deployment capabilities
- Cross-chain address consistency
- Updatable implementation address
- Smart Contracts: Solidity 0.8.28
- Development Framework: Hardhat 3.0+
- Testing: Hardhat + Viem
- Deployment: Hardhat Ignition
- Libraries: OpenZeppelin Contracts (UUPS proxy, ReentrancyGuard, Pausable)
- Proxy Pattern: UUPS + EIP-1167 Minimal Proxies
- Ethereum Mainnet
- Polygon
- Arbitrum One
- Base
- Sepolia (Testnet)
- Node.js >= 18
- npm or yarn
- Git
# Clone the repository
git clone https://github.com/ZakoDAO/ZakoBox-ZakoPako-Contracts.git
cd ZakoBox-ZakoPako-Contracts
# Install dependencies
npm installSet up network configuration using Hardhat's keystore:
# Set Sepolia RPC URL
npx hardhat keystore set SEPOLIA_RPC_URL
# Set deployment private key
npx hardhat keystore set SEPOLIA_PRIVATE_KEY
# List all configured keys
npx hardhat keystore list# Compile contracts
npx hardhat build
# Clean artifacts
npx hardhat clean# Run all tests (91 tests, all passing)
npx hardhat test
# Run with coverage
npx hardhat test --coverage
# Run specific test file
npx hardhat test test/ZakoBox.test.ts
# Run specific test suite
npx hardhat test --grep "Emergency Withdrawal"Current Test Status:
- β 91 tests passing
- β 0 tests failing
- π Comprehensive coverage including:
- Multi-signature withdrawal workflows
- Emergency withdrawal with higher threshold
- Daily limit enforcement and reset
- Vesting schedules (cliff, proportional, full)
- Factory upgrade with 7-day timelock
- Access control and authorization
# Start local Hardhat node
npx hardhat node
# In another terminal, deploy to local network
npx hardhat ignition deploy ignition/modules/ZakoBoxFactory.ts --network localhostπ For detailed deployment instructions, see Deployment Guide
# Deploy factory contract
npx hardhat ignition deploy ignition/modules/ZakoBoxFactory.ts --network sepolia
# Or use custom deployment script
npm run deploy:sepolia
# Verify on Blockscout
npx hardhat verify blockscout --network sepolia DEPLOYED_ADDRESS
# Verify on Etherscan
npx hardhat verify etherscan --network sepolia DEPLOYED_ADDRESS# Use production build profile with optimizations
npx hardhat ignition deploy ignition/modules/ZakoBoxFactory.ts \
--network mainnet \
--build-profile production
# Verify contracts
npx hardhat ignition verify --deployment-id <deployment-id>Pre-Deployment (Sepolia):
- All tests passing (91/91 tests β )
- Security audit completed (3 CRITICAL + 6 HIGH issues fixed)
- Gas optimization review
- Correct compiler settings verified (0.8.28, 200 runs)
- Network configuration confirmed
- Token addresses verified for target chain
Pre-Deployment (Mainnet):
- External professional audit
- 2+ weeks on testnet without issues
- Bug bounty program live
- Multi-sig setup for factory owner (minimum 3/5)
- Emergency response procedures documented
- Upgrade procedures tested on testnet
- Reentrancy Protection: All fund transfers protected with OpenZeppelin's ReentrancyGuard
- Access Control: Role-based permissions for all sensitive operations
- Pausable: Emergency pause mechanism for critical situations
- Multi-Signature: Required approvals for all withdrawals (minimum threshold of 2 for multi-owner)
- Emergency Threshold: Higher approval requirement for emergency withdrawals
- Daily Limits: Rate limiting to prevent rapid fund drainage
- Vesting Validation: Comprehensive validation of vesting parameters (start time, cliff, duration)
- Upgrade Timelock: 7-day delay before contract upgrades take effect
- Gas Limits: 30k gas limit on ETH transfers to prevent gas griefing
- Duplicate Checks: Prevention of duplicate whitelist entries
- Internal security audit completed (2025-10-25)
- 3 CRITICAL issues: All fixed β
- 8 HIGH issues: 6 fixed β , 2 accepted risks
- 5 MEDIUM issues: Documented
- 4 LOW issues: Documented
- Code review and testing (91 tests passing)
- External professional audit (recommended before mainnet)
- Bug bounty program (planned post-deployment)
π Security Documentation:
Please report security vulnerabilities to: security@zako.wtf
Do not create public GitHub issues for security vulnerabilities.
Core Documentation:
- Developer Documentation: Comprehensive technical documentation for developers
- Deployment Guide: Step-by-step deployment instructions for Sepolia and mainnet
- Upgradeable Architecture: Detailed explanation of the UUPS + EIP-1167 proxy architecture
- Access Control: GitHub account authorization and access control mechanisms
Security Documentation:
- Security Audit Report: Complete security audit findings and analysis
- Security Fixes Summary: All security fixes applied with code examples
Contract ABIs and detailed function documentation can be found in the Developer Documentation.
For frontend integration examples using Viem, see Section 4 of the Developer Documentation.
ETHOnline 2025 Hackathon MVP (October 15-26, 2025)
- Project initialization
- Core contracts (ZakoBox + ZakoBoxFactory)
- Multi-signature treasury with configurable thresholds
- Emergency withdrawal with higher threshold
- Vesting schedules with validation
- Daily withdrawal limits
- 7-day upgrade timelock
- Factory with CREATE2 deployment
- Access control for authorized accounts
- Comprehensive test suite (91 tests, 100% passing)
- Unit tests (>95% coverage)
- Integration tests (complete workflows)
- Emergency withdrawal tests
- Vesting scenario tests
- Upgrade timelock tests
- Security audit and fixes
- All CRITICAL issues fixed (3/3)
- All HIGH issues addressed (6/8 fixed, 2 accepted)
- Documentation
- Developer documentation
- Deployment guide
- Security audit report
- Security fixes summary
- Testnet deployment (Sepolia)
- Contract verification (Blockscout + Etherscan)
- DAO governance contracts
- Voting mechanisms
- Token economics system
- GitHub integration
- Advanced vesting and milestone features
- Cross-chain bridge integration (Jumper)
- Yield optimization (AAVE, Compound)
- Analytics dashboard
- Mobile app
Hackathon Goals:
- β Complete MVP core functionality (ZakoBox + ZakoBoxFactory)
- β Pass all test cases (91/91 tests, 100% passing)
- β Security audit completed (all CRITICAL and HIGH issues addressed)
- β Comprehensive documentation (6 documents)
- π Successful Sepolia testnet deployment (pending)
- π― Win at least one ETHOnline track prize
Current Achievement:
- 95% MVP Complete - Ready for testnet deployment
- 91 Tests Passing - Comprehensive test coverage
- Security Hardened - All critical vulnerabilities fixed
- Production Ready - Code quality meets high standards
- Solidity: Follow Solidity Style Guide
- TypeScript: ESLint configuration in project
- Comments: Use NatSpec for all public/external functions
- Hannes Gao - The Lead
DeveloperZako in the ZakoBox - The Ο-Zako Team - The Core Develop Team of Project ZakoBox/ZakoPako
- ZakoDAO - The Core Developer DAO of Project Airi
This project is licensed under the MIT License - see the LICENSE file for details.
- Documentation: ./docs
- Website: [Coming Soon]
- GitHub: https://github.com/Zako-DAO/ZakoBox-ZakoPako-Contracts
This project is participating in ETHOnline 2025 hackathon.
Submission Deadline: October 26, 2025
Built with β₯ by The Ο-Zako Team for the open-source community