Worker System

What It Is

The Neko Worker System is a deterministic, event-driven, Celery-based task processor that automatically manages a wide range of DeFi positions including: PT Looping, Basis Trades, Supply Side Optimizers, ALM Orchestrator strategies, and more.

While the DeFAI Multi-agent System is responsible for high-level analysis and strategy selection, the Worker System carries out those strategies on-chain with precision and reliability. The system is designed for scalability, with each vault managed by a dedicated, autonomous Neko Worker in a 1 vault = 1 worker loop architecture.

Your Benefit: AI-Informed Strategy, Deterministic Execution

The Neko architecture is designed to give you the best of both worlds: the analytical power of advanced AI models and the predictable safety of deterministic execution.

• AI-Powered Analysis: Pre-approved AI and strategy engines analyze vast amounts of historical and real-time market data from Neko's data pipelines to select the optimal strategy for a given vault.

• Deterministic Execution: Once a strategy is assigned, the Neko Worker executes it according to a strict, predefined set of rules. This ensures the system will not hallucinate, call the wrong function, or interact with an unintended protocol, protecting the profitability of your position.

• Traceable & Auditable: Every action taken by a worker is logged and traceable on-chain, providing a clear audit trail of your position's management history.

---

Core Architecture

The Worker System is composed of four key components that ensure reliable and persistent operation.

Neko Workers

These are distributed, asynchronous, Celery-based task runners that form the heart of the system. Each worker is an automated script responsible for the main monitoring and execution loop for a single vault position. They operate independently and are designed for high availability and robust error handling.

State Management & Persistence

The system's memory is a comprehensive state management database. It goes beyond storing the initial strategy to track the complete, dynamic state of each position. This includes:

• status: The current operational state (e.g., active, rebalancing, error).

• onchain_state: The latest data fetched from the blockchain for the position.

• performance_metrics: Key metrics like APR and fees earned.

• worker_last_heartbeat: A timestamp to monitor if a worker is alive and responsive.

• alerts: A log of recent warnings or issues.

This persistence enables robust error handling and recovery, ensuring that if a worker crashes or restarts, a new instance can resume exactly where the previous one left off.

Strategy Definitions

Each vault is assigned a predefined strategy (e.g., Automated Liquidity Management, PT Looping, Basis Trades) from a library of pre-approved playbooks. These definitions, stored in the database, contain the exact configuration and parameters for the vault, including token addresses, protocol details, and specific strategy rules. Workers execute these strategies faithfully and cannot deviate from their instructions.

Execution Layer (hl-bot-suite)

To ensure maximum security and determinism, workers do not execute blockchain transactions directly. Instead, they send commands for atomic actions (e.g., "rebalance," "compound") to a secure, external API service. This Execution Layer is responsible for the final, complex step of building, signing, and broadcasting the on-chain transaction. This separation of concerns creates a secure boundary between the worker's decision logic and on-chain execution.

How It Works: The Worker Lifecycle

The Worker System is event-driven, beginning when a user deposits funds into a vault.

1. Trigger: A user deposit event initiates the workflow, assigning a dedicated Neko Worker to manage the vault's new or existing position.

2. Initialization: The worker loads its assigned strategy and parameters from the state management database.

3. Execution Loop: The worker enters a continuous loop to manage the position:

   • Acquire Lock: It secures a lock on the position to prevent concurrent operations from other workers.

   • Load State: It fetches the latest status of its assigned position from the database.

   • Fetch On-Chain Data: It queries the blockchain and subgraphs for real-time data about the position (e.g., current price tick, uncollected fees).

   • Evaluate Strategy: It compares the live on-chain data against the rules defined in its strategy to determine if an action is required.

   • Execute Action: If an action is needed, the worker sends a precise command (e.g., rebalance, compound) with the necessary parameters to the secure Execution Layer.

   • Update State: It records the results of the cycle—including any actions taken, performance metrics, and the latest on-chain data—back into the database.

   • Reschedule: The worker schedules itself to run again after a predefined interval (e.g., every 5 minutes), creating a continuous, self-scheduling monitoring loop.

How Neko Guarantees Safe Execution

The system's architecture is fundamentally designed to prevent AI hallucinations from impacting on-chain execution and user funds.

• Predefined Strategies: Workers only execute strategies that are pre-approved, audited, and stored in the database. They do not devise their own actions at runtime.

• No LLM in the Execution Path: The core worker loop—from fetching data to executing an action—is pure, deterministic code. It evaluates structured data against fixed rules without any calls to a large language model.

• Abstracted On-Chain Actions: Workers are sandboxed from direct on-chain interaction. They issue high-level commands to the Execution Layer API, which translates them into specific, secure transactions. This removes any risk of a worker calling an incorrect contract function.