Overview#
This document outlines the trust assumptions made in the Lilith Platform smart contract system. Auditors should validate these assumptions and identify any cases where they may be violated.
1. Blockchain Assumptions#
1.1 Ethereum Network#
- Assumption: Ethereum maintains consensus and doesn't experience long reorganizations
- Impact if violated: Transaction finality issues, potential double-spends
- Mitigation: Wait for sufficient confirmations before considering transactions final
1.2 Block Properties#
- Assumption:
block.timestampis accurate within ~15 seconds - Impact if violated: Timing-based logic may be manipulated
- Mitigation: No critical time-sensitive operations use exact timing
1.3 Gas Limits#
- Assumption: Block gas limit remains sufficient for contract operations
- Impact if violated: Some operations may become impossible
- Mitigation: Batch size limits, gas-efficient implementations
2. Access Control Assumptions#
2.1 Owner (Multi-Sig)#
- Who: Gnosis Safe multi-sig with 3/5 threshold
- Trust level: FULLY TRUSTED
- Assumption: Majority of signers are honest and secure
- Powers:
- Upgrade contract implementations
- Change treasury addresses
- Modify fee percentages
- Pause/unpause contracts
- Grant/revoke roles
- Constraints:
- 72-hour timelock on upgrades
- Maximum fee limits
- Cannot directly access user funds
2.2 Pauser Role#
- Who: Security team members, automated monitoring
- Trust level: TRUSTED
- Assumption: Will only pause in genuine emergencies
- Powers:
- Pause contract operations
- Unpause contract operations
- Constraints:
- Cannot modify state
- Cannot upgrade contracts
- Cannot access funds
2.3 Oracle Role#
- Who: Backend reputation service
- Trust level: TRUSTED
- Assumption: Provides accurate reputation updates based on off-chain data
- Powers:
- Update user reputation scores
- Resolve challenges
- Constraints:
- Cannot directly slash stakes (requires proof)
- Score changes are bounded
- Actions are logged for audit
2.4 Verifier Role#
- Who: Content verification team
- Trust level: SEMI-TRUSTED
- Assumption: Verifies content authenticity honestly
- Powers:
- Mark content as verified
- Constraints:
- Cannot modify ownership
- Cannot create licenses
- Verification is informational only
3. External Dependency Assumptions#
3.1 OpenZeppelin Contracts#
- Version: 5.x
- Assumption: Audited and secure implementations
- Used for:
- ERC-20, ERC-721, ERC-1155 implementations
- Access control (Ownable2Step)
- Security (ReentrancyGuard, Pausable)
- Upgrades (UUPS pattern)
3.2 Solidity Compiler#
- Version: 0.8.20+
- Assumption: Compiler produces correct bytecode
- Notable features relied upon:
- Native overflow/underflow checking
- ABI encoding/decoding
- Modifier behavior
3.3 Ethereum Clients#
- Assumption: RPC providers return accurate blockchain data
- Impact if violated: Incorrect state reads, failed transactions
4. Economic Assumptions#
4.1 Token Pricing#
- Assumption: Creator-set prices are rational
- Impact if violated: None (creators bear the risk of poor pricing)
4.2 Fee Sustainability#
- Assumption: Platform fees cover operational costs
- Current fee: 2.5% (configurable up to 10%)
4.3 Staking Incentives#
- Assumption: Stake requirements deter bad actors
- Minimum stake: 0.01 ETH
- Slashing: Up to 100% for severe violations
5. User Behavior Assumptions#
5.1 Key Security#
- Assumption: Users secure their private keys
- Impact if violated: Individual user fund loss
- Not our responsibility: Key compromise is user responsibility
5.2 Transaction Verification#
- Assumption: Users verify transactions before signing
- Impact if violated: Phishing attacks may succeed
- Mitigation: Clear event emissions, standard interfaces
5.3 Contract Interaction#
- Assumption: Users interact through known interfaces
- Impact if violated: May miss important checks
- Mitigation: Standard function signatures, require statements
6. Marketplace Assumptions#
6.1 Authorized Marketplaces#
- Assumption: Only trusted marketplaces are authorized
- Trust level: SEMI-TRUSTED
- Powers:
- Trigger royalty distributions
- Report sale amounts
- Constraints:
- Cannot bypass royalties (on authorized sales)
- Authorization is revocable
- On-chain enforcement
6.2 Sale Reporting#
- Assumption: Authorized marketplaces report accurate sale amounts
- Impact if violated: Incorrect royalty distributions
- Mitigation: Post-sale verification possible, marketplace reputation
7. Upgrade Assumptions#
7.1 Timelock Controller#
- Assumption: 72-hour delay is sufficient for community review
- Impact if violated: Malicious upgrades could execute
- Monitoring: On-chain alerts for scheduled operations
7.2 Storage Layout#
- Assumption: Upgrades maintain storage compatibility
- Impact if violated: Data corruption
- Mitigation: Storage gap patterns, upgrade tests
7.3 Bytecode Verification#
- Assumption: Deployed bytecode matches source code
- Impact if violated: Hidden functionality
- Mitigation: Source verification on Etherscan
8. Invariants#
The following invariants should always hold:
Contract State Invariants#
solidity
// AccessToken
assert(tokenCounter >= 0);
assert(platformFeePercentage <= MAX_FEE);
assert(treasury != address(0));
// ContentLicenseNFT
assert(ownerOf(tokenId) != address(0) || !exists(tokenId));
assert(contentHashes[tokenId] != "" || !exists(tokenId));
// CreatorRoyalties
assert(pendingRoyalties[creator] <= address(this).balance);
assert(sum(pendingRoyalties) <= address(this).balance);
// IdentityReputation
assert(stakes[user] >= minimumStake || !isRegistered(user));
assert(reputationScore[user] >= 0 && reputationScore[user] <= maxScore);
Economic Invariants#
solidity
// Platform fees are correctly calculated
assert(platformFee == totalAmount * platformFeePercentage / 10000);
// Creator receives correct amount
assert(creatorAmount == totalAmount - platformFee);
// Staking is correctly tracked
assert(totalStaked == sum(individualStakes));
// Withdrawals don't exceed balances
assert(withdrawAmount <= pendingRoyalties[user]);
9. Known Limitations#
9.1 Off-Chain Transfers#
- Limitation: Cannot enforce royalties on off-chain transfers
- Impact: Potential royalty evasion
- Status: Accepted limitation (industry-wide issue)
9.2 Oracle Trust#
- Limitation: Reputation relies on centralized oracle
- Impact: Single point of failure
- Future mitigation: Multi-oracle implementation
9.3 Upgrade Centralization#
- Limitation: Owner controls upgrades
- Impact: Requires trust in owner
- Mitigation: Multi-sig + timelock + monitoring
10. Violation Response#
If any trust assumption is violated:
- Detection: Monitoring alerts trigger
- Assessment: Severity classification (P0-P3)
- Response: See incident response plan
- Recovery: Contract pause if necessary
- Post-mortem: Document and improve