diff --git a/README.md b/README.md index 2cd120f..3b404ca 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,35 @@ +
+ # Eremos ![Eremos](docs/banner2.png) **Autonomous swarm agents for early on-chain signal detection** -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. +[![MIT License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/) +[![Solana](https://img.shields.io/badge/Solana-9945FF?logo=solana&logoColor=white)](https://solana.com/) +[![Twitter Follow](https://img.shields.io/twitter/follow/EremosCore?style=social)](https://twitter.com/EremosCore) + +[Getting Started](#getting-started) • [Documentation](#documentation) • [Contributing](#contributing) • [Links](#links) + +
--- -

+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. + +## Quick Overview + +

Agent Theron
Theron - Agent (000) -

+
**Meet Theron - Agent-000** -*The first deployed agent in the swarm. Passive. Pattern-sensitive. -Modular and extendable by design.* - +*The first deployed agent in the swarm. Passive. Pattern-sensitive. Modular and extendable by design.* -**Agent-001 Coming Soon** [Teaser #1](https://x.com/EremosCore/status/1949154939923833239), [Teaser #2](https://x.com/EremosCore/status/1954856345284567218) +**Agent-001 Coming Soon** • [Teaser #1](https://x.com/EremosCore/status/1949154939923833239) • [Teaser #2](https://x.com/EremosCore/status/1954856345284567218) --- @@ -30,18 +40,18 @@ Modular and extendable by design.* - **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.* - +- **Launch Wallet Detection** - Trace freshly funded wallets from CEXs, track contract interactions, and flag high-confidence deploys in real time +- **Ghost Watcher** - Monitor long-dormant wallets that suddenly reactivate. Perfect for tracing old dev wallets or rug setups +- **Confidence Scoring** - Behavioral heuristics provide 0-1 confidence scores for all signals +- *+ More agents in development* --- ## Example Signal -An example signal emitted by an agent detecting a live token deployment: +Here's what a live token deployment detection looks like: -```ts +```typescript [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) @@ -59,74 +69,176 @@ An example signal emitted by an agent detecting a live token deployment: } ``` ---- - ## Signal Confidence 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 -Confidence is computed via agent-side scoring and logged alongside the signal. +- **CEX-origin funding** (Kraken, Coinbase, etc.) +- **Timing patterns** (funding → deploy intervals) +- **Wallet linkage density** (bundled activity detection) +- **Token metadata validation** +- **Historical behavior analysis** + +Confidence is computed via agent-side scoring and logged alongside each signal. --- ## Tech Stack -- **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 +| Layer | Technology | +|-------|------------| +| **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 | +| **Blockchain** | Solana ecosystem | --- ## Getting Started +### Prerequisites + +- Node.js 18+ +- npm or yarn +- Basic knowledge of TypeScript + +### Installation + ```bash +# Clone the repository git clone https://github.com/EremosCore/Eremos.git cd Eremos + +# Install dependencies npm install + +# Set up environment +cp .env.example .env.local + +# Start development mode +npm run dev ``` -Set up your environment: +### Quick Test + +Test an agent with the development script: ```bash -cp .env.example .env.local -npm run dev +# Run example agent +npx ts-node scripts/dev-agent.ts + +# Generate a test signal +npx ts-node scripts/generate-signal.ts +``` + +--- + +## Project Structure + ``` +Eremos/ +├── agents/ # Agent templates & logic +│ ├── theron.ts # Agent-000 (Memory Vault) +│ ├── observer.ts # Surveillance Agent +│ ├── harvester.ts # Indexing Agent +│ └── example.ts # Template for custom agents +├── utils/ # Shared utilities +│ ├── signal.ts # Signal generation & hashing +│ ├── logger.ts # Logging utilities +│ └── throttle.ts # Signal throttling +├── types/ # TypeScript definitions +├── scripts/ # Development & testing scripts +└── docs/ # Documentation & whitepaper +``` + +--- + +## Documentation + +| Document | Description | +|----------|-------------| +| [Architecture](docs/architecture.md) | System design and agent communication | +| [Agent Guide](docs/agents.md) | Creating custom agents | +| [Signals](docs/signals.md) | Signal types and taxonomy | +| [Memory System](docs/memory.md) | Agent memory and state management | +| [Glyphs](docs/glyphs.md) | Agent identification symbols | +| [Deployment](docs/deployment.md) | Production deployment guide | --- -## Key Folders +## Available Agents -- `/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 +| Agent | Glyph | Role | Watch Type | Description | +|-------|-------|------|------------|-------------| +| **Theron** | Ϸ | Memory Vault | Anomaly Detection | The first observer. Archives anomalies, stores primordial memory | +| **Observer** | φ | Surveillance | Wallet Activity | Passive agent logging unusual wallet clustering | +| **Harvester** | λ | Indexing | Mint Activity | Indexes mint data for high-volume collections | +| **LaunchTracker** | Σ | Launch Monitor | Wallet Activity | Monitors CEX-funded wallets for high-confidence launches | +| **Skieró** | ψ | Ghost Watcher | Dormant Wallets | Tracks long-dormant wallets that suddenly reactivate | --- ## 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) +We welcome contributions from the community! Here's how you can help: + +### For Developers + +1. **Fork the repository** +2. **Check out** `/agents/example.ts` for agent structure +3. **Build your own observer** following the modular pattern +4. **Test using** `/scripts/dev-agent.ts` +5. **Submit a pull request** + +### For Designers & Artists + +Have ideas that fit the Eremos mythos? We'd love to hear from you! +Send us a DM on [Twitter @EremosCore](https://x.com/EremosCore) + +### Development Guidelines + +- Keep agent logic scoped and clean +- Use `generateSignalHash()` for all signal outputs +- Log using the shared `logSignal()` utility +- Follow TypeScript best practices +- Test agents using provided scripts + +--- + +## Development Scripts + +| Script | Purpose | +|--------|---------| +| `scripts/dev-agent.ts` | Test individual agents | +| `scripts/generate-signal.ts` | Generate test signals | +| `scripts/stress-test.ts` | Performance testing | +| `scripts/validate-agent.ts` | Validate agent configuration | --- ## License -MIT © Eremos LLC +MIT © [Eremos LLC](LICENSE) + +This project is released under the MIT License. Use it, fork it, fragment it, build your own swarm. --- ## Links -- **Twitter/X:** [@EremosCore](https://x.com/EremosCore) -- **Website:** [Eremos.io](https://www.eremos.io/) -- **Whitepaper:** [v1.0 PDF](docs/whitepaper.pdf) +
+ +[![Twitter](https://img.shields.io/badge/Twitter-1DA1F2?style=for-the-badge&logo=twitter&logoColor=white)](https://x.com/EremosCore) +[![Website](https://img.shields.io/badge/Website-000000?style=for-the-badge&logo=safari&logoColor=white)](https://www.eremos.io/) +[![Whitepaper](https://img.shields.io/badge/Whitepaper-FF0000?style=for-the-badge&logo=adobe-acrobat-reader&logoColor=white)](docs/whitepaper.pdf) + +**Maintained by the Eremos Core team 💛** + +
+ +--- -_Maintained by the Eremos Core team 💛._ +
+ Eremos is a decentralized observer system built for Solana - designed to detect early signals from the edges of on-chain noise. +
diff --git a/agents/index.ts b/agents/index.ts new file mode 100644 index 0000000..a9dab8e --- /dev/null +++ b/agents/index.ts @@ -0,0 +1,23 @@ +export { Theron } from './theron'; +export { Observer } from './observer'; +export { Harvester } from './harvester'; +export { LaunchTracker } from './launchtracker'; +export { GhostWatcher } from './skieró'; +export { ExampleAgent } from './example'; + +// Agent registry for scripts that need it +import { Theron } from './theron'; +import { Observer } from './observer'; +import { Harvester } from './harvester'; +import { LaunchTracker } from './launchtracker'; +import { GhostWatcher } from './skieró'; +import { ExampleAgent } from './example'; + +export const agents = [ + Theron, + Observer, + Harvester, + LaunchTracker, + GhostWatcher, + ExampleAgent +]; diff --git a/package.json b/package.json index 75703f0..b20603c 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,8 @@ "description": "Modular agent framework for on-chain activity monitoring.", "main": "index.js", "scripts": { - "dev": "echo 'Running dev mode...'" + "dev": "echo 'Running dev mode...'", + "agents:list": "npx ts-node scripts/agent-list.ts" }, "keywords": [ "agent", @@ -14,5 +15,10 @@ "framework" ], "license": "MIT", - "author": "EremosCore" + "author": "EremosCore", + "devDependencies": { + "@types/node": "^20.0.0", + "ts-node": "^10.9.0", + "typescript": "^5.0.0" + } } diff --git a/utils/logger.ts b/utils/logger.ts index ddb7a7f..51adc3e 100644 --- a/utils/logger.ts +++ b/utils/logger.ts @@ -4,9 +4,11 @@ export function logSignal(signal: { glyph: string; hash: string; timestamp: string; + confidence?: number; details?: Record; }) { - console.log(`[${signal.agent}] stored signal ${signal.hash} (${signal.type}) at ${signal.timestamp}`); + const confidenceStr = signal.confidence ? ` (confidence: ${signal.confidence})` : ''; + console.log(`[${signal.agent}] stored signal ${signal.hash} (${signal.type})${confidenceStr} at ${signal.timestamp}`); if (signal.details) { console.log(`├─ context:`, JSON.stringify(signal.details, null, 2)); }