Skip to content

docs: comprehensive documentation improvements with enhanced README #80

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Haleem001 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: comprehensive documentation improvements with enhanced README #80

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
be4b744
improved the README structure and edited the docs to add more details…
Haleem001 Aug 18, 2025
d9fc69b
Added the Eremoscore repo link
Haleem001 Aug 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
253 changes: 185 additions & 68 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,130 +2,247 @@

![Eremos](docs/banner2.png)

**Autonomous swarm agents for early on-chain signal detection**
<div align="center">

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.
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-43853D?style=flat&logo=node.js&logoColor=white)](https://nodejs.org/)
[![Solana](https://img.shields.io/badge/Solana-9945FF?style=flat&logo=solana&logoColor=white)](https://solana.com/)
[![Next.js](https://img.shields.io/badge/Next.js-000000?style=flat&logo=next.js&logoColor=white)](https://nextjs.org/)

</div>

<p align="center">
<strong>πŸ€– Autonomous swarm agents for early on-chain signal detection</strong>
</p>

<p align="center">
Eremos is a lightweight framework for deploying modular agents that monitor blockchain activityβ€”tracking wallet clusters, mint patterns, and contract anomalies. Designed for developers who want low-noise, early signals embedded into their workflows.
</p>

---

## πŸ“‘ Table of Contents

- [Features](#features)
- [Meet Theron (Agent-000)](#meet-theron-agent-000)
- [Quick Start](#quick-start)
- [Installation & Configuration](#installation--configuration)
- [Project Structure](#project-structure)
- [Signal Detection](#signal-detection)
- [Tech Stack](#tech-stack)
- [Development](#development)
- [Performance & Monitoring](#performance--monitoring)
- [Roadmap](#roadmap)
- [Links](#links)
- [License](#license)

---

## ✨ Features

### Core Capabilities
- πŸ€– **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

### Detection Modules
- πŸš€ **Launch Wallet Detection:** Trace freshly funded wallets (e.g. from CEXs), track contract interactions, and flag high-confidence deploys in real time
- πŸ‘» **Ghost Watcher:** Monitors long-dormant wallets that suddenly become active again
- 🌾 **Harvester Agent:** Advanced pattern recognition for complex trading behaviors
- πŸ“Š **Observer Agent:** Real-time monitoring and signal correlation
- ⚑ **Skieró Agent:** Lightning-fast event detection and processing

---

## πŸ€– Meet Theron (Agent-000)

<p align="center">
<img src="docs/therontphd2.png" alt="Agent Theron" width="155"/><br/>
<em>Theron - Agent (000)</em>
</p>

**Meet Theron - Agent-000**
*The first deployed agent in the swarm. Passive. Pattern-sensitive.
Modular and extendable by design.*
Theron is the first deployed agent in the swarm. Passive, pattern-sensitive, modular, and extendable by design. Specializes in detecting early-stage token launches and suspicious wallet patterns across Solana.

---

## πŸš€ Quick Start

```bash
# Clone the repository
git clone https://github.com/Haleem001/Eremos.git
cd Eremos

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env.local
# Edit .env.local with your Solana RPC credentials

# Start development
npm run dev
```

**Agent-001 Coming Soon** [Teaser](https://x.com/EremosCore/status/1949154939923833239)
Visit `http://localhost:3000` to access the dashboard.

---

## Features
## πŸ“¦ Installation & Configuration

- **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.
### Prerequisites

- Node.js (v18+)
- npm (v8+)
- Git
- Solana RPC endpoint

### Environment Variables

| Variable | Description | Required | Default |
|-------------------------|-----------------------------|----------|-----------|
| `SOLANA_RPC_URL` | Solana RPC endpoint | βœ… | - |
| `SOLANA_WEBSOCKET_URL` | WebSocket endpoint | βœ… | - |
| `LOG_LEVEL` | Logging verbosity | ❌ | `info` |
| `AGENT_POLL_INTERVAL` | Agent polling interval (ms) | ❌ | `5000` |
| `CONFIDENCE_THRESHOLD` | Minimum confidence for signals | ❌ | `0.7` |

Edit `.env.local` with your preferred settings.

---

## πŸ“ Project Structure

```
Eremos/
β”œβ”€β”€ agents/ # Agent templates & logic
β”‚ β”œβ”€β”€ example.ts
β”‚ └── theron.ts
β”œβ”€β”€ docs/ # Documentation & whitepaper
β”‚ β”œβ”€β”€ whitepaper.pdf
β”‚ └── architecture.md
β”œβ”€β”€ scripts/ # Bootstrap and deployment scripts
β”‚ β”œβ”€β”€ setup.js
β”‚ └── deploy.js
β”œβ”€β”€ tests/ # Tests
β”‚ β”œβ”€β”€ example.test.ts
β”‚ └── throttle.test.ts
β”œβ”€β”€ types/ # TypeScript interfaces + definitions
β”‚ β”œβ”€β”€ agent.ts
β”‚ └── signal.ts
β”œβ”€β”€ utils/ # Shared utilities
β”‚ β”œβ”€β”€ signal.ts
β”‚ β”œβ”€β”€ logging.ts
β”‚ └── blockchain.ts
β”œβ”€β”€ .env.example
β”œβ”€β”€ package.json
β”œβ”€β”€ LICENSE
└── tsconfig.json
```

---

## Example Signal
## πŸ“‘ Signal Detection

An example signal emitted by an agent detecting a live token deployment:
### Example Output

```ts
```bash
[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)
```

### Signal Schema

```json
{
agent: "Observer",
type: "launch_detected",
glyph: "Ξ”",
hash: "sig_c7f9a3d2bc",
timestamp: "2025-06-12T04:41:25Z",
source: "agent-observer",
confidence: 0.91
"agent": "Observer",
"type": "launch_detected",
"glyph": "Ξ”",
"hash": "sig_c7f9a3d2bc",
"timestamp": "2025-06-12T04:41:25Z",
"source": "agent-observer",
"confidence": 0.91
}
```

### Confidence Scoring

- CEX-origin funding: +0.2
- Time between funding β†’ deploy: +0.15
- Wallet linkage density: +0.25
- Token metadata validation: +0.1
- Historical pattern matching: +0.3

---

## Signal Confidence
## πŸ›  Tech Stack

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
| Category | Technology |
|---------------|-----------------------------------------------|
| Frontend | Next.js, Tailwind CSS, TypeScript |
| Backend | Node.js, TypeScript |
| Language | TypeScript (typed logic across agents, utils, and infra) |
| Chain Layer | RPC watchers, Mempool filters, native triggers|

Confidence is computed via agent-side scoring and logged alongside the signal.

---

## Tech Stack
## πŸ”§ Development

- **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
### Available Scripts

---
| Command | Description |
|---------|-------------|
| `npm run dev` | Start development server |
| `npm run build` | Build for production |
| `npm run start` | Start production server |
| `npm run lint` | Run ESLint |
| `npm run type-check` | Run TypeScript type checking |
| `npm test` | Run test suite |

## Getting Started
### Creating Custom Agents

```bash
git clone https://github.com/EremosCore/Eremos.git
cd Eremos
npm install
```
1. **Create Agent File:** Add a new TypeScript file in the `/agents/` directory
2. **Implement Interface:** Follow the agent interface defined in `/types/agent.ts`
3. **Register Agent:** Add your agent to the main configuration
4. **Test & Deploy:** Run tests and verify signal detection works as expected

Set up your environment:

```bash
cp .env.example .env.local
npm run dev
```
See existing agents like [`theron.ts`](agents/theron.ts), [`observer.ts`](agents/observer.ts), or [`harvester.ts`](agents/harvester.ts) for implementation examples.

---

## Key Folders
## πŸ“Š Performance & Monitoring

- `/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
- Real-time agent monitoring
- Signal latency tracking (<100ms)
- Memory-efficient design
- Configurable alerting

---

## Contributing

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)
## πŸ”— Links

- 🐦 [Twitter/X](https://x.com/EremosCore)
- 🌐 [Website](https://www.eremos.io/)
- πŸ“„ [Whitepaper](./docs/whitepaper.pdf)
- πŸ“š [Documentation](./docs/)
- πŸ™ [GitHub Repository](https://github.com/EremosCore/Eremos)

---

## License
## πŸ“„ License

MIT Β© Eremos LLC

---

## Links

- **Twitter/X:** [@EremosCore](https://x.com/EremosCore)
- **Website:** [Eremos.io](https://www.eremos.io/)
- **Whitepaper:** [v1.0 PDF](docs/whitepaper.pdf)

_Maintained by the Eremos Core team πŸ’›._
<div align="center">
<strong>Maintained by the Eremos Core team πŸ’›</strong>
<em>Building the future of on-chain intelligence</em>
</div>
Loading