LithosProtocol Security Documentation

Built to Last. Built for Play. A comprehensive Web3 gaming ecosystem that combines NFTs, on-chain assets, and Play-to-Earn (P2E) mechanics.

LithosProtocol Security Documentation

Table of Contents

  1. Security Overview
  2. Security Features
  3. Smart Contract Security
  4. Economic Security
  5. Operational Security
  6. Security Best Practices
  7. Incident Response
  8. Audit Information

Security Overview

LithosProtocol is designed with security as a first-class concern. This document outlines the comprehensive security measures implemented across all layers of the protocol.

Security Philosophy

  1. Defense in Depth: Multiple layers of security controls
  2. Principle of Least Privilege: Minimal necessary permissions
  3. Fail Secure: Default to secure state on errors
  4. Transparency: All security-relevant actions are auditable
  5. Continuous Improvement: Regular security reviews and updates

Security Layers

┌─────────────────────────────────────────────────────────────────────┐
│                    SECURITY ARCHITECTURE                              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │                    LAYER 1: BLOCKCHAIN                          │    │
│  │  ┌─────────────────┐  ┌─────────────────┐                  │    │
│  │  │  Smart Contracts │  │  Consensus       │                  │    │
│  │  │  Security        │  │  Security        │                  │    │
│  │  └─────────────────┘  └─────────────────┘                  │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │                    LAYER 2: ECONOMIC                            │    │
│  │  ┌─────────────────┐  ┌─────────────────┐                  │    │
│  │  │  Tokenomics     │  │  Incentive       │                  │    │
│  │  │  Security        │  │  Design          │                  │    │
│  │  └─────────────────┘  └─────────────────┘                  │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │                    LAYER 3: OPERATIONAL                         │    │
│  │  ┌─────────────────┐  ┌─────────────────┐                  │    │
│  │  │  Access Control  │  │  Monitoring      │                  │    │
│  │  │  & Governance    │  │  & Alerting      │                  │    │
│  │  └─────────────────┘  └─────────────────┘                  │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │                    LAYER 4: INFRASTRUCTURE                     │    │
│  │  ┌─────────────────┐  ┌─────────────────┐                  │    │
│  │  │  Network         │  │  Storage         │                  │    │
│  │  │  Security        │  │  Security        │                  │    │
│  │  └─────────────────┘  └─────────────────┘                  │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │                    LAYER 5: APPLICATION                         │    │
│  │  ┌─────────────────┐  ┌─────────────────┐                  │    │
│  │  │  Input           │  │  Output          │                  │    │
│  │  │  Validation      │  │  Validation      │                  │    │
│  │  └─────────────────┘  └─────────────────┘                  │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Security Features

Smart Contract Security Features

Feature Description Implementation
Reentrancy Protection Prevents reentrancy attacks OpenZeppelin ReentrancyGuard
Input Validation Validates all function inputs require() statements
Overflow Protection Prevents arithmetic overflows Solidity 0.8+ built-in
Access Control Role-based permissions OpenZeppelin AccessControl
Pausable Contracts Emergency stop capability OpenZeppelin Pausable
UUPS Proxy Pattern Secure upgradeability ERC1967 Proxy
Event Logging Full audit trail emit events

Economic Security Features

Feature Description Implementation
Deflationary Mechanics Token sinks for supply control AdvancedTokenSinks
Inflation Control Controlled token minting GameLogic
Dynamic Pricing Market-based adjustments DynamicTokenomics
Sustainable Staking Balanced reward rates StakingContract
Balanced Fees Fair fee structure Marketplace

Operational Security Features

Feature Description Implementation
Multi-Signature Wallet Multi-party control MultiSigWallet
Time-locks Delayed critical operations Future implementation
Rate Limiting Transaction throttling Future implementation
Monitoring Real-time contract monitoring Future implementation
Admin Controls Emergency interventions Owner functions

Smart Contract Security

Reentrancy Protection

All contracts use OpenZeppelin ReentrancyGuard to prevent reentrancy attacks:

