01 - Systemarchitektur¶
Contract Landscape, Option-B Pattern, Interaktionsdiagramm
Architekturmuster: Option B (State/Funds Separation)¶
Das System trennt strikt zwischen Fund-Holding und Logik-Contracts:
┌─────────────────────────────────────────────────────┐
│ FUND LAYER │
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ ReserveVault │ (USDT) │ CharityVault │ (USDT) │
│ │ V2 │ │ V2 │ │
│ └──────────────┘ └──────────────┘ │
│ │
├─────────────────────────────────────────────────────┤
│ LOGIC LAYER │
│ │
│ ┌────────────┐ ┌────────────┐ ┌──────────────┐ │
│ │GameManager │ │GameTreasury│ │ Settlement │ │
│ │ V3 │ │ V2 │ │ V5 │ │
│ └────────────┘ └────────────┘ └──────────────┘ │
│ │
│ ┌────────────┐ ┌────────────┐ ┌──────────────┐ │
│ │ PrizeVault │ │AffiliateV. │ │ ClaimRouter │ │
│ │ V3 │ │ V2 │ │ V2 │ │
│ └────────────┘ └────────────┘ └──────────────┘ │
│ │
│ ┌────────────┐ │
│ │VRFReceiver │ │
│ │ V3 │ │
│ └────────────┘ │
│ │
├─────────────────────────────────────────────────────┤
│ EXTERNAL │
│ Chainlink VRF V2+ │ Multicall3 │ SAFE Multisig │
└─────────────────────────────────────────────────────┘
Kernprinzip: Nur ReserveVault und CharityVault halten USDT. Alle anderen Contracts sind reine State-Machines ohne Token-Besitz.
Contract Landscape¶
| Contract | Version | Zweck | Hält USDT | Solidity |
|---|---|---|---|---|
| ReserveVaultV2 | V2 | Einziger Fund Holder | Ja | 0.8.24 |
| GameManagerV3 | V3 | Ticket-Kauf + RNG | Nein | 0.8.24 |
| GameTreasuryV2 | V2 | Accounting (Fee Splits) | Nein | 0.8.24 |
| SettlementV5 | V5 | Tägliche Abrechnung | Nein | 0.8.24 |
| PrizeVaultV3 | V3 | Gewinn-Claims (State) | Nein | 0.8.24 |
| AffiliateVaultV2 | V2 | Affiliate-Provisionen (State) | Nein | 0.8.24 |
| CharityVaultV2 | V2 | Charity Fund Management | Ja (sekundär) | 0.8.24 |
| ClaimRouterV2 | V2 | Batch Claims via Relayer | Nein | 0.8.24 |
| VRFReceiverV3 | V3 | Chainlink VRF Consumer | Nein | 0.8.24 |
| MockUSDT | - | Test-Token (nur Testnet) | - | 0.8.20 |
Interaktionsdiagramm¶
Ticket-Kauf Flow¶
Player ──EIP-712 Signatur──► Backend (Relayer)
│
▼
GameManagerV3
├── Nonce-Check
├── Settlement Guard
├── Affiliate Binding
│
▼
GameTreasuryV2
├── Fee Split berechnen
│ ├── 67.5% → Pot
│ ├── 27.5% → Fee
│ └── 5.0% → Rollover
│
▼
ReserveVaultV2
└── depositFrom(player, amount)
└── USDT.transferFrom(player → vault)
Settlement Flow (täglich)¶
Backend (Operator) ──commitMerkleSettlement──► SettlementV5
│
┌─────────────────────────────┤
│ │
▼ ▼
GameTreasuryV2 PrizeVaultV3
├── applySettlement() └── setMerkleRoot()
├── applyJackpotSettlement()
└── takeFeeForDay()
│
▼
ReserveVaultV2
├── payFee(feeSafe)
├── payCharity(charityVault)
└── [Prize payouts via claims]
Claim Flow¶
Player ──EIP-712 ClaimPermit──► Backend (Relayer)
│
▼
ClaimRouterV2
├── Signatur prüfen
├── Claims Hash prüfen
│
▼
Multicall3
├── PrizeVaultV3.claimMerkle()
└── AffiliateVaultV2.claimAffiliate()
│
▼
SettlementV5
└── payoutFromPrizeVault()
│
▼
ReserveVaultV2
└── payPrize(player, amount)
└── USDT.transfer(player)
Versionierungsstrategie¶
Das System verwendet eine Migration-Ready Architektur:
- Jeder Contract hat einen Konstruktor mit Initialwerten für State-Übernahme
- One-Time-Setter erlauben Cross-Contract-Wiring nach Deployment
- SAFE-Owner kann neue Versionen deployen und umverdrahten
Aktuelle Versionshistorie:
| Contract | V1 | V2 | V3 | V4 | V5 |
|---|---|---|---|---|---|
| ReserveVault | Legacy | Prod | - | - | - |
| GameManager | Legacy | Legacy | Prod | - | - |
| GameTreasury | Legacy | Prod | - | - | - |
| Settlement | Legacy | Legacy | Legacy | Legacy | Prod |
| PrizeVault | Legacy | Legacy | Prod | - | - |
| AffiliateVault | Legacy | Prod | - | - | - |
| CharityVault | Legacy | Prod | - | - | - |
| ClaimRouter | Legacy | Prod | - | - | - |
| VRFReceiver | Legacy | Legacy | Prod | - | - |
Externe Abhängigkeiten¶
| Dependency | Version | Zweck |
|---|---|---|
| OpenZeppelin | 5.x | ReentrancyGuard, Ownable, MerkleProof, SafeERC20 |
| Chainlink VRF | V2+ | Verifizierbare Zufallszahlen |
| Multicall3 | Standard | Batch-Ausführung von Claims |
| SAFE | Multisig | Owner aller Contracts |
| USDT (ERC-20) | 6 Decimals | Zahlungs-Token |
Netzwerk-Konfiguration¶
| Parameter | Arbitrum Sepolia | Arbitrum One |
|---|---|---|
| Chain ID | 421614 | 42161 |
| RPC | sepolia-rollup.arbitrum.io/rpc |
arb1.arbitrum.io/rpc |
| Block Explorer | sepolia.arbiscan.io |
arbiscan.io |
| VRF Coordinator | Chainlink Sepolia | Chainlink Mainnet |
| USDT | MockUSDT (deployed) | Official USDT |
| Multicall3 | Standard Address | Standard Address |
Audit-Kritische Versprechen¶
- Funds Safety: Nur ReserveVault hält USDT - kein Logic-Contract hat Token-Zugriff
- Merkle Integrity: Merkle Roots sind nach Settlement immutable
- Double-Claim Prevention: Jeder Claim kann nur einmal ausgeführt werden
- Sequential Settlement: Tage werden strikt sequentiell abgerechnet
- Emergency Kill-Switch: SAFE kann alle Payouts sofort stoppen
- Fee Immutability: Fee-Split-Ratios sind Constants (nicht änderbar)