LithosProtocol Architecture 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 Architecture Documentation

Table of Contents

  1. Overview
  2. System Architecture
  3. Contract Design
  4. Token Economics
  5. Game Mechanics

Overview

LithosProtocol is a comprehensive Web3 gaming ecosystem built on Ethereum.

Key Features

System Architecture

High-Level Architecture

LithosProtocol Ecosystem
├── Frontend (Web App, Unity Game, Mobile App, Admin Panel)
├── Backend (API Server, Indexer, Cache, Analytics)
└── Blockchain (Smart Contracts, RPC Node, IPFS Storage)

Component Architecture

Core Contracts (12):

Enhanced Contracts (5):

P2 Contracts (1):

Contract Design

Contract Hierarchy

All contracts follow these patterns:

Contract Inheritance

GovernanceToken
├── ERC20Upgradeable
├── ERC20BurnableUpgradeable
├── ERC20PausableUpgradeable
├── ERC20VotesUpgradeable
├── OwnableUpgradeable
├── AccessControlUpgradeable
└── UUPSUpgradeable

Token Economics

Dual Token Model

$GOV (Governance Token)

$PLAY (Utility Token)

Token Flow

Sources (Inflationary):

Sinks (Deflationary):

Game Mechanics

Play-to-Earn System

1. Quest System

2. PvP Battle System

3. Crafting System

4. Asset Progression

Player Data Structure

struct PlayerData {
    uint256 level;
    uint256 experience;
    uint256 pvpWins;
    uint256 pvpLosses;
    uint256 pvpRating;
    uint256 totalDamageDealt;
    uint256 totalDamageTaken;
    bool isActive;
    uint256 lastActivityTime;
}

Security Architecture

Security Layers

  1. Smart Contract Security
    • Reentrancy Protection
    • Input Validation
    • Overflow Protection
    • Access Control
    • Pausable Contracts
    • UUPS Pattern
  2. Economic Security
    • Deflationary Mechanics
    • Inflation Control
    • Dynamic Pricing
    • Sustainable Staking Rewards
    • Balanced Fee Structure
  3. Operational Security
    • Multi-Signature Wallet
    • Time-locks
    • Rate Limiting
    • Event Logging
    • Admin Controls

Security Features by Contract

All 18 contracts implement:

Integration Architecture

Web3 SDK

Structure:

LithosProtocolSDK
├── player: PlayerModule
├── token: TokenModule
├── nft: NFTModule
├── game: GameModule
├── marketplace: MarketplaceModule
├── staking: StakingModule
├── vesting: VestingModule
├── config: NetworkConfig
├── provider: Provider
├── signer: Signer
└── logger: DebugLogger

Supported Networks:

Unity SDK

Platform Support:

Data Flow

Player Action Flow

  1. Player triggers action in frontend
  2. SDK validates and constructs transaction
  3. Signer signs transaction
  4. Transaction sent to network
  5. SDK waits for confirmation
  6. SDK processes result and emits events
  7. Frontend updates UI

Event Flow

  1. Contract emits event
  2. Event stored in transaction receipt
  3. Indexer detects and stores event
  4. SDK subscribes to event type
  5. SDK polls for new events
  6. SDK calls registered callbacks
  7. Frontend updates based on event

Deployment Architecture

Deployment Process

  1. Development
    • Write and test contracts on localhost
    • Use anvil for local blockchain
    • Run comprehensive tests
  2. Testnet Deployment
    • Deploy to Sepolia testnet
    • Test with real wallets
    • Verify all functionality
    • Test upgrade process
  3. Production Deployment
    • Deploy implementation contracts
    • Deploy proxy contracts
    • Initialize contracts
    • Configure parameters
    • Verify on Etherscan
  4. Post-Deployment
    • Set up monitoring
    • Configure indexer
    • Update frontend configuration
    • Announce to community

Deployment Scripts

Script Purpose Networks
DeployContracts.s.sol Deploy core contracts All
DeployAllContracts.s.sol Deploy all contracts (P0) All
DeployCompleteSystem.s.sol Deploy complete system (P0 + P1) All
DeployCompleteSystemWithP2.s.sol Deploy complete system with P2 All

Best Practices

Smart Contract Development

  1. Always use OpenZeppelin libraries
  2. Use UUPS pattern for upgradeable contracts
  3. Implement reentrancy guards
  4. Validate all inputs
  5. Use events for state changes
  6. Follow Solidity style guide
  7. Write comprehensive tests
  8. Use NatSpec comments

Security Best Practices

  1. Principle of Least Privilege
  2. Defense in Depth
  3. Fail Secure
  4. Transparency
  5. Comprehensive Testing
  6. Real-time Monitoring
  7. Incident Response Plan

Gas Optimization

  1. Minimize storage writes
  2. Pack variables
  3. Avoid loops (especially unbounded)
  4. Use calldata instead of memory
  5. Cache values
  6. Use efficient data structures

Troubleshooting

Common Issues

Issue Cause Solution
Transaction reverted Insufficient gas Increase gas limit
Transaction reverted Insufficient balance Get more tokens
Transaction reverted Not approved Approve token spending
Transaction reverted Not owner Use owner account
Transaction reverted Paused Wait for unpause
Event not detected Wrong network Check network
Contract not found Wrong address Verify address

Debugging Tools

  1. Foundry: forge test -vv
  2. Etherscan: Verify contracts
  3. Tenderly: Debug transactions
  4. Hardhat Console: Debug with console.log
  5. Remix: Interactive debugging

Version History

Version Date Changes
1.0.0 2024-01 Initial release
1.1.0 2024-02 Added V2 contracts
1.2.0 2024-03 Added P2 features
1.3.0 2024-04 Documentation updates

License

Apache License 2.0

Built with love by the LithosProtocol Team