Architectural Overview
Proxy Pattern Implementations
1. UUPS Upgradeable Proxies
Core protocol contracts use OpenZeppelin’s UUPS (Universal Upgradeable Proxy Standard) pattern:- EventManager:
0x29A34231B3c156b3556Be018e0323885b16E8962 - LiveTipping:
0xd431284b6c5a4FFF616437f0178051af406e63E6 - Distributor:
0xb7F59ce88DaD15b27F04F96a8508D4dFa4eC6598
2. Minimal Proxies (EIP-1167)
Delegation contracts use minimal proxies for maximum gas efficiency:| Deployment Type | Gas Cost | Bytecode Size |
|---|---|---|
| Full Delegation Contract | ~200,000 gas | ~2,000 bytes |
| Minimal Proxy | ~40,000 gas | 55 bytes |
| Savings | 80% reduction | 97% reduction |
3. CREATE2 Deterministic Deployment
Per-event contracts use CREATE2 for predictable addresses:Delegation Permission Model
Three-Tier Authorization System
The EventManager implements a comprehensive permission model:Tier 1: NFT Ownership
- Authority: Current holder of the event NFT
- Scope: Full control over the specific event
- Transferable: Yes, through NFT transfer or tipping competition
- Implementation: Direct check via
eventFactory.ownerOf(eventId)
Tier 2: Event-Specific Delegation
- Authority: Address specifically delegated for an event
- Scope: Same permissions as NFT owner for that event only
- Transferable: No, immutable once set
- Implementation: Minimal proxy deployment with delegation record
Tier 3: Global Whitelist
- Authority: Platform-wide authorized agents
- Scope: Can modify ANY event without specific delegation
- Transferable: No, controlled by protocol owner
- Implementation: Simple mapping with owner-only updates
Delegation Proxy Lifecycle
Proxy Implementation Details
Minimal Proxy Bytecode Analysis
EIP-1167 minimal proxies use a 55-byte bytecode template:- Setup: Copy calldata and prepare for delegatecall
- Delegatecall: Forward all calls to master implementation
- Return: Pass return data back to caller
- Fallback: Handle failed calls appropriately
Storage Layout Considerations
Each minimal proxy maintains its own storage context:- Each proxy has independent storage
- Master implementation provides logic only
- No storage conflicts between proxies
- Gas cost: 4 SSTORE operations (~80,000 gas) during initialization
Advanced Proxy Patterns
Batched Proxy Deployment
CreationWrapper enables atomic event creation with delegation:Global Whitelist Management
Efficient batch operations for platform-wide permissions:Scope-Based Agent System
The protocol includes predefined scope agents with specific permission levels:Deployed Scope Agents
Gas Optimization Strategies
1. Proxy Pattern Selection
Minimal Proxies for Simple State:- Use for delegation records (immutable after creation)
- 55-byte bytecode vs full contract deployment
- Best for high-volume, lightweight contracts
- Use for core protocol contracts requiring upgrades
- Slightly higher deployment cost but upgrade capability
- Best for contracts with evolving requirements
2. Storage Access Patterns
Favor Direct Mappings:3. Event Filtering Optimization
Use indexed parameters for efficient event filtering:Security Considerations
Proxy Security Patterns
Initialization Protection:Permission Validation
Multiple Authorization Levels: The three-tier system provides defense in depth:- NFT ownership (transferable authority)
- Event delegation (immutable assignment)
- Global whitelist (platform administration)
- Delegation records cannot be modified after creation
- No risk of permission escalation through delegation manipulation
- Clear audit trail of permission grants
Design Trade-offs
Advantages
- Gas Efficiency: 80% reduction in delegation setup costs
- Immutable Records: Permanent delegation history
- Flexible Permissions: Three-tier authorization system
- Upgrade Capability: UUPS proxies for core contracts
- Predictable Addresses: CREATE2 for deterministic deployment
Current Limitations (can be improved)
- Immutable Delegations: Cannot modify or revoke specific delegations
- Runtime Overhead: Delegatecall adds ~2,100 gas per proxy call
- Upgrade Risks: UUPS proxies centralize upgrade authority, this will be decentralized through community governance on main net
- Storage Fragmentation: Each proxy maintains separate storage context
- Global Whitelist Power: Platform-wide permissions concentrate authority, this will be decentralized through community governance on main net