Skip to main content

Test Strategy locally

Step 1: Install Foundry's Anvil​

Anvil is a local Ethereum testnet node that simulates blockchain environments for testing. It can "fork" existing networks, allowing developers to test their code against real blockchain data but without spending actual cryptocurrency. It's particularly useful for testing smart contracts, DeFi strategies, and complex transactions in a safe, cost-free environment before deploying to mainnet. We use to have a local environment where we can simulate and test our strategies.

To install Anvil, follow these steps:

  1. Install Foundry: Foundry can be installed using a single command:

    curl -L https://foundry.paradigm.xyz | bash

  2. Install Anvil: Once Foundry is installed, initialize it and install Anvil by running:

    foundryup

  3. Verify Installation: After installation, verify that Anvil is available by running;

    anvil --version

Step 2: Install the Almanak SDK​

To install the Almanak SDK, ensure that you have Python 3.11 and pip installed. Run the following command:

pip install almanak

Step 3: Authorize the Almanak CLI and Download a Tutorial Strategy​

  1. Authorize with API Key: To interact with Almanak services, you need to authenticate with your Almanak API Key. This key can be found on the Settings page of your Almanak account in the web application. Use the following command to authorize:

    almanak auth

You will be prompted to enter your API Key.

  1. Download the Tutorial Strategy: Once authorized, download tutorial_uniswap_swap strategy (an example strategy great for learning the ropes of Almanak with configuration files and sample code) using this command: 
    almanak strat example

This will create a folder named tutorial_uniswap_swap/ containing the structure and files needed to start building your strategy.

Step 4: Configure the Tutorial Strategy​

In the tutorial_uniswap_swap/ folder, you'll need to set up two important configuration files:

Environment Variables (.env)​

Create a .env file in your strategy folder with the following required variables:

# Required Environment Variables
PRIVATE_KEY_<SAFE_WALLET_ADDRESS>=<SAFE_WALLET_PRIVATE_KEY>  # For transaction signing
ALCHEMY_API_KEY=<YOUR_ALCHEMY_API_KEY>                       # For blockchain node interaction

# Example using Anvil's default test wallet (for local testing only)
PRIVATE_KEY_0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80

Strategy Configuration (pyproject.toml)​

The pyproject.toml file defines your strategy's configuration and metadata. Here's a breakdown of its key components:

[tool.metadata]
human_readable_name = "Tutorial - Uniswap Swap"      # Display name for your strategy

[tool.presets.default]
title = "Default"                                    # Preset configuration name
description = "Default preset for the Uniswap Swap Tutorial."
chain = "ARBITRUM"                                   # Target blockchain network
config = "./presets/default/config.json"             # Path to configuration file
permissions = "./presets/default/permissions.json"    # Path to permissions file
env = ".env"                                         # Path to environment variables

Configuration Fields Explained:​

  • is_private: Determines if the strategy is visible only to you
  • human_readable_name: A user-friendly name for your strategy
  • chain: Specifies the blockchain network (e.g., ARBITRUM, ETHEREUM, etc.)
  • config: Points to your strategy's specific configuration settings
  • permissions: Defines the required permissions for your strategy
  • env: Specifies the location of your environment variables file

Step 5: Test the Strategy Locally​

Before deploying, it's recommended to test the strategy locally using Anvil, Foundry's Ethereum fork framework.

  1. Start Anvil: Run Anvil with your Alchemy API key as follows (The example was done for the Arbitrum chain, if you wish to use another EVM chain then you have to change the URL and change the config.json as well as pyproject.toml): 
    anvil -f https://arb-mainnet.g.alchemy.com/v2/<ALCHEMY_API_KEY> --no-rate-limit --transaction-block-keeper 100

This command forks the mainnet, allowing you to test your strategy against real blockchain data in a local environment.

  1. Run the Local Test: With Anvil running, navigate to the tutorial_uniswap_swap/ folder and test the strategy locally using:

    almanak strat test --working-dir tutorial_uniswap_swap/ --preset default

The --preset specifies which preset of the strategy to use. Strategies can have multiple presets which are different configurations for the strategy for the same strategy, e.g. if you want to run it in different chains. When deploying the agent you will be able to select with which preset you want to deploy the agent.

Within your strategy folder (e.g., tutorial_uniswap_swap/), you'll find a directory named local_storage that contains the state machine data. This directory also captures the file hierarchy, including Actions, ActionBundles, and their corresponding transaction results and timestamps.

To stop a running strategy test at any time, press Ctrl + C. By default, relaunching the strategy will resume from the current state stored in local_storage. If you prefer to start fresh, use the --clean-restart flag to reset the state before running the strategy again and restart the Anvil instance.

By following these steps, you'll have completed the initial setup and testing for your first agent using the Almanak SDK and CLI.