Persistence of AutoConfig global & per-pair variables explained

A key feature of Gunbot's AutoConfig system is its ability to maintain stateful information using global and per-pair variables. This statefulness isn't just for a single Gunbot session; these variables are designed to persist across Gunbot restarts. This is achieved by automatically saving them to dedicated JSON files in your Gunbot user directory: autoconfig-variables.json for global variables and autoconfig-pairVariables.json for per-pair variables.

Use the AutoConfig wizard

Nearly every option that follows can be set without editing files by hand.
Click the ⋮ (three-dots) menu ➜ AutoConfig, step through the wizard, and press Save; it will write a correct autoconfig.json for you.

The Persistence Mechanism

AutoConfig's ability to "remember" variable states across sessions is crucial for long-running automations, multi-stage processes, and consistent behavior after restarts or updates. This is handled through two primary files:

1. autoconfig-variables.json:

   • Purpose: Stores all global AutoConfig variables. These are variables accessible via this.variables in custom scripts and can be set by any job using setVariable or resetVariable.
   • Location: Found in your main Gunbot user directory (the folder containing config.js, gunbotgui.db, etc.).
   • Format: A simple JSON object where keys are the variable names and values are their stored states (string, number, or boolean).

     // Example content of autoconfig-variables.json
     {
       "marketPhase": "bullish",
       "activeAutomations": 5,
       "lastGlobalCheckTimestamp": 1678886400000
     }

2. autoconfig-pairVariables.json:

   • Purpose: Stores all per-pair AutoConfig variables. These variables are specific to an exchange and a trading pair (e.g., a variable for BTC-USDT on binance). They are accessible via this.pairVariables in custom scripts and set using setPairVariable or resetPairVariable.
   • Location: Also in your Gunbot user directory.
   • Format: A nested JSON object. The first level keys are exchange names, the second level keys are pair names (Gunbot's normalized format, e.g., BTC-USDT), and the third level contains the actual per-pair variable names and their values.

     // Example content of autoconfig-pairVariables.json
     {
       "binance": {
         "USDT-BTC": {
           "tradingCycleStep": "awaitingSellSignal",
           "dcaLevel": 2
         },
         "USDT-ETH": {
           "tradingCycleStep": "inPosition",
           "lastBuyPrice": 1850.75
         }
       },
       "kraken": {
         "USDT-BTC": { // Note: Pair names might differ by exchange convention
           "tradingCycleStep": "cooldown"
         }
       }
     }

How and When Variables Are Saved and Loaded

• Saving:

  • Whenever an AutoConfig job executes an action that modifies a variable (i.e., setVariable, resetVariable, setPairVariable, resetPairVariable), Gunbot's AutoConfig module immediately updates the in-memory store of these variables.
  • Shortly thereafter (often almost instantly or within a very short debounce period), AutoConfig writes the complete current state of the respective variable object (either all global variables or all per-pair variables) to its corresponding JSON file (autoconfig-variables.json or autoconfig-pairVariables.json). This overwrites the previous file content with the new, complete state.

• Loading:

  • When Gunbot starts, one of its initialization steps includes reading autoconfig-variables.json and autoconfig-pairVariables.json.
  • If these files exist and are valid JSON, their contents are parsed and loaded into AutoConfig's memory. This makes all previously saved variables immediately available to any AutoConfig job or custom filter script from the moment Gunbot is ready.
  • If a file is missing or corrupted (invalid JSON), AutoConfig will typically start with an empty set for that type of variable, and a warning might be logged.

Implications of Persistence

• Stateful Logic: Your AutoConfig jobs can build upon previous states. A counter incremented in one run will retain its value for the next run, even if Gunbot restarts in between.
• Long-Term Tracking: You can track events or states over days or weeks (e.g., "has this pair been unprofitable for 7 consecutive days?").
• Recovery from Restarts: If Gunbot restarts unexpectedly, jobs that rely on these variables can pick up where they left off in terms of their stateful logic, provided the variable files were successfully written before the shutdown.
• Manual Inspection (with Caution): Because they are JSON files, you can open and inspect them to understand the current state of your AutoConfig variables. However, manual editing should be done with extreme caution.

Manual Editing and Backups

• Manual Editing:

  • It is generally not recommended to manually edit autoconfig-variables.json or autoconfig-pairVariables.json while Gunbot is running, as AutoConfig might overwrite your changes.
  • If you need to edit them (e.g., to reset a stuck variable or correct a value), stop Gunbot first.
  • Ensure your edits result in valid JSON. Use a JSON validator tool to check your changes before saving. An invalid JSON file will prevent AutoConfig from loading your variables.
  • Always make a backup of the file before manual editing.

• Backups:

  • These variable files are critical components of your AutoConfig setup's "memory."
  • Include autoconfig-variables.json and autoconfig-pairVariables.json in your regular Gunbot configuration backups. Losing these files means losing all persisted AutoConfig state.

What if Files Are Missing or Corrupted?

If Gunbot cannot find or parse one of these files on startup:

• It will typically start with an empty set for that type of variable (e.g., no global variables, or no per-pair variables).
• Your AutoConfig jobs that rely on these variables might behave as if it's their very first run (e.g., counters will start from default values like 0 if your scripts use this.variables.myCounter || 0).
• Gunbot will create new, empty files (or overwrite corrupted ones with an empty structure) once an AutoConfig job attempts to set a variable of that type.

The persistence of global and per-pair variables through autoconfig-variables.json and autoconfig-pairVariables.json is what allows AutoConfig to execute complex, state-aware automation strategies reliably over time and across Gunbot sessions. Understanding this mechanism is key to building robust and intelligent AutoConfig workflows.