Skip to main content

Troubleshooting a Strategy

Overview​

Even with robust error handling, your Agent may occasionally encounter unexpected situations while executing a Strategy. The blockchain environment is dynamic and unpredictable, and despite Almanak's Strategy Framework being designed to handle known errors through established happy/sad-flow patterns, there are fundamental principles that govern Agent behavior:

Rule #1: The Agent must never perform actions that could compromise funds or strategy integrity.
Rule #2: When uncertainty exists, the Agent will halt execution and request human intervention.

This approach ensures that when an Agent cannot determine the optimal path forward with high confidence, it pauses rather than proceeding with potentially problematic actions.

This guide outlines the available troubleshooting tools and how to use them effectively when your Agent requires attention.

Troubleshooting Tools​

The Almanak platform provides five primary troubleshooting tools:

  1. Logs
  2. Persistent State Files (Strategy)
  3. Config File
  4. Manual Recovery via Safe
  5. Troubleshooting Agents

Each tool serves a specific purpose in diagnosing and resolving issues with your Agent's execution.

important

While this guide provides examples based on Uniswap V3, the troubleshooting principles apply to all supported protocols.

Logs​

Logs are the first resource to consult when troubleshooting an issue, as they provide a chronological record of the Agent's execution.

When running an Agent, you can access logs from the first tab in the bottom section of the Agent screen.

Logs #1

The logs interface provides several useful features:

  • Navigation controls to view older or newer entries
  • Full-screen display option
  • Text search functionality
  • Severity-based filtering

Logs #2

A recommended troubleshooting approach is to search for State transition entries, which appear in the format:
14:48:36 ">>> INITIALIZATION (INITIALIZATION_SWAP0) | PREPARING_ACTION"
or
14:48:48 ">>> INITIALIZATION (INITIALIZATION_SWAP0) | VALIDATING_ACTION"

These entries indicate:

  • The current State (INITIALIZATION)
  • The SubState (INITIALIZATION_SWAP0)
  • The action being performed (PREPARING_ACTION or VALIDATING_ACTION)

This method helps quickly locate critical execution points. For more information on states, refer to the State Machine documentation.

Persistent State - Strategy​

The Strategy's persistent state stores all critical variables that constitute the Agent's internal memory, including:

  • Current state machine position
  • Internal accounting records
  • History of executed actions
  • Other strategy-specific data

When troubleshooting errors, this is the second resource to examine, as it provides insight into the Strategy's internal representation and potential error causes.

To edit the persistent state:

  1. First pause the Agent if it hasn't already stopped
  2. Navigate to the troubleshooting tab
  3. Modify the persistent state as needed

Persistent State - Strategy

warning

Exercise caution when handling large numbers representing token amounts with many decimal places (e.g., 12345678912345678912345678 PEPE). Ensure these values aren't truncated or converted to scientific notation (e.g., 1.23e25) when copying JSON data, as this can cause errors when the data is read back. Some tools like Chrome's JSON Pretty Print may automatically apply such conversions.

Persistent State - Executioner​

The execution layer (executioner) maintains its own persistent state, storing action bundles with their execution status. This system ensures robustness against unexpected crashes by preserving execution state on disk.

Each Action Bundle generated by a Strategy receives a unique ID and is tracked through its lifecycle, with updates recorded at each execution stage:

  • Action to transaction transformation
  • On-chain transaction submission
  • Receipt parsing and processing

While users rarely need to modify these files directly, they provide valuable information when troubleshooting transaction issues.

Persistent State - Executioner

Config​

The config.json file can be modified to adjust Strategy behavior for troubleshooting purposes. For example, in the Dynamic LP Strategy, you could force a rebalance by changing the rebalance_frequency setting to 1, which would trigger a rebalance after a single granularity period (e.g., 15 minutes).

The config file is accessible from the Troubleshooting tab:

Config

To update the configuration:

  1. Pause the Agent
  2. Edit the config file
  3. Save your changes
  4. Resume the Agent

Configuration changes take effect immediately when the Agent resumes. Note that pausing an Agent shuts down its execution environment to conserve resources, and resuming requires restarting this environment, which may take several seconds.

Manual Recovery - Safe Apps​

If a Strategy encounters an unresolvable issue, you can always terminate the Agent and recover funds manually. The Safe platform allows you to interact with protocols like Uniswap directly through their interface, enabling actions such as closing LP positions or swapping assets.

It's worth noting that Safe has a built-in swap feature powered by CoW, which can be used as an alternative to protocol-specific applications.

Using Uniswap through Safe:​

  1. Navigate to Safe → Apps → Uniswap SAFE Uniswap Details

  2. Interact with Uniswap directly through the Safe interface SAFE Uniswap Details

Note that at the time of writing, the Uniswap app on Safe supports a limited number of chains. For unsupported chains like Base, you may need to use alternative methods to close positions, such as using a troubleshooting Agent or WalletConnect (explained below).

SAFE Uniswap Details

Manual Recovery - Safe with WalletConnect​

When a protocol isn't available as a Safe App, you can use WalletConnect to establish a connection between Safe and the protocol's web interface.

This process requires two browser tabs:

  1. Safe website
  2. Protocol interface (e.g., Uniswap)

Step-by-step WalletConnect process:​

  1. On the protocol website: Select WalletConnect as your connection method SAFE Uniswap WC

  2. Copy the connection code from the pop-up SAFE Uniswap WC

  3. In Safe: Click the WalletConnect icon in the top-right menu SAFE WC Connect

  4. Paste the connection code and approve the connection SAFE WC Connect SAFE WC Approve

  5. Return to the protocol website and initiate your transaction

  6. Back in Safe: Review and execute the transaction SAFE WC Review SAFE WC Sign

  7. Return to the protocol website to confirm the completed action

warning

This guide provides general direction only. Almanak is not responsible for the Safe interface and its usage. Always review transactions carefully before signing.

Troubleshooting Agents​

For situations where an Agent has failed or been terminated before completing a clean shutdown, Almanak provides specialized troubleshooting Agents. The Troubleshoot - Close Position Strategy, available in the Strategy library, can be configured to close specific positions or all positions across pools for a given protocol.

Once positions are closed, the underlying assets and any accrued rewards will be returned to your wallet. You can then use the Safe interface to manage these assets as needed, such as swapping them back to ETH.

warning

Troubleshooting complex Agent issues may require expertise across multiple domains including strategy logic, blockchain operations, and API integrations. There is no universal solution that covers all possible error scenarios.

Potential issues can range from:

  • Strategy code bugs
  • Node provider errors
  • Third-party API failures
  • Transaction reverts on the blockchain

While the tools outlined in this guide enable troubleshooting across a wide range of scenarios, don't hesitate to contact the Almanak team for assistance with complex issues.