diff --git a/.env.example b/.env.example index be6cad6..e0258f3 100644 --- a/.env.example +++ b/.env.example @@ -1 +1,25 @@ -# No required environment variables yet +# Eremos Configuration + +# Solana RPC Configuration +SOLANA_RPC_URL=https://api.mainnet-beta.solana.com +SOLANA_WS_URL=wss://api.mainnet-beta.solana.com + +# Agent Configuration +AGENT_LOG_LEVEL=info +AGENT_CONFIDENCE_THRESHOLD=0.7 +AGENT_ENABLE_WEBHOOKS=false + +# Optional: Custom RPC (for production use) +# CUSTOM_RPC_URL=your-custom-rpc-endpoint +# CUSTOM_RPC_API_KEY=your-api-key + +# Webhook Configuration (if enabled) +# WEBHOOK_URL=https://your-webhook-endpoint.com +# WEBHOOK_SECRET=your-webhook-secret + +# Development Settings +NODE_ENV=development +DEBUG=eremos:* + +# Optional: Database (for agent memory persistence) +# DATABASE_URL=postgresql://user:password@localhost:5432/eremos diff --git a/.eslintrc.json b/.eslintrc.json new file mode 100644 index 0000000..59d218d --- /dev/null +++ b/.eslintrc.json @@ -0,0 +1,38 @@ +{ + "root": true, + "parser": "@typescript-eslint/parser", + "parserOptions": { + "ecmaVersion": 2022, + "sourceType": "module", + "project": "./tsconfig.json" + }, + "plugins": ["@typescript-eslint"], + "extends": [ + "eslint:recommended", + "@typescript-eslint/recommended", + "@typescript-eslint/recommended-requiring-type-checking" + ], + "rules": { + "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }], + "@typescript-eslint/explicit-function-return-type": "warn", + "@typescript-eslint/no-explicit-any": "warn", + "@typescript-eslint/prefer-const": "error", + "@typescript-eslint/no-var-requires": "error", + "prefer-const": "error", + "no-var": "error", + "no-console": "warn", + "eqeqeq": ["error", "always"], + "curly": ["error", "all"] + }, + "env": { + "node": true, + "jest": true, + "es2022": true + }, + "ignorePatterns": [ + "dist/", + "node_modules/", + "coverage/", + "*.js" + ] +} diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..2f13548 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,62 @@ +name: CI + +on: + push: + branches: [main, develop] + pull_request: + branches: [main, develop] + +jobs: + test: + runs-on: ubuntu-latest + + strategy: + matrix: + node-version: [18.x, 20.x] + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Node.js ${{ matrix.node-version }} + uses: actions/setup-node@v4 + with: + node-version: ${{ matrix.node-version }} + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Run TypeScript type check + run: npm run type-check + + - name: Run linting + run: npm run lint + + - name: Check code formatting + run: npm run prettier:check + + - name: Run tests + run: npm test + + - name: Build project + run: npm run build + + prettier: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Check Prettier formatting + run: npx prettier --check "**/*.{ts,js,json,md,yml,yaml}" diff --git a/.prettierrc b/.prettierrc new file mode 100644 index 0000000..0c49f3a --- /dev/null +++ b/.prettierrc @@ -0,0 +1,29 @@ +{ + "semi": true, + "trailingComma": "es5", + "singleQuote": true, + "printWidth": 80, + "tabWidth": 2, + "useTabs": false, + "bracketSpacing": true, + "bracketSameLine": false, + "arrowParens": "avoid", + "endOfLine": "lf", + "quoteProps": "as-needed", + "proseWrap": "preserve", + "overrides": [ + { + "files": "*.md", + "options": { + "proseWrap": "always", + "printWidth": 120 + } + }, + { + "files": "*.json", + "options": { + "printWidth": 120 + } + } + ] +} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1ec554a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,253 @@ +# Contributing to Eremos + +Thank you for your interest in contributing to Eremos! This guide will help you get started with making meaningful contributions to our autonomous agent framework. + +## Getting Started + +### Prerequisites + +- Node.js 18 or higher +- Git +- TypeScript knowledge (recommended) +- Basic understanding of blockchain/Solana (helpful but not required) + +### Development Setup + +1. **Fork the repository** + ```bash + # Click the "Fork" button on GitHub, then: + git clone https://github.com/YOUR_USERNAME/Eremos.git + cd Eremos + ``` + +2. **Install dependencies** + ```bash + npm install + ``` + +3. **Create a feature branch** + ```bash + git checkout -b feature/your-feature-name + # or + git checkout -b fix/issue-description + ``` + +4. **Set up your environment** + ```bash + cp .env.example .env.local + # Edit .env.local with your configuration + ``` + +## Making Changes + +### Code Style Guidelines + +- **TypeScript First**: Use TypeScript with strict type checking +- **Formatting**: Code is automatically formatted with Prettier +- **Naming**: Use descriptive names for variables, functions, and files +- **Comments**: Add comments for complex logic, especially in agent detection algorithms + +### Testing + +Before submitting changes: + +```bash +# Run the full test suite +npm test + +# Run tests for specific component +npm test -- --testNamePattern="YourComponent" + +# Run linting +npm run lint + +# Fix linting issues automatically +npm run lint:fix + +# Type check +npm run type-check +``` + +### Commit Messages + +Use clear, descriptive commit messages: + +```bash +# Good examples: +git commit -m "feat: add launch detection to observer agent" +git commit -m "fix: resolve signal confidence calculation bug" +git commit -m "docs: update agent architecture documentation" +git commit -m "test: add unit tests for signal processor" + +# Use conventional commit prefixes: +# feat: new features +# fix: bug fixes +# docs: documentation changes +# test: adding or updating tests +# refactor: code refactoring +# style: formatting changes +# chore: maintenance tasks +``` + +## Types of Contributions + +### πŸ› Bug Fixes + +- Check [existing issues](https://github.com/AJibolaOnaneye/Eremos/issues) first +- Include reproduction steps in your PR description +- Add tests that verify the fix + +### ✨ New Features + +- Discuss major features in an issue first +- Follow existing patterns in the codebase +- Include comprehensive tests +- Update documentation as needed + +### πŸ“š Documentation + +- Fix typos, improve clarity, add examples +- Update README for structural changes +- Add inline code comments for complex logic +- Create or update docs in `/docs` folder + +### πŸ§ͺ Testing + +- Add tests for uncovered code paths +- Improve existing test reliability +- Add integration tests for agent workflows + +### 🎨 Visual/Structural Improvements + +Perfect for bounty submissions: +- Better README layout and organization +- Add useful badges and shields +- Improve code formatting consistency +- Better file/folder organization +- Add helpful developer tooling + +## Bounty-Specific Guidelines + +For the current bounty challenge, focus on: + +### README Improvements +- Better structure and navigation +- More comprehensive quick start guide +- Clear usage examples with code snippets +- Professional badges and project identity + +### Documentation Enhancements +- Fix formatting inconsistencies +- Add missing sections (API docs, troubleshooting) +- Improve onboarding clarity for new developers + +### Developer Experience +- Add missing config files (`.prettierrc`, `.eslintrc`) +- Create GitHub Actions for CI/CD +- Add helpful npm scripts +- Improve TypeScript configurations + +### Repository Organization +- Better folder structure +- Consistent file naming +- Clear separation of concerns +- Remove unused files + +## Pull Request Process + +### Before Submitting + +1. **Ensure your changes work** + ```bash + npm run dev # Test locally + npm test # All tests pass + npm run lint # No linting errors + ``` + +2. **Update documentation** if needed + +3. **Rebase on latest main** + ```bash + git fetch upstream + git rebase upstream/main + ``` + +### PR Template + +Use this template for your pull request: + +```markdown +## Description +Brief description of what this PR does. + +## Type of Change +- [ ] Bug fix +- [ ] New feature +- [ ] Documentation update +- [ ] Code refactoring +- [ ] Visual/structural improvement + +## Testing +- [ ] Tests pass locally +- [ ] Added new tests (if applicable) +- [ ] Manual testing completed + +## Screenshots (if applicable) +Before/after screenshots for visual changes. + +## Checklist +- [ ] Code follows project style guidelines +- [ ] Self-review completed +- [ ] Documentation updated +- [ ] No breaking changes (or clearly documented) +``` + +### Review Process + +1. **Automated checks** run on every PR +2. **Code review** by maintainers +3. **Testing** in staging environment +4. **Merge** after approval + +## Community Guidelines + +### Code of Conduct + +- Be respectful and inclusive +- Focus on constructive feedback +- Help others learn and grow +- Celebrate contributions of all sizes + +### Communication + +- **Issues**: For bug reports and feature requests +- **Discussions**: For questions and brainstorming +- **Twitter**: [@EremosCore](https://x.com/EremosCore) for announcements +- **Pull Requests**: For code contributions + +### Getting Help + +- Check existing issues and documentation first +- Ask questions in GitHub Discussions +- Join our community on X/Twitter +- Reach out to maintainers for complex problems + +## Recognition + +Contributors will be: +- Listed in our contributors section +- Mentioned in release notes for significant contributions +- Eligible for bounties and rewards +- Invited to community events and discussions + +--- + +**Ready to contribute?** + +1. Pick an issue or improvement area +2. Follow the setup steps above +3. Make your changes +4. Submit a clean pull request +5. Celebrate your contribution to the Solana ecosystem! πŸŽ‰ + +Thank you for helping make Eremos better for everyone! πŸ’› diff --git a/README.md b/README.md index 2cd120f..4e486f1 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,195 @@ **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. ---- +## Table of Contents + +- [Quick Start](#quick-start) +- [Usage Examples](#usage-examples) +- [Developer Guide](#developer-guide) +- [Architecture](#architecture) +- [Signal System](#signal-system) +- [Contributing](#contributing) +- [License](#license) + +## Quick Start + +### Prerequisites + +- Node.js 18+ +- npm or yarn +- Solana RPC endpoint (optional: own RPC for production) + +### Installation + +```bash +# Clone the repository +git clone https://github.com/AJibolaOnaneye/Eremos.git +cd Eremos + +# Install dependencies +npm install + +# Copy environment template +cp .env.example .env.local + +# Start development mode +npm run dev +``` + +### Running Your First Agent + +```bash +# Run the example agent +npx ts-node agents/example.ts + +# Or run Theron (Agent-000) +npx ts-node agents/theron.ts + +# Validate agent configuration +npm run validate-agent theron +``` + +## Usage Examples + +### CLI Usage + +```bash +# Generate a new agent template +npm run generate-agent MyCustomAgent + +# Export agent memory for analysis +npm run export-agent-memory theron --format json + +# Simulate agent cluster +npm run simulate-cluster --agents 3 --duration 60s + +# Stress test signal processing +npm run stress-test --signals 1000 +``` + +### Integration Example + +```typescript +import { Agent, SignalEmitter } from './types/agent'; +import { createAgent } from './utils/lifecycle'; + +// Create a custom agent +const myAgent = createAgent({ + name: 'LaunchTracker', + description: 'Tracks new token launches', + handlers: { + onWalletFunding: (event) => { + // Custom logic here + if (event.source === 'CEX') { + return { confidence: 0.8, emit: true }; + } + } + } +}); + +// Start monitoring +myAgent.start(); +``` + +### Webhook Integration + +```typescript +// Pipe signals to external services +import { SignalProcessor } from './utils/signal'; + +const processor = new SignalProcessor({ + webhook: 'https://your-service.com/webhook', + filters: ['launch_detected', 'anomaly_flagged'], + threshold: 0.7 +}); + +processor.start(); +``` + +## Developer Guide + +### Project Structure + +``` +Eremos/ +β”œβ”€β”€ agents/ # Agent implementations +β”‚ β”œβ”€β”€ example.ts # Template agent +β”‚ β”œβ”€β”€ theron.ts # Agent-000 (pattern detection) +β”‚ β”œβ”€β”€ observer.ts # Wallet activity monitor +β”‚ └── harvester.ts # Data collection agent +β”œβ”€β”€ types/ # TypeScript definitions +β”‚ β”œβ”€β”€ agent.ts # Core agent interfaces +β”‚ β”œβ”€β”€ signal.ts # Signal type definitions +β”‚ └── config.ts # Configuration schemas +β”œβ”€β”€ utils/ # Shared utilities +β”‚ β”œβ”€β”€ signal.ts # Signal processing +β”‚ β”œβ”€β”€ metrics.ts # Performance monitoring +β”‚ β”œβ”€β”€ logger.ts # Structured logging +β”‚ └── eventParser.ts # Blockchain event parsing +β”œβ”€β”€ scripts/ # Development tools +└── tests/ # Test suites +``` + +### Creating a New Agent + +1. **Generate template:** + ```bash + npm run generate-agent YourAgentName + ``` + +2. **Implement core methods:** + ```typescript + export class YourAgent implements Agent { + async initialize(): Promise { + // Setup logic + } + + async processEvent(event: BlockchainEvent): Promise { + // Event processing logic + return this.shouldEmitSignal(event) ? this.createSignal(event) : null; + } + } + ``` + +3. **Add configuration:** + ```typescript + // In types/config.ts + export interface YourAgentConfig { + watchAddresses: string[]; + confidenceThreshold: number; + enableWebhooks: boolean; + } + ``` + +4. **Test your agent:** + ```bash + npm test -- --testNamePattern=YourAgent + ``` + +### Dependencies & Tooling + +- **Runtime:** Node.js with TypeScript +- **Blockchain:** Solana Web3.js +- **Testing:** Jest with TypeScript support +- **Linting:** ESLint + Prettier +- **Type Checking:** TypeScript strict mode + +### Development Commands + +```bash +npm run dev # Start development mode +npm run build # Build for production +npm run test # Run test suite +npm run lint # Check code style +npm run lint:fix # Fix linting issues +npm run type-check # TypeScript validation +``` + +## Architecture

