AGI Solver

svf agi solver

AGI Solver

AGI Solver is a backend system written in TypeScript designed to reliably fulfill on-chain interaction requests (Agent Generated Intents) for AI agents. It serves as a critical bridge between AI agents and blockchain interactions, ensuring reliable execution of complex on-chain operations.

Setup

1. Clone the repository

2. Set up environment variables:

   cp .env.example .env

   cd contracts
   cp .env.example .env

3. Deploy contracts

   start an anvil node first

   anvil

   then install the dependencies under the contracts/ foler:

   forge install
   

   finally, under root directory

   make deploy
   

4. Start solver

   make start
   

5. Publish an agi

   #e.g.
   make sellTokenA

Development

See .github/CONTRIBUTING.md, then .github/DEVELOPMENT.md. Thanks! 💖

💝 This package was templated with create-typescript-app using the Bingo engine.

AGI Queue Manager

The AGI Queue Manager is a system that manages the processing queue of Agent Generated Intents (AGIs). It handles the lifecycle of AGI tasks from creation to completion, including asset withdrawal, swapping, and deposit operations.

Order Processing Flow

1. Queue Management

• Items are added to queue via add(agiId)
• When processing starts, items are moved to end of queue before processing
• Items are only removed from queue when fully completed (status 2)
• Tasks that have failed swaps after MAX_RETRIES attempts will be skipped and removed from queue

2. Status Flow

a. Initial State (0 - PendingDispense)

• Withdraw asset from contract
• Contract status becomes 1

b. After Withdraw (1 - DispensedPendingProceeds)

• Set internal status to 3 (SwapInitiated)
• Begin swap operation

c. Swap Initiated (3 - SwapInitiated)

• Perform swap operation
• Set internal status to 4 (SwapCompleted) when swap is done

d. After Swap (4 - SwapCompleted)

• Deposit swapped assets back to the contract
• Set internal status to 2 (ProceedsReceived)

e. Final State (2 - ProceedsReceived)

• Clean up internal state
• Remove from queue

3. Status Selection Logic

• Use contract status as primary source of truth
• Only use internal SwapCompleted status when:
  • Contract status is 1 (DispensedPendingProceeds)
  • And we have an internal status (not undefined)

4. Transaction Handling

• Wait for transaction confirmation before proceeding
• Handle transaction failures gracefully
• Keep items in queue until fully processed

5. Queue Processing

• Process one item at a time
• Move items to end of queue before processing
• Only remove items when fully completed
• Maintain FIFO order while allowing other items to be processed

Implementation Details

The queue manager is implemented in TypeScript and uses a combination of contract interactions and internal state management to track the progress of each AGI task. It includes retry mechanisms for failed operations and maintains a strict order of operations to ensure the integrity of the asset swapping process.

Key Features

• Automatic retry of failed operations
• Transaction confirmation waiting
• FIFO queue processing
• State management for both contract and internal states
• Error handling and logging
• Configurable retry limits and delays

Error Handling

• Failed swaps are retried up to MAX_RETRIES times
• Tasks exceeding retry limits are removed from the queue
• Transaction failures are handled gracefully with appropriate logging
• System maintains queue integrity even during failures