Relevant source files

The following files were used as context for generating this wiki page: - [bot/src/UnstakeBot.ts](https://github.com/P-Rwirangira/Zero-Wait-Unstaking/blob/main/bot/src/UnstakeBot.ts) - [bot/src/index.ts](https://github.com/P-Rwirangira/Zero-Wait-Unstaking/blob/main/bot/src/index.ts) - [bot/src/__tests__/UnstakeBot.test.ts](https://github.com/P-Rwirangira/Zero-Wait-Unstaking/blob/main/bot/src/__tests__/UnstakeBot.test.ts) - [scripts/config.ts](https://github.com/P-Rwirangira/Zero-Wait-Unstaking/blob/main/scripts/config.ts) - [README.md](https://github.com/P-Rwirangira/Zero-Wait-Unstaking/blob/main/README.md) - [shared/src/types/events.ts](https://github.com/P-Rwirangira/Zero-Wait-Unstaking/blob/main/shared/src/types/events.ts)

# Unstake Bot Core Logic The Unstake Bot is an automated, off-chain agent responsible for executing unstaking transactions at the precise moment a user's token lock period expires. It operates by monitoring on-chain `Staked` events, scheduling unstake operations, and executing them through a delegator smart contract. The bot is designed for high reliability, featuring block-accurate timing, gas price optimization, concurrent execution safety, and a robust retry mechanism. This system ensures that users' assets are unstaked automatically without manual intervention, leveraging EIP-7702 for secure, authorized transaction execution on behalf of the user. The bot's core logic is encapsulated within the `UnstakeBot` class, which manages state, network interaction, and the execution lifecycle. Sources: [README.md](), [bot/src/UnstakeBot.ts:1-15]() ## Architecture and Core Components The bot's architecture is centered around the `UnstakeBot` class, which orchestrates all operations. It maintains an internal state, interacts with the blockchain via `ethers.js`, and listens for events using a WebSocket connection. Sources: [bot/src/UnstakeBot.ts:63-156]() ### UnstakeBot Class Diagram The following diagram illustrates the main components and dependencies of the `UnstakeBot` class. ```mermaid classDiagram direction LR class UnstakeBot { -provider: ethers.JsonRpcProvider -wallet: ethers.Wallet -stakingContract: ethers.Contract -delegatorContract: ethers.Contract -ws: WebSocket -state: BotState -config: BotConfig -isRunning: boolean +start() void +stop() void -connectWebSocket() void -subscribeToEvents() void -handleWebSocketMessage(data) void -processContractEvent(log) void -scheduleUnstake(userAddress, unlockTime) void -startExecutionLoop() void -executeScheduledUnstakes() void -executeUnstake(userAddress) void -handleExecutionFailure(userAddress, error) void -updateGasPrice() void -monitorNetworkHealth() void } class BotConfig { +rpcUrl: string +wsUrl: string +privateKey: string +stakingContractAddress: string +delegatorContractAddress: string +maxGasPrice: bigint +retryAttempts: number } class BotState { +pendingUnstakes: Map +executionQueue: UnstakeTask[] +gasTracker: GasPriceTracker +networkMonitor: NetworkHealthMonitor +executionLocks: Set +completedExecutions: Set } UnstakeBot "1" *-- "1" BotConfig : uses UnstakeBot "1" *-- "1" BotState : manages ``` Sources: [bot/src/UnstakeBot.ts:18-59, 63-65]() ### Key Components | Component | Description | Source File | | --- | --- | --- | | `UnstakeBot` | The main class that encapsulates all bot logic, including event monitoring, scheduling, and execution. | `bot/src/UnstakeBot.ts:63` | | `BotConfig` | An interface defining all configuration parameters, such as RPC endpoints, contract addresses, and gas settings. | `bot/src/UnstakeBot.ts:50-61` | | `BotState` | An interface representing the bot's internal state, including pending tasks, execution queues, and network health monitors. | `bot/src/UnstakeBot.ts:18-48` | | `ethers.js` | The library used for all blockchain interactions, including provider connections, wallet management, and contract calls. | `bot/src/UnstakeBot.ts:1` | | `WebSocket` | Used for establishing a real-time connection to an Ethereum node to listen for contract events. | `bot/src/UnstakeBot.ts:2` | ## Configuration The bot is configured through environment variables, which are parsed and loaded into a `BotConfig` object upon initialization. This approach separates configuration from code and allows for different settings across environments (e.g., testnet, mainnet). Sources: [bot/src/index.ts:6-49](), [scripts/config.ts:4-44]() ### Bot Configuration (`BotConfig`) The following table details the parameters available in the `BotConfig` interface. | Parameter | Type | Description | Default Value | | --- | --- | --- | --- | | `rpcUrl` | `string` | The URL of the JSON-RPC endpoint for blockchain interaction. | `https://bsc-testnet.public.blastapi.io` | | `wsUrl` | `string` | The URL of the WebSocket endpoint for real-time event monitoring. | `wss://bsc-testnet.public.blastapi.io` | | `privateKey` | `string` | The private key of the wallet used by the bot to send transactions. | `''` (Required) | | `stakingContractAddress` | `string` | The address of the `StakingContract`. | `''` (Required) | | `delegatorContractAddress` | `string` | The address of the `EIP7702Delegator` contract. | `''` (Required) | | `gasLimitMultiplier` | `number` | A multiplier applied to the estimated gas limit for safety. | `1.2` | | `maxGasPrice` | `bigint` | The maximum gas price the bot is willing to pay for a transaction. | `20000000000` (20 gwei) | | `retryAttempts` | `number` | The number of times to retry a failed unstake execution. | `3` | | `retryDelay` | `number` | The base delay in milliseconds before the first retry. | `5000` | | `blockConfirmations` | `number` | The number of block confirmations to wait for after sending a transaction. | `1` | Sources: [bot/src/index.ts:20-33](), [bot/src/UnstakeBot.ts:50-61]() ### Initialization The `main` function in `bot/src/index.ts` is the application's entry point. It reads environment variables, creates the `BotConfig` object, validates required fields, and instantiates the `UnstakeBot`. ```typescript // bot/src/index.ts // ... const botConfig: BotConfig = { rpcUrl: process.env['RPC_URL'] || 'https://bsc-testnet.public.blastapi.io', wsUrl: process.env['WS_URL'] || 'wss://bsc-testnet.public.blastapi.io', privateKey: process.env['PRIVATE_KEY'] || '', stakingContractAddress: process.env['STAKING_CONTRACT_ADDRESS'] || '', delegatorContractAddress: process.env['DELEGATOR_CONTRACT_ADDRESS'] || '', // ... other configs }; // Validate required configuration if (!botConfig.privateKey) { console.error('PRIVATE_KEY environment variable is required'); process.exit(1); } // ... const bot = new UnstakeBot(botConfig); await bot.start(); // ... ``` Sources: [bot/src/index.ts:20-51, 80-82]() ## State Management The bot maintains a `BotState` object to track its internal status, manage tasks, and monitor the environment. This state is crucial for ensuring idempotency, preventing race conditions, and maintaining operational awareness. Sources: [bot/src/UnstakeBot.ts:18-48, 131-149]() ### Bot State Structure This diagram shows the components of the `BotState`. ```mermaid graph TD BotState --> PendingUnstakes["pendingUnstakes (Map)"] BotState --> ExecutionQueue["executionQueue (Array)"] BotState --> GasTracker["gasTracker (Object)"] BotState --> NetworkMonitor["networkMonitor (Object)"] BotState --> ExecutionLocks["executionLocks (Set)"] BotState --> CompletedExecutions["completedExecutions (Set)"] BotState --> ExecutionTimestamps["executionTimestamps (Map)"] PendingUnstakes -- "key: userAddress" --> UnstakeSchedule ExecutionQueue -- "contains" --> UnstakeTask ``` Sources: [bot/src/UnstakeBot.ts:18-48]() ### State Components | Component | Type | Description | | --- | --- | --- | | `pendingUnstakes` | `Map` | Stores all known unstake schedules, keyed by user address. Used to track retry counts and status. | | `executionQueue` | `UnstakeTask[]` | A priority queue of tasks ready for execution, sorted by `unlockTime`. | | `gasTracker` | `GasPriceTracker` | Tracks the current gas price and its history to determine optimal transaction fees. | | `networkMonitor` | `NetworkHealthMonitor` | Monitors blockchain health, such as the timestamp of the latest block. | | `executionLocks` | `Set` | A set of user addresses currently being processed to prevent concurrent execution for the same user. | | `completedExecutions` | `Set` | A set of unique `executionId`s for completed tasks to ensure idempotency. | | `executionTimestamps` | `Map` | Stores timestamps of completed executions for periodic cleanup. | Sources: [bot/src/UnstakeBot.ts:18-48]() ## Lifecycle and Execution Flow The bot's lifecycle begins with the `start()` method and ends with `stop()`. The core logic resides in an execution loop that periodically checks for and processes ready tasks. ### Startup Sequence The `start()` method initializes all necessary components, including network monitoring and the WebSocket connection, before starting the main execution loop. ```mermaid sequenceDiagram participant Main as "index.ts" participant Bot as "UnstakeBot" participant Provider as "ethers.JsonRpcProvider" participant WS as "WebSocket" Main->>Bot: new UnstakeBot(config) Main->>Bot: start() Bot->>Provider: getBlock('latest') Note over Bot,Provider: Initializes network monitoring Provider-->>Bot: block Bot->>Bot: updateGasPrice() Bot->>WS: new WebSocket(wsUrl) Note over Bot,WS: Connects to node WS-->>Bot: 'open' event Bot->>WS: send(subscribe_message) Note over Bot,WS: Subscribes to Staked events Bot->>Bot: startExecutionLoop() Note right of Bot: setInterval(..., 2000) Bot-->>Main: Promise resolves ``` Sources: [bot/src/UnstakeBot.ts:158-177, 195-231, 400-435]() ### Event Handling and Scheduling The bot listens for `Staked` events from the `StakingContract` via its WebSocket connection. When an event is received, it is processed to schedule a future unstake operation. This flowchart illustrates the event handling and scheduling process. ```mermaid flowchart TD A[WebSocket receives 'Staked' event] --> B{Process Message}; B --> C[Decode Event Log]; C --> D{Extract user & unlockTime}; D --> E{Is unstake already scheduled or completed?}; E -- No --> F[Create UnstakeSchedule object]; F --> G[Add to pendingUnstakes Map]; G --> H{Is unlockTime within 1 hour?}; H -- Yes --> I[Add to executionQueue]; I --> J[Sort executionQueue by priority]; J --> K[End]; E -- Yes --> K; H -- No --> K; ``` Sources: [bot/src/UnstakeBot.ts:252-300, 302-330, 332-361]() ### Unstake Execution The `startExecutionLoop` method sets up an interval (every 2 seconds) that triggers the `executeScheduledUnstakes` function. This function is the heart of the bot, responsible for block-accurate execution. 1. **Check Network Health**: The loop first ensures the network is healthy. 2. **Identify Ready Tasks**: It filters the `executionQueue` for tasks whose `scheduledTime` is at or before the latest block's timestamp. 3. **Prevent Race Conditions**: It uses an `executionLocks` set to ensure only one execution attempt runs at a time for a given user. 4. **Ensure Idempotency**: It checks the `completedExecutions` set to avoid re-processing completed tasks. 5. **Execute**: For each ready and unlocked task, it calls `executeUnstake`. The `executeUnstake` method performs the final on-chain transaction: 1. **Pre-flight Checks**: It verifies that `canUnstake` on the `StakingContract` and `hasValidAuthorization` on the `EIP7702Delegator` contract both return `true`. 2. **Gas Optimization**: It calls `getOptimalGasPrice` to calculate a competitive but capped gas price. 3. **Wait for Next Block**: To achieve block-accurate timing, it attempts to wait for the next block before submission. 4. **Submit Transaction**: It calls `executeUnstake(userAddress)` on the `delegatorContract`, which atomically executes the unstake. 5. **Confirmation**: It waits for the transaction to be confirmed. Sources: [bot/src/UnstakeBot.ts:400-435, 437-531, 533-582]() This sequence diagram shows the unstake execution flow. ```mermaid sequenceDiagram participant Loop as "Execution Loop" participant Bot as "UnstakeBot" participant Provider as "ethers.Provider" participant StakingContract as "StakingContract" participant DelegatorContract as "DelegatorContract" Loop->>Bot: executeScheduledUnstakes() Bot->>Provider: getBlock('latest') Provider-->>Bot: latestBlock Note right of Bot: Filters queue for ready tasks Bot->>Bot: Acquire execution lock for user Bot->>StakingContract: canUnstake(user) StakingContract-->>Bot: true Bot->>DelegatorContract: hasValidAuthorization(user) DelegatorContract-->>Bot: true Bot->>Bot: getOptimalGasPrice() Bot->>Provider: waitForNextBlock() Provider-->>Bot: nextBlockNumber Bot->>DelegatorContract: executeUnstake(user) DelegatorContract-->>Bot: tx Bot->>Provider: tx.wait(confirmations) Provider-->>Bot: receipt Note right of Bot: On success, mark as complete and remove from queue Bot->>Bot: Release execution lock ``` Sources: [bot/src/UnstakeBot.ts:437-582]() ## Error Handling and Resilience The bot is designed to be resilient to network issues and transaction failures. ### Retry Mechanism If an `executeUnstake` call fails, the `handleExecutionFailure` method is invoked. - It increments the `retryCount` for the schedule. - It implements an **exponential backoff** strategy, where the delay before the next retry increases with each failure (`retryDelay * 2^(retryCount - 1)`). - If the number of retries exceeds `config.retryAttempts`, the task is removed from the queue, and a critical error is logged. Sources: [bot/src/UnstakeBot.ts:584-625]() ### Network Health Monitoring The `monitorNetworkHealth` method is called in each execution loop. It checks if the latest block's timestamp is recent (within 15 seconds). If the block is too old, the `networkMonitor.isHealthy` flag is set to `false`, and the execution cycle is skipped to prevent acting on stale data. Sources: [bot/src/UnstakeBot.ts:696-718]() ### Graceful Shutdown & Exception Handling The `index.ts` file sets up process listeners for `SIGINT` and `SIGTERM` to ensure a graceful shutdown by calling `bot.stop()`. It also includes handlers for `uncaughtException` and `unhandledRejection` that trigger an `emergencyStop()` to prevent undefined behavior. Sources: [bot/src/index.ts:53-78]() ## Conclusion The Unstake Bot's core logic provides a robust and automated solution for executing time-sensitive blockchain transactions. Through a combination of real-time event monitoring, precise scheduling, stateful execution management, and comprehensive error handling, it ensures that user unstakes are processed reliably and efficiently. Its architecture, featuring idempotency checks, concurrency locks, and network health monitoring, makes it a resilient off-chain component critical to the Zero-Wait Unstaking system's functionality. Sources: [README.md](), [bot/src/UnstakeBot.ts]()## FULL FILE CONTEXT SUMMARY Query: You are an expert technical writer and software architect. Your task is to generate a comprehensive and accurate technical wiki page in Markdown format about a specific feature, system, or module within a given software project. You will be given: 1. The "[WIKI_PAGE_TOPIC]" for the page you need to create. 2. A list of "[RELEVANT_SOURCE_FILES]" from the project that you MUST use as the sole basis for the content. You MUST use AT LEAST 5 relevant source files for comprehensive coverage - if fewer are provided, search for additional related files in the codebase. CRITICAL STARTING INSTRUCTION: The very first thing on the page MUST be a

block listing ALL the [RELEVANT_SOURCE_FILES] you used to generate the content. There MUST be AT LEAST 5 source files listed - if fewer were provided, you MUST find additional related files to include. Format it exactly like this:

Relevant source files

Remember, do not provide any acknowledgements, disclaimers, apologies, or any other preface before the `

` block. JUST START with the `

` block. The following files were used as context for generating this wiki page: - [bot/src/UnstakeBot.ts](https://github.com/P-Rwirangira/Zero-Wait-Unstaking/blob/main/bot/src/UnstakeBot.ts) - [bot/src/index.ts](https://github.com/P-Rwirangira/Zero-Wait-Unstaking/blob/main/bot/src/index.ts)

Immediately after the

block, the main title of the page should be a H1 Markdown heading: # Unstake Bot Core Logic. Based ONLY on the content of the [RELEVANT_SOURCE_FILES]: 1. **Introduction:** Start with a concise introduction (1-2 paragraphs) explaining the purpose, scope, and high-level overview of "Unstake Bot Core Logic" within the context of the overall project. If relevant, and if information is available, link to other potential wiki pages using the format [Link Text](#page-anchor-or-id). 2. **Detailed Sections:** Break down "Unstake Bot Core Logic" into logical sections using H2 (##) and H3 (###) Markdown headings. For each section: * Explain the architecture, components, data flow, or logic relevant to the section's focus, as evidenced in the source files. * Identify key functions, classes, data structures, API endpoints, or configuration elements pertinent to that section. 3. **Mermaid Diagrams:** * EXTENSIVELY use Mermaid diagrams (e.g., flowchart TD, sequenceDiagram, classDiagram, erDiagram, graph TD) to visually represent architectures, flows, relationships, and schemas found in the source files. * Ensure diagrams are accurate and directly derived information from the [RELEVANT_SOURCE_FILES]. * Provide a brief explanation before or after each diagram to give context. * CRITICAL diagram requirements for optimal rendering: - **Flow diagrams**: Use "graph TD" (top-down) or "flowchart TD" directives for better vertical layout - **Node labels**: Keep node labels concise but descriptive (under 25 characters for readability) - **Node IDs**: Use alphanumeric characters and underscores only (avoid spaces, special characters) - **Connections**: Use standard arrow syntax (-->, ---, -.->) for reliable rendering - **Sequence diagrams**: - Start with "sequenceDiagram" directive on its own line - Use participant names without spaces (use underscores if needed) - Define participants explicitly when needed: `participant User as "User Interface"` - Use correct arrow types: - ->> for synchronous calls/requests - -->> for responses - -x for failed/error messages - --x for failed responses - Add activation boxes sparingly with +/- notation - Use "Note over" or "Note right of" for clarifications - **Class diagrams**: Use standard UML notation with proper relationship syntax - **ER diagrams**: Use entity relationship syntax with proper cardinality notations * **Quality guidelines**: - Test diagram syntax mentally before including - If a diagram becomes too complex, split into multiple focused diagrams - Ensure proper closing of all brackets and quotes - Use consistent naming conventions within each diagram - Add line breaks for readability in complex diagrams * **Example patterns (GOOD vs BAD)**: ``` GOOD Flow Diagram: ```mermaid flowchart TD A[User Request] --> B[Validate Input] B --> C[Process Data] C --> D[Return Response] ``` BAD Flow Diagram: ```mermaid graph LR A[User Request with Very Long Description] --> B ``` GOOD Sequence Diagram: ```mermaid sequenceDiagram participant User as "User Interface" participant API as "API Server" participant DB as "Database" User->>API: POST /api/data API->>DB: SELECT * FROM table DB-->>API: Query results API-->>User: JSON response ``` ``` 4. **Tables:** * Use Markdown tables to summarise information such as: * Key features or components and their descriptions. * API endpoint parameters, types, and descriptions. * Configuration options, their types, and default values. * Data model fields, types, constraints, and descriptions. 5. **Code Snippets (ENTIRELY OPTIONAL):** * Include short, relevant code snippets (e.g., Python, Java, JavaScript, SQL, JSON, YAML) directly from the [RELEVANT_SOURCE_FILES] to illustrate key implementation details, data structures, or configurations. * Ensure snippets are well-formatted within Markdown code blocks with appropriate language identifiers. 6. **Source Citations (EXTREMELY IMPORTANT):** * For EVERY piece of significant information, explanation, diagram, table entry, or code snippet, you MUST cite the specific source file(s) and relevant line numbers from which the information was derived. * Place citations at the end of the paragraph, under the diagram/table, or after the code snippet. * Use the exact format: `Sources: [filename.ext:start_line-end_line]()` for a range, or `Sources: [filename.ext:line_number]()` for a single line. Multiple files can be cited: `Sources: [file1.ext:1-10](), [file2.ext:5](), [dir/file3.ext]()` (if the whole file is relevant and line numbers are not applicable or too broad). * If an entire section is overwhelmingly based on one or two files, you can cite them under the section heading in addition to more specific citations within the section. * You MUST cite AT LEAST 5 different source files throughout the wiki page to ensure comprehensive coverage. 7. **Technical Accuracy:** All information must be derived SOLELY from the [RELEVANT_SOURCE_FILES]. Do not infer, invent, or use external knowledge about similar systems or common practices unless it's directly supported by the provided code. If information is not present in the provided files, do not include it or explicitly state its absence if crucial to the topic. 8. **Clarity and Conciseness:** Use clear, professional, and concise technical language suitable for other developers working on or learning about the project. Avoid unnecessary jargon, but use correct technical terms where appropriate. 9. **Conclusion/Summary:** End with a brief summary paragraph if appropriate for "Unstake Bot Core Logic", reiterating the key aspects covered and their significance within the project. IMPORTANT: Generate the content in English language. Remember: - Ground every claim in the provided source files. - Prioritize accuracy and direct representation of the code's functionality and structure. - Structure the document logically for easy understanding by other developers. [WIKI_PAGE_TOPIC]: Unstake Bot Core Logic [RELEVANT_SOURCE_FILES]: - bot/src/UnstakeBot.ts - bot/src/index.ts