import "@openzeppelin/contracts-upgradeable/security/ReentrancyGuardUpgradeable.sol";

contract MyContract is ReentrancyGuardUpgradeable {
    function withdraw() external nonReentrant {
        // This function cannot be re-entered
        (bool success, ) = msg.sender.call{value: address(this).balance}("");
        require(success, "Transfer failed");
    }
}

Contracts with Reentrancy Protection:

Input Validation

All contracts validate inputs with require statements:

function transfer(address to, uint256 amount) external {
    require(to != address(0), "Cannot transfer to zero address");
    require(amount > 0, "Amount must be greater than zero");
    require(balanceOf[msg.sender] >= amount, "Insufficient balance");
    // ... transfer logic
}

Validation Rules:

Overflow Protection

Solidity 0.8+ has built-in overflow protection:

// SPDX-License-Identifier: Apache-2.0
pragma solidity 0.8.19;

// All arithmetic operations automatically check for overflow
// and revert if overflow would occur
uint256 public value;

function add(uint256 amount) external {
    value += amount; // Reverts on overflow
}

Protected Operations:

Access Control

All contracts use OpenZeppelin AccessControl for role-based permissions:

import "@openzeppelin/contracts-upgradeable/access/AccessControlUpgradeable.sol";

contract MyContract is AccessControlUpgradeable {
    bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");
    bytes32 public constant ADMIN_ROLE = keccak256("ADMIN_ROLE");
    
    function mint(address to, uint256 amount) external onlyRole(MINTER_ROLE) {
        // Only addresses with MINTER_ROLE can call this
    }
    
    function grantMinterRole(address account) external onlyRole(ADMIN_ROLE) {
        _grantRole(MINTER_ROLE, account);
    }
}

Roles by Contract:

Contract Roles
GovernanceToken DEFAULT_ADMIN_ROLE, MINTER_ROLE, PAUSER_ROLE
UtilityToken DEFAULT_ADMIN_ROLE, MINTER_ROLE, PAUSER_ROLE
GameAssetNFT DEFAULT_ADMIN_ROLE, MINTER_ROLE, PAUSER_ROLE
GameResourceNFT DEFAULT_ADMIN_ROLE, MINTER_ROLE, PAUSER_ROLE
GameLogic DEFAULT_ADMIN_ROLE, PAUSER_ROLE, GAME_ROLE
Marketplace DEFAULT_ADMIN_ROLE, PAUSER_ROLE, FEE_MANAGER_ROLE
StakingContract DEFAULT_ADMIN_ROLE, PAUSER_ROLE, POOL_MANAGER_ROLE
Vesting DEFAULT_ADMIN_ROLE, PAUSER_ROLE, SCHEDULE_MANAGER_ROLE
MultiSigWallet OWNER_ROLE

Pausable Contracts

All contracts implement Circuit Breaker pattern:

import "@openzeppelin/contracts-upgradeable/security/PausableUpgradeable.sol";

contract MyContract is PausableUpgradeable {
    function pause() external onlyRole(PAUSER_ROLE) {
        _pause();
    }
    
    function unpause() external onlyRole(PAUSER_ROLE) {
        _unpause();
    }
    
    function sensitiveOperation() external whenNotPaused {
        // This function can only be called when the contract is not paused
    }
}

Emergency Procedures:

  1. Detect critical vulnerability
  2. Owner calls pause() on affected contract
  3. All state-changing functions disabled
  4. Fix vulnerability
  5. Owner calls unpause()

UUPS Proxy Pattern

All contracts use UUPS (Universal Upgradeable Proxy Standard) for secure upgradeability:

import "@openzeppelin/contracts-upgradeable/proxy/utils/UUPSUpgradeable.sol";

contract MyContract is UUPSUpgradeable {
    function _authorizeUpgrade(address newImplementation)
        internal
        override
        onlyRole(UPGRADER_ROLE)
    {
        // Only addresses with UPGRADER_ROLE can authorize upgrades
    }
}

