# Auditor FAQ

## Frequently Asked Questions for Smart Contract Auditors

---

### General Questions

#### Q1: What is the primary purpose of the Lilith Platform?

The Lilith Platform enables creators to:
1. Tokenize access to their content using ERC-1155 access tokens
2. Issue unique content licenses as ERC-721 NFTs
3. Receive automated royalty distributions
4. Build on-chain reputation through identity staking

---

#### Q2: What are the main entry points for external calls?

**User-facing functions:**
- `AccessToken.purchaseTokens()` - Purchase access tokens
- `ContentLicenseNFT.issueLicense()` - Mint content license
- `CreatorRoyalties.withdrawRoyalty()` - Claim pending royalties
- `IdentityReputation.registerIdentity()` - Register new identity
- `IdentityReputation.stake()` / `unstake()` - Manage stakes

**Admin functions:**
- `*.pause()` / `unpause()` - Emergency controls
- `*.transferOwnership()` - Ownership transfer (two-step)
- `*Upgradeable.upgradeToAndCall()` - Contract upgrades
- `AccessToken.updateTreasury()` - Change fee recipient
- `AccessToken.setPlatformFeePercentage()` - Change fees

**Oracle functions:**
- `IdentityReputation.updateReputation()` - Update scores
- `IdentityReputation.slashStake()` - Slash bad actors
- `IdentityReputation.resolveChallenge()` - Resolve disputes

---

#### Q3: How is ETH handled in the system?

**Inflows:**
1. Token purchases (`purchaseTokens{value: X}()`)
2. Identity staking (`stake{value: X}()`)

**Outflows:**
1. Creator withdrawals (`withdrawRoyalty()` - pull pattern)
2. Pending payment claims (`claimPendingPayment()`)
3. Stake unstaking (`unstake()`)
4. Admin treasury withdrawal (`withdrawToTreasury()`)

**Safety measures:**
- ReentrancyGuard on all external call paths
- CEI (Checks-Effects-Interactions) pattern
- Pull payment pattern instead of push

---

#### Q4: What external dependencies exist?

| Dependency | Usage |
|------------|-------|
| OpenZeppelin Contracts 5.x | ERC standards, access control, security |
| OpenZeppelin Upgradeable 5.x | UUPS upgrade pattern |
| Solidity 0.8.20+ | Native overflow protection |

**No price oracles are used.** Token prices are set by creators.

---

#### Q5: How are upgrades handled?

1. **Pattern:** UUPS (Universal Upgradeable Proxy Standard)
2. **Authorization:** Only owner can initiate
3. **Timelock:** 72 hours delay via TimelockController
4. **Process:**
   - Owner schedules upgrade
   - 72-hour waiting period
   - Community can review
   - Owner executes upgrade
   - Cancel possible during delay

**Storage safety:**
- Storage gap patterns in all contracts
- Initializer functions for state setup
- Storage layout compatibility testing

---

### Security Questions

#### Q6: How is reentrancy prevented?

1. **ReentrancyGuard:** Applied to all functions with external calls
2. **CEI Pattern:** State changes before external calls
3. **Pull Payments:** Users claim funds, not pushed
4. **No callbacks:** ERC-1155 safe transfers with reentrancy guard

**Example pattern:**
```solidity
function withdraw() external nonReentrant {
    uint256 amount = pendingBalance[msg.sender];  // Check
    pendingBalance[msg.sender] = 0;                // Effect
    (bool success,) = msg.sender.call{value: amount}("");  // Interaction
    require(success, "Transfer failed");
}
```

---

#### Q7: How are flash loan attacks prevented?

The `FlashLoanGuard` library tracks the last action block for each user:

```solidity
mapping(address => uint256) private _lastActionBlock;

modifier flashLoanProtected() {
    require(block.number > _lastActionBlock[msg.sender], "SameBlock");
    _lastActionBlock[msg.sender] = block.number;
    _;
}
```

Applied to:
- Token purchases
- License minting
- Staking operations
- Royalty claims

---

#### Q8: What access control model is used?

**Ownable2Step:** Two-step ownership transfer
- Owner proposes new owner
- New owner must accept
- Prevents accidental transfers

**Role-based for specific functions:**
- PAUSER_ROLE: Pause/unpause
- ORACLE_ROLE: Reputation updates
- VERIFIER_ROLE: Content verification