Agent Theron
@@ -34,6 +219,27 @@ Modular and extendable by design.* - **Ghost Watcher** - Monitors long-dormant wallets that suddenly become active again. Useful for tracing old dev wallets or rug setups. - *+ More to come.* +**Core Principles:** +- **Modularity:** Each agent operates independently +- **Extensibility:** Easy to add new detection logic +- **Performance:** Minimal resource footprint +- **Reliability:** Fault-tolerant signal processing +- **Transparency:** Open-source with clear documentation + +### Agent Lifecycle + +1. **Initialization** β†’ Load configuration and connect to data sources +2. **Monitoring** β†’ Continuously process blockchain events +3. **Analysis** β†’ Apply detection algorithms and heuristics +4. **Signal Emission** β†’ Output structured signals when patterns match +5. **Cleanup** β†’ Graceful shutdown and resource cleanup + +## Signal System + +### Example Signal Output + +```typescript +// Real-time detection log --- @@ -48,6 +254,7 @@ An example signal emitted by an agent detecting a live token deployment: [agent-observer] β†’ 5 bundle-linked wallets interacted within 8s of deploy [agent-observer] β†’ launch confidence spike (0.91) - emitting signal (elapsed: 13s) +// Structured signal object { agent: "Observer", type: "launch_detected", @@ -111,10 +318,29 @@ npm run dev ## Contributing -We’re open to contributors. +We’re open to contributors. Please see our [Contributing Guide](CONTRIBUTING.md) for details. . 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) + +### Quick Contributing Steps + +1. Fork the repository +2. Create a feature branch: `git checkout -b feature/your-feature` +3. Make your changes and add tests +4. Run linting: `npm run lint:fix` +5. Run tests: `npm test` +6. Commit with clear messages +7. Push and open a Pull Request + +### Code Style + +- Use TypeScript with strict type checking +- Follow Prettier formatting (configured in `.prettierrc`) +- Write meaningful commit messages +- Include tests for new features +- Update documentation as needed + --- ## License diff --git a/package.json b/package.json index 75703f0..3ef6a79 100644 --- a/package.json +++ b/package.json @@ -4,15 +4,42 @@ "description": "Modular agent framework for on-chain activity monitoring.", "main": "index.js", "scripts": { - "dev": "echo 'Running dev mode...'" + "dev": "echo 'Running dev mode...'", + "build": "tsc", + "test": "jest", + "test:watch": "jest --watch", + "test:coverage": "jest --coverage", + "lint": "eslint . --ext .ts,.js --ignore-path .gitignore", + "lint:fix": "eslint . --ext .ts,.js --ignore-path .gitignore --fix", + "prettier": "prettier --write \"**/*.{ts,js,json,md,yml,yaml}\"", + "prettier:check": "prettier --check \"**/*.{ts,js,json,md,yml,yaml}\"", + "type-check": "tsc --noEmit", + "validate-agent": "npx ts-node scripts/validate-agent.ts", + "generate-agent": "npx ts-node scripts/generate-agent.ts", + "export-agent-memory": "npx ts-node scripts/export-agent-memory.ts", + "simulate-cluster": "npx ts-node scripts/simulate-cluster.ts", + "stress-test": "npx ts-node scripts/stress-test.ts", + "precommit": "npm run lint:fix && npm run prettier && npm run type-check && npm test" }, "keywords": [ "agent", "onchain", "modular", "blockchain", - "framework" + "framework", + "solana", + "autonomous", + "swarm", + "signals" ], "license": "MIT", - "author": "EremosCore" + "author": "EremosCore", + "repository": { + "type": "git", + "url": "git+https://github.com/AJibolaOnaneye/Eremos.git" + }, + "bugs": { + "url": "https://github.com/AJibolaOnaneye/Eremos/issues" + }, + "homepage": "https://github.com/AJibolaOnaneye/Eremos#readme" }