# Genesis - Technical Documentation ### 1. Architecture Overview The Genesis Protocol utilizes a decentralized, immutable Factory-Child architectural pattern. The system is composed of two primary smart contracts designed to ensure fund safety, accurate token distribution, and transparent vesting schedules. * GenesisFactory (Singleton): The administrative hub responsible for deploying individual fundraising pools. It utilizes a private deployment mechanism (`onlyOwner`) to ensure only verified, vetted projects are launched on the platform * GenesisPool (Instance): An independent, self-contained smart contract deployed for each IDO. Each pool holds its own state, funds, and vesting logic, isolating risk and ensuring modular security.
### 2. Security Mechanisms & Auditing Standards
Security is the cornerstone of the Genesis architecture. The contracts implement industry-standard protections provided by OpenZeppelin.\ ╔══════════════════════════════════════════════════════════════╗\ ║ GENESIS PROTOCOL v1.0 ║\ ╠══════════════════════════════════════════════════════════════╣\ ║ ║\ ║ \[FACTORY] ──────────► \[POOL INSTANCE 0x12...F] ║\ ║ │ │ ║\ ║ │ ├── \[LOCKER] 🔒 (Active) ║\ ║ └─► Validated ├── \[VESTING] ⏳ (Pending) ║\ ║ └── \[SWAP] 🔄 (Ready) ║\ ║ ║\ ║ SECURITY METRICS: ║\ ║ \[████████████████████] 100% Non-Reentrant ║\ ║ \[████████████████████] 100% Overflow Protected ║\ ║ \[████████████░░░░░░░░] 60% Audit Coverage ║\ ║ ║\ ╚══════════════════════════════════════════════════════════════╝ #### 2.1. Anti-Reentrancy Protection All functions involving state changes and fund transfers (`invest`, `claim`, `finalizePool`) are secured with the `nonReentrant` modifier. This prevents malicious actors from executing recursive calls to drain contract liquidity. #### 2.2. Decimal Precision & Normalization The protocol natively handles discrepancies between token decimals (e.g., investing USDT (6 decimals) vs. Sale Token (18 decimals)). * Mechanism: The `calculateTokenAmount` function automatically detects decimal precision. * Logic: If the Sale Token has higher precision than the Investment Token, the contract scales the amount upwards using `10 ** (saleDecimals - investDecimals)` to ensure the user receives the mathematically correct allocation #### 2.3. Emergency Withdrawal Safety Lock Unlike standard launchpads, Genesis implements a Restricted Emergency Withdraw pattern. * The Feature: The `emergencyWithdrawToken` function allows the recovery of airdropped or mistakenly sent tokens. * The Constraint: To prevent "rug pulls," the contract strictly forbids the withdrawal of `InvestTokens` (User Funds) before the pool is finalized. This cryptographic guarantee ensures that the administrator cannot bypass the sale logic to seize user funds during an active sale. All token transfers utilize the `SafeERC20` wrapper library. This ensures compatibility with non-standard ERC20 tokens (like USDT on BSC) that may not return a boolean value upon transfer, preventing silent failures and stuck funds. ### 3. Functional Specifications #### 3.1. Whitelisting System The protocol supports a granular `whitelistEnabled` mode. When active, only addresses explicitly added via `setWhitelist` can interact with the `invest` function. This allows for Tier-based or KYC-compliant fundraising rounds. #### 3.2. Advanced Vesting Engine Genesis features a flexible vesting engine stored in the `VestingSettings` struct, supporting both immediate TGE (Token Generation Event) releases and linear cyclic unlocking. * Formula: `Claimable = (TotalAllocation * (TGE% + (CyclesPassed * Cycle%))` * Constraint: The logic strictly caps the release at 100% to effectively prevent overflow errors #### 3.3. Finalization & Settlement Upon sale conclusion, the `finalizePool` function triggers a dual-settlement process: 1. Fund Routing: Collected funds (BNB/BUSD) are securely transferred to the project owner 2. Unsold Token Burn/Return: Any tokens not sold during the IDO are automatically calculated and returned to the project owner, ensuring no tokens are "locked forever" in the contract. ## 4: Mathematical & Visual Appendix
### 1. Core Mathematical Models The Genesis Protocol is governed by deterministic mathematical laws enforced by the EVM (Ethereum Virtual Machine). Below are the core formulas defining the economic logic. #### 1.1. Cross-Decimal Rate Normalization To support diverse assets (e.g., investing `USDC` with 6 decimals vs. `MTS` with 18 decimals), the protocol uses a dynamic scaling formula. This ensures the exchange rate $$R$$ remains constant regardless of token precision.
Where: * $$Tallocation​$$: Final amount of Sale Tokens user receives. * $$Ainvest​$$: Amount of Investment Tokens sent by user. * $$R$$: Sale Rate (e.g., 1 BNB = 4000 Tokens). * $$Dsale​$$: Decimals of the project token (usually 18). * $$Dinvest​$$: Decimals of the investment currency (e.g., 18 for BNB, 6 for USDC). #### 1.2. Vesting Release Function The claimable amount at any given timestamp $$t$$ is calculated using a linear discrete function with a TGE (Token Generation Event) offset.
Where: * $$Vtge​$$: Percentage released immediately at TGE. * $$tend​$$: Timestamp when the sale ended. * $$dcycle​$$: Duration of one vesting cycle (in seconds). * $$Vcycle​$$: Percentage released per cycle. * $$⌊x⌋$$: Floor function (integer division).
### 2. System Architecture Diagrams #### 2.1. The "Factory-Child" Deployment Flow
This diagram illustrates how the `GenesisFactory` isolates risk by deploying a unique, independent Smart Contract for each fundraising event.
#### 2.2. User Interaction Lifecycle (State Machine) The lifecycle of an investor's journey through the protocol.
*** ### 3. "Under the Hood" Mechanics #### 3.1. Gas Optimization Techniques The Genesis contracts are optimized for the BNB Chain to minimize transaction costs for investors. * Immutable Variables: Core settings like token addresses are stored as `immutable` bytecode constants, saving \~200 gas per read compared to standard storage. * Unchecked Arithmetic: Vesting calculations use optimized math where overflow is logically impossible, reducing opcode usage. * Mapping Packing: Boolean flags (like `whitelistEnabled`) are packed into single storage slots adjacent to addresses. #### 3.2. Data Flow Example Scenario: User invests 1 BNB into Project X. 1. Input: Protocol receives `1.0` BNB ($$1018$$ wei). 2. Rate Check: Rate is `1 BNB = 2,500 X-Tokens`. 3. Calculation: $$1018×2500=2500×1018$$. 4. Storage: `investments[user] += 1 BNB`. 5. Event: Emits `Invested(User, 1 BNB)`. 6. Result: User is now legally entitled to 2,500 X-Tokens claimable after finalization. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.metuslabs.com/metus/dapps/genesis/genesis-technical-documentation.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.