Xitadel Keeper-Bot

One-command Solana keeper scaffold – watch on-chain events and push transactions automatically.

Quick Start

Using Makefile (recommended):

# Setup and start in devnet mode
make start-devnet

# Setup and start in mainnet mode
make start-mainnet

# Clean up generated files
make clean

Or using environment variables directly:

# devnet
BUILD_TARGET=devnet deno task start

# mainnet
BUILD_TARGET=mainnet deno task start

The script reads config.json for RPC URLs, polling interval, and custom handlers.

Environment Setup

The bot requires the following environment variables:

• BUILD_TARGET: Network to use (mainnet or devnet)
• ANCHOR_WALLET: Path to your wallet keypair file

These are automatically set up when using the Makefile. If you're not using the Makefile, you'll need to set them manually:

# Set network target
export BUILD_TARGET=devnet  # or mainnet

# Set wallet path
export ANCHOR_WALLET=.keys/wallet-keypair.json

Wallet Setup

The Makefile will automatically create a wallet keypair if one doesn't exist. The keypair will be stored in .keys/wallet-keypair.json.

To create a wallet manually:

# Create .keys directory
mkdir -p .keys

# Generate new keypair
solana-keygen new --no-bip39-passphrase -o .keys/wallet-keypair.json

Requirements

• Deno v1.40+ – runtime & bundler (Node.js is optional, only used for pre-commit hooks or CI scripts)
• Solana CLI tools (for wallet management)

Install / Build

git clone https://github.com/xitadel/keeper-bot.git
cd keeper-bot

# cache deps
deno cache main.ts

# production binaries
deno task build:mainnet   # outputs ./keeper-bot
deno task build:devnet    # outputs ./keeper-bot

Config Example (config.json)

{
  "db": {
    "api_url": "https://example.xitadel.fi"
  },
  "monitor": {
    "interval": 3000,
    "targets": {
      "mainnet": {
        "name": "keeper-bot-mainnet",
        "url": "https://api.mainnet-beta.solana.com",
        "method": "POST",
        "headers": {
          "Content-Type": "application/json"
        },
        "body": {
          "jsonrpc": "2.0",
          "id": 1,
          "method": "getBlockHeight"
        }
      },
      "devnet": {
        "name": "keeper-bot-devnet",
        "url": "https://api.devnet.solana.com",
        "method": "POST",
        "headers": {
          "Content-Type": "application/json"
        },
        "body": {
          "jsonrpc": "2.0",
          "id": 1,
          "method": "getBlockHeight"
        }
      }
    }
  },
  "actions": {
    "status_mismatch": {
      "type": "webhook",
      "params": {
        "url": "https://hooks.example.com/alerts",
        "message": "Solana network health check failed"
      }
    },
    "check_failed": {
      "type": "log",
      "params": {
        "message": "Network health check failed"
      }
    }
  },
  "update_status_invocation": {
    "interval": 3000
  }
}

Directory Layout

src/
├─ services/        # core watchers & tx builders
├─ types/           # shared TypeScript defs
├─ utils/           # helpers
├─ logger.ts        # logging service
├─ config.ts        # configuration management
└─ action-handler.ts # action handlers
main.ts             # entry point
deno.json           # tasks & permissions
config.json         # sample config
Makefile           # environment & build management

Testing

Run the test suite with:

deno test

For specific test files:

deno test src/services/monitor_test.ts
deno test src/logger_test.ts

Error Handling

The bot implements comprehensive error handling:

• Network failures are retried with exponential backoff
• Configuration errors are caught and logged
• Invalid responses trigger appropriate actions
• All errors are logged with context for debugging

Security Notes

• The .keys directory is automatically added to .gitignore
• Never commit your wallet keypair file
• Keep your seed phrase secure and backed up
• Use different wallets for devnet and mainnet

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

keeper-bot

Solana network keeper bot CLI - distributed as a Deno binary.

Installation

You can install globally from npm:

npm install -g keeper-bot

The package includes a pre-compiled Deno binary, so no additional setup is required.

Usage

Run the bot with:

keeper-bot --url=<network> [--wallet=<path-to-wallet-keypair>] [--config=<path-to-config>]

• --url (required): Network to use, either mainnet or devnet.
• --wallet (optional): Path to your Solana wallet keypair file. Defaults to .keys/wallet-keypair.json.
• --config (optional): Path to your config file. If not provided, uses built-in default configuration.

Examples

Using default configuration:

keeper-bot --url=devnet

Using custom config file:

keeper-bot --url=devnet --wallet=.keys/wallet-keypair.json --config=my-config.json

Configuration

The bot comes with a built-in default configuration. If you want to customize it, create a config.json file:

{
  "apiUrl": "http://localhost:3000/api",
  "defaultNetwork": "mainnet",
  "network": {
    "mainnet": {
      "name": "keeper-bot-mainnet",
      "url": "https://api.mainnet-beta.solana.com",
      "actions": {
        "monitor": { "interval": 3000 },
        "update_status_invocation": { "interval": 3000 }
      }
    },
    "devnet": {
      "name": "keeper-bot-devnet",
      "url": "https://api.devnet.solana.com",
      "actions": {
        "monitor": { "interval": 3000 },
        "update_status_invocation": { "interval": 3000 }
      }
    }
  }
}

Development

• Lint: npm run lint
• Format: npm run format
• Build (Deno binary): npm run build

Notes

• This package distributes a pre-compiled Deno binary, so users don't need Deno installed.
• The binary includes all dependencies and permissions needed to run.
• No config file required: The bot works out of the box with default settings.
• The postinstall script ensures the binary is executable.
• Husky and other dev dependencies are only required for local development.

For more details, see the code and comments in the repository.