From 9fcda340f59aa8e634b9418ccfcd9a5ebad341ed Mon Sep 17 00:00:00 2001 From: IAM-CW Date: Sun, 17 Aug 2025 18:35:06 +0100 Subject: [PATCH] Improved README with detailed setup instructions --- README.md | 195 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 112 insertions(+), 83 deletions(-) diff --git a/README.md b/README.md index 2cd120f..3d26a33 100644 --- a/README.md +++ b/README.md @@ -1,132 +1,161 @@ # Eremos -![Eremos](docs/banner2.png) +![Open Source](https://img.shields.io/badge/Open%20Source-Yes-brightgreen) +![MIT License](https://img.shields.io/badge/License-MIT-blue) +![Solana Ecosystem](https://img.shields.io/badge/Built%20for-Solana-blueviolet) -**Autonomous swarm agents for early on-chain signal detection** +*Eremos is an open design for deploying self-governing "swarm agents" that monitor on-chain activities across the Solana ecosystem to reveal early warning signs before they become bigger issues. It aims to improve understanding and prioritize simplicity for all, created for the public good.* -Eremos is a lightweight framework for deploying modular agents that monitor blockchain activity - tracking wallet clusters, mint patterns, and contract anomalies. -Designed for devs who want low-noise, early signals embedded into their workflows. +--- + +![Eremos Architecture](./images/eremos-architecture.png) + +## Quick Links + +- [Website](https://www.eremos.io/) +- [GitHub](https://github.com/EremosCore/Eremos) +- [Twitter/X](https://x.com/EremosCore) --- -

- Agent Theron
- Theron - Agent (000) -