---

#### Q9: How are funds protected in case of compromise?

1. **Multi-sig ownership:** 3/5 Gnosis Safe
2. **Timelock:** 72h delay on critical operations
3. **Pause capability:** Emergency stop
4. **Pull payments:** Users control withdrawals
5. **No infinite approvals:** Standard transfer patterns
6. **Monitoring:** On-chain alerts for sensitive events

---

#### Q10: What happens if the owner key is compromised?

**Immediate impact:**
- Attacker can pause contracts
- Attacker can change fees (bounded)
- Attacker cannot immediately upgrade (72h delay)
- Attacker cannot directly access user funds

**Response:**
1. Alert on ownership transfer detected
2. Cancel any scheduled operations
3. Rotate keys via multi-sig
4. Deploy patched contracts if needed

---

### Economic Questions

#### Q11: What are the fee structures?

| Fee Type | Default | Maximum | Recipient |
|----------|---------|---------|-----------|
| Platform fee | 2.5% | 10% | Treasury |
| Royalties | Creator-defined | 25% | Creator |

**Fee calculation:**
```solidity
uint256 platformFee = amount * platformFeePercentage / 10000;
uint256 creatorAmount = amount - platformFee;
```

---

#### Q12: How are royalties distributed?

1. Marketplace calls `distributeRoyalty(tokenId, amount)`
2. Platform fee deducted
3. Net amount added to creator's pending balance
4. Creator calls `withdrawRoyalty()` to claim

**Only authorized marketplaces can trigger distributions.**

---

#### Q13: What is the staking mechanism?

**Purpose:** Reputation collateral

**Operations:**
- `stake{value: amount}()` - Add stake
- `unstake(amount)` - Remove stake (with checks)
- `slashStake(user, amount, reason)` - Penalty (oracle only)

**Constraints:**
- Minimum stake: 0.01 ETH
- Cannot unstake below minimum while registered
- Slashing requires oracle authorization

---

### Technical Questions

#### Q14: What Solidity version and why?

**Version:** 0.8.20+

**Reasons:**
- Native overflow/underflow protection
- Custom errors for gas efficiency
- Latest security patches
- UUPS pattern compatibility

---

#### Q15: Are there any known gas optimization opportunities?

Yes, some areas identified:
1. Batch operations could use unchecked loops
2. Some storage reads could be cached
3. Events could be more gas-efficient

**Note:** Security was prioritized over gas optimization.

---

#### Q16: How is randomness handled?

**No on-chain randomness is used.**

All operations are deterministic based on:
- User inputs
- Block properties (number, timestamp)
- Contract state

---

#### Q17: What are the batch operation limits?

| Operation | Recommended Limit | Gas Limit |
|-----------|-------------------|-----------|
| Batch license mint | 100 | ~15M gas |
| Batch transfer | 50 | ~10M gas |

Limits enforced in contract to prevent DoS.

---

### Testing Questions

#### Q18: What testing has been done?

1. **Unit tests:** 100% function coverage
2. **Integration tests:** Cross-contract interactions
3. **Security tests:**
   - Reentrancy scenarios
   - Access control bypass attempts
   - Flash loan attack simulations
   - CEI pattern verification
   - DoS resistance
4. **Fuzzing:** Foundry fuzz tests on critical paths
5. **Invariant tests:** Economic invariants verified

---

#### Q19: What static analysis tools were used?

- Slither (static analyzer)
- Mythril (symbolic execution)
- Solhint (linting)
- Hardhat coverage

---

#### Q20: Is there a deployed testnet version?

Yes, contracts are deployed on:
- Sepolia testnet
- Goerli testnet (deprecated, migrating)

Testnet addresses available in deployment artifacts.

---

### Contact Information

For questions during the audit:

- **Technical Lead:** [Contact via secure channel]
- **Response Time:** < 4 hours during business hours
- **Secure Document Sharing:** [Encrypted channel]
- **Code Repository:** Private GitHub (access provided)

---

### Document Versions

| Document | Version | Last Updated |
|----------|---------|--------------|
| Architecture | 1.0 | 2024-Q4 |
| Threat Model | 1.0 | 2024-Q4 |
| Trust Assumptions | 1.0 | 2024-Q4 |
| This FAQ | 1.0 | 2024-Q4 |
