atom-001

Automated ETH/USDC portfolio rebalancing bot on Sepolia using custom algorithms and Chainlink CRE.

Prerequisites

• Bun - Runtime (bun install, bun run)
• SQLite - Built into Bun (bun:sqlite)
• bws CLI - Bitwarden Secrets Manager (npm install -g @bitwarden/sdk) - or 1Password if you like it better
• Chainlink CRE - (bunx cre ...)
• Rust/Cargo - For compiled algorithms (cargo build)
• jq - For bash algorithms (brew install jq)

Environment Variables

Where to put each .env file:

Directory	File	Purpose
apps/web/	.env	Frontend config (RPC, wallet)
apps/workflows/	.env	CRE workflows (BWS credentials)
apps/workflows/contracts/	.env	Foundry deployment (private keys, RPC)

Environment Variable Details

BWS (Bitwarden Secrets Manager) - for CRE workflows:

export BWS_ACCESS_TOKEN=<your_token>
export BWS_PROJECT_ID=<your_project_id>

Frontend (apps/web/.env):

VITE_TARGET_WALLET_ADDRESS=0x...
VITE_SEPOLIA_RPC_URL=https://ethereum-sepolia-rpc.publicnode.com

Contracts (apps/workflows/contracts/.env):

SEPOLIA_RPC_URL=https://ethereum-sepolia-rpc.publicnode.com
DEPLOYER_PRIVATE_KEY=0x...
OWNER_PRIVATE_KEY=0x...
FUNDER_PRIVATE_KEY=0x...
ETHERSCAN_API_KEY=your_etherscan_api_key

Installation

# Install web dependencies
cd apps/web && bun install

# Build frontend
cd apps/web && bun run build

# Install Foundry (for contracts)
curl -L https://foundry.paradigm.xyz | bash
foundryup

Running the Project

Command Center Mode (Recommended)

You do NOT need to run cli.ts manually anymore. The server manages it for you.

# Terminal 1: Sensors (fires every 30s)
bash apps/workflows/start-sensors.sh

# Terminal 2: Backend & Process Manager
cd apps/web && bun run server.ts

# Terminal 3: Frontend UI
cd apps/web && bun run dev

Then open http://localhost:3000 in your browser:

1. Select an algorithm from the dropdown
2. Click Start to spawn the CLI
3. Watch the CLI output stream to Terminal 2
4. Click Stop to kill the process

CLI / Headless Mode (Advanced)

If you prefer to run the CLI manually without the UI:

# Terminal 1: Sensors
bash apps/workflows/start-sensors.sh

# Terminal 2: CLI Orchestrator
cd apps/web
bun run cli.ts --algorithm ../workflows/algorithms/run-force-trade.sh --frequency 30s

Algorithm Interface Standard (AIS)

Custom algorithms must:

1. Accept a JSON state file path as $1
2. Output a strict JSON decision to stdout

# Example output
echo '{"action": "trade", "direction": "ETH_TO_USDC", "rawAmount": 0.001}'
echo '{"action": "hold"}'

Debug logs must go to stderr: echo "debug" >&2

Smart Contracts (Foundry)

The treasury swap contract is in apps/workflows/contracts/.

Install Foundry

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

Deploy to Sepolia

cd apps/workflows/contracts

# Copy and edit .env
cp .env.example .env
# Edit .env with your private keys and RPC URL

# Deploy the Treasury contract
forge script script/DeployTreasuryV4SwapConsumer.s.sol --rpc-url sepolia --broadcast --verify

This will deploy TreasuryV4SwapConsumer to Sepolia and verify it on Etherscan.

Other Useful Commands

# Build contracts
forge build

# Run tests
forge test

# Format code
forge fmt