Upgrade Process:

  1. Deploy new implementation contract
  2. Test thoroughly on testnet
  3. Announce upgrade window
  4. Call upgradeTo(newImplementation) on proxy
  5. Verify new functionality

Upgrade Safety:

Event Logging

All contracts emit events for state changes:

contract MyContract {
    event ValueChanged(uint256 oldValue, uint256 newValue);
    event ActionPerformed(address indexed performer, uint256 value);
    
    uint256 public value;
    
    function setValue(uint256 newValue) external {
        uint256 oldValue = value;
        value = newValue;
        emit ValueChanged(oldValue, newValue);
    }
    
    function performAction(uint256 value) external {
        // ... perform action
        emit ActionPerformed(msg.sender, value);
    }
}

Event Coverage:

Economic Security

Token Economics Security

Dual Token Model:

Security Features:

Deflationary Mechanics

Token Sinks:

Sink Type Percentage Purpose
Crafting 10% Crafting fees
Marketplace 2.5% Transaction fees
Repair 5% Repair costs
Premium 10% Premium features
Direct Burn 100% Manual burns

Implementation:

// AdvancedTokenSinks.sol
function applySink(SinkType sinkType, uint256 amount) external returns (uint256) {
    TokenSink storage sink = tokenSinks[sinkType];
    uint256 burnAmount = (amount * sink.percentage) / 10000;
    IERC20(utilityToken).burn(burnAmount);
    return burnAmount;
}

Inflation Control

Controlled Minting:

Minting Limits:

Dynamic Pricing

DynamicTokenomics Contract:

Formula:

basePrice * (1 + activityFactor) * (1 + rarityFactor) * (1 + marketFactor) * (1 + supplyDemandFactor)

Sustainable Staking

StakingContract:

Sustainability Features:

Operational Security

Multi-Signature Wallet

MultiSigWallet Contract:

Configuration:

// Initialize with 3 owners and threshold of 2
address[] memory owners = [owner1, owner2, owner3];
multiSig.initialize(owners, 2);

Workflow:

  1. Owner submits transaction
  2. Other owners approve transaction
  3. When threshold is met, transaction can be executed
  4. Any owner can execute the transaction

Access Control

Role Hierarchy:

DEFAULT_ADMIN_ROLE (Highest)
├── MINTER_ROLE
├── PAUSER_ROLE
├── UPGRADER_ROLE
├── GAME_ROLE
├── FEE_MANAGER_ROLE
├── POOL_MANAGER_ROLE
└── SCHEDULE_MANAGER_ROLE

Role Assignment:

Monitoring and Alerting

Monitoring Plan:

Alert Types:

Admin Controls

Emergency Functions:

Control Flow:

  1. Detect issue
  2. Assess severity
  3. Execute emergency action
  4. Notify stakeholders
  5. Resolve issue
  6. Restore normal operation

Security Best Practices

Smart Contract Development

  1. Use OpenZeppelin Libraries
    • Always use audited, battle-tested libraries
    • Follow OpenZeppelin patterns
  2. Implement Reentrancy Guards
    • Use ReentrancyGuard on all state-changing functions
    • Mark functions as nonReentrant
  3. Validate All Inputs
    • Check for zero addresses
    • Check for positive amounts
    • Check for valid ranges
    • Check array bounds
  4. Use Events
    • Emit events for all state changes
    • Include relevant data in events
    • Use indexed parameters for filtering
  5. Follow Solidity Style Guide
    • Consistent naming conventions
    • Clear code structure
    • Comprehensive comments
  6. Write Comprehensive Tests
    • Test all functions
    • Test edge cases
    • Test error conditions
    • Maintain high test coverage
  7. Use NatSpec Comments
    • Document all functions
    • Include @notice, @dev, @param, @return tags
    • Use /// for single-line comments
    • Use /** … */ for multi-line comments

Security Review Checklist

Before Deployment:

After Deployment:

