---

TODO: Project Name

TODO is a reusable Node.js template for building EVM keeper bots that monitor protocol state and execute automated maintenance transactions safely.

---

Features

• Strategy-based keeper core: Keep protocol-specific logic isolated in src/strategies/.
• Safe execution controls: DRY_RUN, MAX_ACTIONS_PER_CYCLE, EXPECTED_CHAIN_ID, and confirmation controls.
• Production-friendly runtime: Graceful loop execution, robust error handling, and structured logs.
• CI-ready template: Unit tests, CI workflow, security audit workflow, and release artifact workflow included.

---

Tech Stack

Frontend

• N/A (headless keeper service)

Backend

• Node.js 20+
• JavaScript (ESM)
• Ethers.js v6
• dotenv

AI/ML (if applicable)

• N/A

Blockchain (if applicable)

• EVM-compatible networks
• JSON-RPC providers
• Keeper signer wallet for transaction execution

---

Project Checklist

• The protocol (if applicable):
  • has been described and formally specified in a paper.
  • has had its main properties mathematically proven.
  • has been formally verified.
• The smart contracts (if applicable):
  • were thoroughly reviewed by at least two knights of The Stable Order.
  • were deployed to: [Add deployment details]
• The mobile app (if applicable):
  • has an About page containing the Stability Nexus's logo and pointing to the social media accounts of the Stability Nexus.
  • is available for download as a release in this repo.
  • is available in the relevant app stores.
• The AI/ML components (if applicable):
  • LLM/model selection and configuration are documented.
  • Prompts and system instructions are version-controlled.
  • Content safety and moderation mechanisms are implemented.
  • API keys and rate limits are properly managed.

---

Repository Links

1. Main Repository
2. Frontend (if separate)
3. Backend (if separate)

---

Architecture Diagram

+--------------------+
|  Keeper Scheduler  |
| (interval / once)  |
+---------+----------+
          |
          v
+--------------------+        +-------------------------+
|  Strategy Selector | -----> | Protocol Strategy Logic |
| (KEEPER_STRATEGY)  |        | (getWorkItems/execute)  |
+---------+----------+        +------------+------------+
          |                                |
          v                                v
+--------------------+             +--------------------+
|   Ethers Provider  | <---------> |  Target Contract   |
+--------------------+             +--------------------+

---

User Flow

Start keeper -> Load config -> Validate chain -> Detect actionable items ->
(optional dry-run) -> Execute tx actions -> Wait confirmations -> Repeat

Key User Journeys

1. Template Setup

   • Copy .env.example to .env
   • Choose strategy
   • Configure RPC and contract values

2. Local Validation

   • Run npm test
   • Run npm run start:once
   • Run npm run start:dry-run

3. Production Loop

   • Run npm run start
   • Monitor logs and tx outcomes
   • Tune cycle interval and action cap

---

Getting Started

Prerequisites

• Node.js 20+
• npm 10+
• EVM RPC endpoint
• Funded keeper wallet private key (for write strategies)

Installation

1. Clone the Repository

git clone https://github.com/StabilityNexus/TODO-EVM-Keeper.git
cd TODO-EVM-Keeper

2. Install Dependencies

npm ci

3. Configure Environment Variables(.env.example)

Create a .env file in the root directory:

KEEPER_STRATEGY=noop
RPC_URL=
EXPECTED_CHAIN_ID=
PRIVATE_KEY=
CONTRACT_ADDRESS=
TX_CONFIRMATIONS=1
MAX_ACTIONS_PER_CYCLE=25
KEEPER_INTERVAL_MS=15000
DRY_RUN=false
LOG_LEVEL=info

Public free RPC options you can use for RPC_URL:

• Base Mainnet (8453): https://mainnet.base.org
• Base Sepolia (84532): https://sepolia.base.org
• BNB Smart Chain Mainnet (56): https://bsc-dataseed.bnbchain.org
• BNB Smart Chain Testnet (97): https://bsc-testnet-dataseed.bnbchain.org
• Polygon PoS Mainnet (137): https://polygon-bor-rpc.publicnode.com
• Polygon Amoy (80002): https://polygon-amoy-bor-rpc.publicnode.com

4. Run the Keeper

# one cycle
npm run start:once

# continuous loop
npm run start

# no transactions, log-only
npm run start:dry-run

5. Verify Execution

Check terminal logs for:

• network and signer initialization
• detected work items
• executed transactions (or dry-run actions)

---

App Screenshots

Keeper runtime log examples (replace with actual screenshots or terminal captures):

Startup logs	Dry-run cycle logs	Transaction execution logs

---

Contributing

Don't forget to star this repository if you find it useful.

Thank you for considering contributing to this project! Contributions are highly appreciated and welcomed. To ensure smooth collaboration, please refer to our Contribution Guidelines.

---

Maintainers

TODO: Add maintainer information

• Maintainer Name
• Maintainer Name

---

License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.

---

Thanks To All Contributors

Thanks a lot for spending your time helping TODO grow. Keep rocking.

© 2025 Stability Nexus