+## Getting Started -**Meet Theron - Agent-000** -*The first deployed agent in the swarm. Passive. Pattern-sensitive. -Modular and extendable by design.* +1. **Fork this repo:** + [Eremos on GitHub](https://github.com/EremosCore/Eremos) +2. **Customize your fork:** +After forking this project, you don’t have to just copy it, you can make it something you'd like to see! +- Remake or improve the README to better fit the project’s purpose or audience. +- Update documentation, add new diagrams, or clarify instructions. +- Reorganize any folders or files to match a workflow you like. +- Push your changes to your fork (and send a pull request if you think your improvements would help others!). -**Agent-001 Coming Soon** [Teaser #1](https://x.com/EremosCore/status/1949154939923833239), [Teaser #2](https://x.com/EremosCore/status/1954856345284567218) +Open source thrives on improvement and personalization, so don’t be afraid to remix! ---- +3. **Install dependencies:** +This project is built with **TypeScript**, so it requires **TypeScript** and **Node.js type definitions**. All necessary dependencies including TypeScript are installed automatically when you run the following command in your project folder. -## Features +To do this: -- **Modular Agents** - Scoped logic for detecting wallet activity, contract spawns, and anomalies -- **Signal Emission** - Structured signals for logging, alerting, or downstream use -- **Swarm Design** - Each agent operates independently with shared utilities -- **Extensible Core** - Plug in watchers, inference layers, or custom triggers -- **Minimal Output** - Log only what matters -- **Launch Wallet Detection** - Agents can trace freshly funded wallets (e.g. from CEXs), track their contract interactions, and flag high-confidence deploys in real time -- **Ghost Watcher** - Monitors long-dormant wallets that suddenly become active again. Useful for tracing old dev wallets or rug setups. -- *+ More to come.* +1. Open your terminal (Command Prompt, PowerShell, or Terminal app). +2. Navigate to your project folder by running: + ``` + cd path/to/your/project + ``` ---- +3. Then, run the install command: -## Example Signal + ``` + npm install + ``` -An example signal emitted by an agent detecting a live token deployment: +This will download and install all the libraries your project needs to work properly. -```ts -[agent-observer] → fresh funding detected from kraken (wallet: 6Yxk...P2M8) at 04:41:12Z -[agent-observer] → contract probing detected within 4s (pump.fun interaction traced) -[agent-observer] → token created at 04:41:17Z (tx: 5gW...pump) -[agent-observer] → 5 bundle-linked wallets interacted within 8s of deploy -[agent-observer] → launch confidence spike (0.91) - emitting signal (elapsed: 13s) +4. **Set up your environment file:** +Most projects need environment variables (like API keys or custom settings) that you configure privately for your own setup. +- Duplicate the example environment file by running: -{ - agent: "Observer", - type: "launch_detected", - glyph: "Δ", - hash: "sig_c7f9a3d2bc", - timestamp: "2025-06-12T04:41:25Z", - source: "agent-observer", - confidence: 0.91 -} -``` + ``` + cp .env.example .env.local + ``` ---- +- Open `.env.local` in your editor and fill in the required fields (e.g., API keys, network URLs, custom options). -## Signal Confidence +**Why?** +This ensures your project has all the configuration info it needs to run correctly, such as connections to third-party services or your local development environment. +*If you’re unsure what to enter, check the comments in `.env.example` or ask a project maintainer.* -Each emitted signal includes a `confidence` score (0-1) based on behavioral heuristics: -- CEX-origin funding (e.g. Kraken, Coinbase) -- Time between funding → deploy -- Wallet linkage density (bundled activity) -- Token metadata validation +5. **Run a swarm agent:** +Eremos is built around autonomous agents that monitor blockchain activity in real time. To start operating, run one or more of these agents. +- Each agent is an independent Node.js process with modular logic. +- After installing dependencies and setting up your environment file, start an agent by running: -Confidence is computed via agent-side scoring and logged alongside the signal. + ``` + npm run start + ``` ---- +- This command launches the default swarm agent which scans blockchain data sources according to the logic in the `/agents` folder. +- You can run multiple agents simultaneously by starting separate processes or customizing agent configurations. +- Logs and signals emitted by agents display in your terminal, helping you monitor wallet activity, contract deployments, or anomalies. +- For development and customization, explore the `/agents` directory to create or modify agents tailored to your monitoring needs. -## Tech Stack +**Tip:** To stop an agent, press `Ctrl+C` in the terminal. Restarted agents continue scanning from the last known state based on saved checkpoints. -- **Frontend:** Next.js, Tailwind CSS -- **Backend:** Node.js (TypeScript-based agent runner) -- **Language:** TypeScript (typed logic across agents, utils, and infra) -- **Chain Layer:** RPC watchers, mempool filters, native triggers +_For detailed info on each agent’s configuration, signal types, and extending swarm capabilities, visit the [official docs](https://github.com/EremosCore/Eremos/tree/main/docs) and the `/agents` folder._ ---- +6. **Check logs and outputs:** +Each agent tracks activity and highlights relevant signals in real time. -## Getting Started +*For detailed setup, visit our [agent folder on GitHub](https://github.com/EremosCore/Eremos/tree/main/agents).* -```bash -git clone https://github.com/EremosCore/Eremos.git -cd Eremos -npm install -``` +--- -Set up your environment: +## What Are Swarm Agents? +> Self-governing bots that monitor money flows, identify trends, and provide rapid information allowing developers and analysts to take quicker action. -```bash -cp .env.example .env.local -npm run dev -``` +Agents can: +- Monitor blockchain updates continuously. +- Detect unusual or large transfers. +- Compile trend data for research and alerts. --- -## Key Folders +## Contribution Guide -- `/agents` - Agent templates + logic -- `/utils` - Shared signal/logging utilities -- `/types` - TypeScript interfaces + definitions -- `/scripts` - Bootstrap and dev scripts -- `/docs` - Swarm structure, architecture, & our artwork/official whitepaper +Contributors are very important to us! +- Watch and star this repository. +- Make your modifications after forking. +- Open a pull request (PR) and attach images for big changes. +- Need help? [Open an issue](https://github.com/EremosCore/Eremos/issues) or send a DM to us on Twitter. + +See [CONTRIBUTING.md](./CONTRIBUTING.md) for more tips. --- -## Contributing +## FAQ + +**Q: Is this for beginners?** +A: Yes! Eremos is designed for all skill levels. -We’re open to contributors. -If you are experienced in TypeScript and like agent-based systems, check `example.ts` and build your own observer. -If you're a designer, artist, or just have ideas that fit the mythos - send us a DM on Twitter. [@EremosCore](https://x.com/EremosCore) +**Q: Where can I ask questions?** +A: GitHub Issues, Twitter/X, or join our community on [Discord](#). --- ## License -MIT © Eremos LLC +MIT + +--- + +## Special Thanks + +The open-source community makes Eremos possible. Everyone is welcome to contribute to shaping its future! + +[CONTRIBUTING.md](./CONTRIBUTING.md) --- -## Links +# Contributing to Eremos + +Thank you for your interest in improving Eremos! + +## How to Contribute + +1. Fork the repository +2. Create a new branch for your change +3. Make edits or improvements +4. Commit changes and open a Pull Request (PR) + - Explain *why* your change is helpful. + - Attach screenshots if you changed or added diagrams! + +## Tips + +- Keep PRs clean and focused. +- Use clear commit messages (e.g., “Improved README with new diagram”). +- Be kind and constructive in comments. -- **Twitter/X:** [@EremosCore](https://x.com/EremosCore) -- **Website:** [Eremos.io](https://www.eremos.io/) -- **Whitepaper:** [v1.0 PDF](docs/whitepaper.pdf) +## Help -_Maintained by the Eremos Core team 💛._ +If you get stuck, open an issue or ask for help on [Twitter](https://twitter.com/EremosCore). Every contribution counts!