diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..c6c8b36 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,9 @@ +root = true + +[*] +indent_style = space +indent_size = 2 +end_of_line = lf +charset = utf-8 +trim_trailing_whitespace = true +insert_final_newline = true diff --git a/.eslintrc.json b/.eslintrc.json new file mode 100644 index 0000000..532bb7a --- /dev/null +++ b/.eslintrc.json @@ -0,0 +1,15 @@ +{ + "env": { + "node": true, + "es2021": true + }, + "extends": ["eslint:recommended"], + "parserOptions": { + "ecmaVersion": 12 + }, + "rules": { + "semi": ["error", "always"], + "quotes": ["error", "single"], + "no-unused-vars": "warn" + } +} diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..782a0ad --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,10 @@ +version: 2 +updates: + - package-ecosystem: "npm" + directory: "/" + schedule: + interval: "weekly" + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" diff --git a/.gitignore.local.bak b/.gitignore.local.bak new file mode 100644 index 0000000..3bb22dd --- /dev/null +++ b/.gitignore.local.bak @@ -0,0 +1,15 @@ +# Node +node_modules/ +dist/ +.env +.DS_Store + +# Logs +npm-debug.log* +yarn-debug.log* +yarn-error.log* + +# Editor +.vscode/ +.idea/ +*.swp diff --git a/.prettierrc b/.prettierrc new file mode 100644 index 0000000..fcb051c --- /dev/null +++ b/.prettierrc @@ -0,0 +1,6 @@ +{ + "semi": true, + "singleQuote": true, + "trailingComma": "es5", + "printWidth": 80 +} diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..5a9033a --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,21 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We pledge to make participation in our project a harassment-free experience for everyone. + +## Our Standards + +- Respectful communication +- No discrimination or harassment +- Accept constructive feedback + +## Enforcement + +Violations may result in removal from the project. + +## Contact + +For code of conduct issues, email: conduct@eremoscore.org + +[Full text: https://www.contributor-covenant.org/version/2/1/code_of_conduct/] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..30177f0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,48 @@ +# Contributing to Eremos Core + +Thank you for your interest in contributing! + +--- + +## Pull Request Rules + +- **Small, focused PRs:** One feature or fix per PR. +- **Descriptive commit messages:** Use `docs:`, `feat:`, `fix:`, `chore:` prefixes. +- **Tests required:** Add/maintain tests for new features. +- **Follow code style:** See `.prettierrc`, `.editorconfig`, and linter config. + +--- + +## Development Workflow + +1. **Fork the repo** and create your branch: + `git checkout -b feat/my-feature` +2. **Make your changes** and commit: + `git commit -m "feat: add new agent adapter"` +3. **Run tests and linter:** + `npm run lint && npm test` +4. **Push and open a PR:** + - Fill out the PR template. + - Reference related issues. + - Add screenshots if relevant. + +--- + +## Code Style + +- Use Prettier for formatting. +- Follow ESLint rules. +- Write clear, concise comments. + +--- + +## Community + +- Join [Discussions](https://github.com/EremosCore/Eremos/discussions) +- Respectful, inclusive communication. + +--- + +## License + +MIT © Eremos Core diff --git a/README.local.bak b/README.local.bak new file mode 100644 index 0000000..63aec00 --- /dev/null +++ b/README.local.bak @@ -0,0 +1,90 @@ +# Eremos Core + +[![Build Status](https://img.shields.io/github/actions/workflow/status/EremosCore/Eremos/ci.yml?branch=main)](https://github.com/EremosCore/Eremos/actions) +[![License](https://img.shields.io/github/license/EremosCore/Eremos)](LICENSE) +[![Issues](https://img.shields.io/github/issues/EremosCore/Eremos)](https://github.com/EremosCore/Eremos/issues) +[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md) + +> **Eremos Core** powers open, composable swarm agents for Solana and beyond. + +--- + +## Table of Contents + +- [Overview](#overview) +- [Architecture](#architecture) +- [Quickstart](#quickstart) +- [Usage Examples](#usage-examples) +- [Contributing](#contributing) +- [License](#license) + +--- + +## Overview + +Eremos Core is an open-source framework for building and deploying swarm agents on Solana. It enables decentralized coordination, composability, and transparency for agent-based systems. + +--- + +## Architecture + +![Eremos Architecture Diagram](docs/architecture.svg) + +- **Swarm Agents:** Modular, composable agents that interact with Solana and each other. +- **Core Engine:** Orchestrates agent lifecycle, messaging, and state. +- **Adapters:** Integrate with Solana, external APIs, and custom logic. +- **CLI & SDK:** Tools for deploying, monitoring, and extending agents. + +--- + +## Quickstart + +```sh +# 1. Clone the repo +git clone https://github.com/EremosCore/Eremos.git +cd Eremos + +# 2. Install dependencies +npm install + +# 3. Run the demo +npm run demo +``` + +See [docs/QUICKSTART.md](docs/QUICKSTART.md) for full setup instructions. + +--- + +## Usage Examples + +### 1. Launch a Swarm Agent + +```js +import { SwarmAgent } from 'eremos-core'; + +const agent = new SwarmAgent({ + name: 'SolanaIndexer', + adapters: ['solana', 'http'], + onMessage: (msg) => { /* handle messages */ }, +}); + +agent.start(); +``` + +### 2. Real-World Use Cases + +- **Solana Indexer:** Aggregate and analyze on-chain data. +- **DeFi Arbitrage Bot:** Coordinate multiple agents for cross-protocol trading. +- **NFT Discovery:** Swarm agents crawl and index NFT metadata. + +--- + +## Contributing + +We welcome PRs! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. + +--- + +## License + +MIT © Eremos Core diff --git a/README.md b/README.md index 2cd120f..1558ada 100644 --- a/README.md +++ b/README.md @@ -121,6 +121,28 @@ If you're a designer, artist, or just have ideas that fit the mythos - send us a MIT © Eremos LLC +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) + +## Security & Governance + +- [Security Policy](SECURITY.md) +- [Code of Conduct](CODE_OF_CONDUCT.md) + +## Examples + +See [`examples/`](examples/) for starter agents: +- Scam Detector +- Whale Tracker +- MEV Monitor + +## Developer Sandbox + +See [docs/DEVELOPMENT_SANDBOX.md](docs/DEVELOPMENT_SANDBOX.md) for local testnet setup. + +## Advanced Guide + +See [docs/ADVANCED_GUIDE.md](docs/ADVANCED_GUIDE.md) for custom agents, deployment, and dashboards. + --- ## Links diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..6631a1e --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,24 @@ +# Security Policy + +## Reporting Vulnerabilities + +If you discover a security vulnerability in Eremos Core, please report it responsibly: + +- Email: security@eremoscore.org +- Do not disclose publicly until a fix is released. +- Include as much detail as possible (steps to reproduce, impact, etc.). + +## Responsible Disclosure + +We follow industry best practices for responsible disclosure. We will acknowledge your report, investigate promptly, and credit you in release notes if desired. + +## Security Practices + +- Regular dependency audits (see Dependabot config) +- CI/CD checks for vulnerabilities +- SPDX license headers in all source files +- Contributor code review for security-sensitive changes + +## Supported Versions + +Only the latest major release is actively maintained for security. diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..4c52f89 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,22 @@ +version: '3.8' +services: + solana-testnet: + image: solanalabs/solana:v1.16.10 + command: solana-test-validator + ports: + - "8899:8899" + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:8899"] + interval: 10s + timeout: 5s + retries: 5 + + eremos-agent: + build: . + environment: + - SOLANA_RPC_URL=http://solana-testnet:8899 + depends_on: + - solana-testnet + volumes: + - ./examples:/app/examples + command: npm run demo diff --git a/docs/ADVANCED_GUIDE.md b/docs/ADVANCED_GUIDE.md new file mode 100644 index 0000000..a16234b --- /dev/null +++ b/docs/ADVANCED_GUIDE.md @@ -0,0 +1,27 @@ +# Advanced Guide + +## Building Custom Agents + +- Extend `SwarmAgent` with custom logic and adapters. +- Use config files for modularity. + +## Deploying on Solana Testnet + +- Use the provided `docker-compose.yml` to launch a testnet. +- Set `SOLANA_RPC_URL` in your agent config. + +## Connecting Dashboards + +- Integrate with analytics dashboards via agent adapters. +- Example: Connect to Prometheus or Grafana for metrics. + +## Best Practices + +- Use SPDX license headers. +- Follow security and code of conduct guidelines. +- Run dependency audits regularly. + +## Resources + +- [Security Policy](../SECURITY.md) +- [Code of Conduct](../CODE_OF_CONDUCT.md) diff --git a/docs/DEVELOPMENT_SANDBOX.md b/docs/DEVELOPMENT_SANDBOX.md new file mode 100644 index 0000000..f71db84 --- /dev/null +++ b/docs/DEVELOPMENT_SANDBOX.md @@ -0,0 +1,26 @@ +# Developer Sandbox + +Spin up a local Solana testnet and Eremos agent for rapid development. + +## Prerequisites + +- Docker & Docker Compose + +## Usage + +```sh +docker-compose up +``` + +- Access Solana testnet at `localhost:8899` +- Eremos agent runs with example configs from `/examples` + +## Customization + +- Edit `docker-compose.yml` to add more agents or adapters. +- Mount your own configs via the `volumes` section. + +## Troubleshooting + +- Ensure Docker is running. +- Check logs with `docker-compose logs`. diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md new file mode 100644 index 0000000..f9d92fe --- /dev/null +++ b/docs/QUICKSTART.md @@ -0,0 +1,44 @@ +# Quickstart Guide + +Follow these steps to set up Eremos Core and launch your first swarm agent. + +--- + +## 1. Prerequisites + +- Node.js >= 18 +- npm >= 9 +- Git + +--- + +## 2. Clone the Repository + +```sh +git clone https://github.com/EremosCore/Eremos.git +cd Eremos +``` + +--- + +## 3. Install Dependencies + +```sh +npm install +``` + +--- + +## 4. Run the Demo + +```sh +npm run demo +``` + +--- + +## 5. Next Steps + +- Explore the [README.md](../README.md) for usage examples. +- Build your own agent using the SDK. +- Join the community and contribute! diff --git a/docs/architecture.svg b/docs/architecture.svg new file mode 100644 index 0000000..00c7e47 --- /dev/null +++ b/docs/architecture.svg @@ -0,0 +1,20 @@ + + + Core Engine + + Swarm Agent + + Swarm Agent + + Swarm Agent + + Solana + + External APIs + + + + + + + diff --git a/examples/mev_monitor_agent.config.json b/examples/mev_monitor_agent.config.json new file mode 100644 index 0000000..89fac41 --- /dev/null +++ b/examples/mev_monitor_agent.config.json @@ -0,0 +1,5 @@ +{ + "name": "MEVMonitor", + "adapters": ["solana"], + "monitorMEV": true +} diff --git a/examples/mev_monitor_agent.js b/examples/mev_monitor_agent.js new file mode 100644 index 0000000..f4a548f --- /dev/null +++ b/examples/mev_monitor_agent.js @@ -0,0 +1,15 @@ +// SPDX-License-Identifier: MIT +// Simple MEV Monitor Agent Example +const { SwarmAgent } = require('eremos-core'); + +const agent = new SwarmAgent({ + name: 'MEVMonitor', + adapters: ['solana'], + onMessage: (msg) => { + if (msg.type === 'transaction' && msg.data.isMEV) { + console.log('MEV opportunity:', msg.data); + } + }, +}); + +agent.start(); diff --git a/examples/scam_detector_agent.config.json b/examples/scam_detector_agent.config.json new file mode 100644 index 0000000..0bab2fe --- /dev/null +++ b/examples/scam_detector_agent.config.json @@ -0,0 +1,5 @@ +{ + "name": "ScamDetector", + "adapters": ["solana"], + "rules": ["flag-suspicious-tx"] +} diff --git a/examples/scam_detector_agent.js b/examples/scam_detector_agent.js new file mode 100644 index 0000000..135b528 --- /dev/null +++ b/examples/scam_detector_agent.js @@ -0,0 +1,15 @@ +// SPDX-License-Identifier: MIT +// Scam Detector Agent Example +const { SwarmAgent } = require('eremos-core'); + +const agent = new SwarmAgent({ + name: 'ScamDetector', + adapters: ['solana'], + onMessage: (msg) => { + if (msg.type === 'transaction' && msg.data.suspicious) { + console.log('Scam detected:', msg.data); + } + }, +}); + +agent.start(); diff --git a/examples/whale_tracker_agent.config.json b/examples/whale_tracker_agent.config.json new file mode 100644 index 0000000..4e0c543 --- /dev/null +++ b/examples/whale_tracker_agent.config.json @@ -0,0 +1,5 @@ +{ + "name": "WhaleTracker", + "adapters": ["solana"], + "threshold": 100000 +} diff --git a/examples/whale_tracker_agent.js b/examples/whale_tracker_agent.js new file mode 100644 index 0000000..f94b174 --- /dev/null +++ b/examples/whale_tracker_agent.js @@ -0,0 +1,15 @@ +// SPDX-License-Identifier: MIT +// Whale Tracker Agent Example +const { SwarmAgent } = require('eremos-core'); + +const agent = new SwarmAgent({ + name: 'WhaleTracker', + adapters: ['solana'], + onMessage: (msg) => { + if (msg.type === 'transaction' && msg.data.amount > 100000) { + console.log('Whale transaction:', msg.data); + } + }, +}); + +agent.start();