Common Vulnerabilities and Mitigations

Vulnerability Mitigation
Reentrancy ReentrancyGuard, Checks-Effects-Interactions pattern
Integer Overflow Solidity 0.8+ built-in protection
Integer Underflow Solidity 0.8+ built-in protection
Front-Running Use commit-reveal, time-locks, or private mempools
Access Control Role-based permissions, principle of least privilege
Oracle Manipulation Use Chainlink, multiple oracles, median calculations
Timestamp Dependence Use block.number instead of block.timestamp when possible
TX Origin Use msg.sender instead of tx.origin
Delegatecall Use UUPS proxy pattern, validate implementation
Self-Destruct Use UUPS proxy pattern, no self-destruct in implementation

Incident Response

Incident Response Plan

Phase 1: Detection and Assessment

  1. Detect security incident
  2. Assess severity (Critical/High/Medium/Low)
  3. Identify affected systems
  4. Determine root cause

Phase 2: Containment

  1. Isolate affected systems
  2. Pause vulnerable contracts
  3. Stop further damage
  4. Preserve evidence

Phase 3: Eradication

  1. Remove malicious code/access
  2. Patch vulnerabilities
  3. Update systems
  4. Verify fixes

Phase 4: Recovery

  1. Restore normal operation
  2. Unpause contracts
  3. Monitor for issues
  4. Verify recovery

Phase 5: Lessons Learned

  1. Document incident
  2. Identify improvements
  3. Update processes
  4. Train team

Incident Severity Levels

Level Description Response Time
Critical Active exploitation, fund loss, major outage Immediate
High Vulnerability discovered, potential for exploitation < 1 hour
Medium Security issue, limited impact < 24 hours
Low Minor issue, no immediate impact < 1 week

Incident Response Team

Role Responsibilities
Incident Commander Overall coordination, decision making
Security Lead Technical assessment, mitigation
Communications Lead Internal and external communications
Operations Lead System operations, monitoring
Legal Lead Legal considerations, compliance

Communication Plan

Internal Communication:

External Communication:

Communication Timeline:

Audit Information

Audit Status

Audit Scope

Contracts to be Audited:

  1. GovernanceToken
  2. UtilityToken
  3. GameAssetNFT
  4. GameResourceNFT
  5. GameLogic
  6. GameLogicV2
  7. Marketplace
  8. MarketplaceV2
  9. StakingContract
  10. Vesting
  11. AdvancedTokenSinks
  12. DynamicTokenomics
  13. GameOracle
  14. PlayerDataStorage
  15. SignatureVerifier
  16. MultiSigWallet

Audit Focus Areas:

Audit Preparation

Preparation Checklist:

Audit Deliverables:

Previous Audits

Date Firm Scope Findings Status
N/A N/A N/A N/A N/A

Security Tools

Static Analysis

Tool Purpose Usage
Slither Static analysis for Solidity slither .
MythX Security analysis platform Web interface
CertiK Formal verification Web interface
Solhint Solidity linter solhint 'contracts/**/*.sol'

Dynamic Analysis

Tool Purpose Usage
Echidna Fuzzing for smart contracts echidna-test .
Manticore Symbolic execution manticore .
Tenderly Transaction debugging Web interface
Etherscan Contract verification Web interface

Monitoring

Tool Purpose Usage
Tenderly Contract monitoring Web interface
Forta Threat detection Web interface
OpenZeppelin Defender Security operations Web interface
Chainlink Oracle monitoring Web interface

Security Checklist for Developers

Before Commit

Before Merge

Before Deployment

Security Contacts

Purpose Contact Response Time
Security Issues security@lithosprotocol.io < 24 hours
General Support support@lithosprotocol.io < 48 hours
Bug Bounty security@lithosprotocol.io < 24 hours
Press Inquiries press@lithosprotocol.io < 48 hours

Bug Bounty Program

Status: Coming Soon

Scope:

Rewards:

Rules:

License

Apache License 2.0

Built with love by the LithosProtocol Team