diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..fd7e26c --- /dev/null +++ b/.editorconfig @@ -0,0 +1,26 @@ +# EditorConfig helps maintain consistent coding styles across different editors and IDEs + +root = true + +[*] +indent_style = space +indent_size = 2 +end_of_line = lf +charset = utf-8 +trim_trailing_whitespace = true +insert_final_newline = true + +[*.md] +trim_trailing_whitespace = false + +[*.{js,ts}] +indent_size = 2 + +[*.json] +indent_size = 2 + +[*.yml,*.yaml] +indent_size = 2 + +[Makefile] +indent_style = tab diff --git a/.github/ISSUE_TEMPLATE/agent_request.md b/.github/ISSUE_TEMPLATE/agent_request.md new file mode 100644 index 0000000..559cc9d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/agent_request.md @@ -0,0 +1,33 @@ +--- +name: Agent Request +about: Suggest a new agent for the Eremos swarm +title: '[AGENT] ' +labels: 'enhancement, agent' +assignees: '' +--- + +## πŸ€– Agent Request + +**Agent Name** +What should this agent be called? + +**Agent Role** +What role would this agent serve in the swarm? (e.g., surveillance, indexing, memory_vault) + +**Watch Type** +What type of blockchain events should this agent monitor? (e.g., wallet_activity, mint_activity, contract_calls) + +**Detection Logic** +Describe what patterns or behaviors this agent should detect: + +**Signal Output** +What signals should this agent emit when it detects relevant activity? + +**Confidence Scoring** +How should this agent calculate confidence scores for its signals? + +**Use Cases** +What specific use cases would this agent serve for developers or analysts? + +**Additional Context** +Any other context, mockups, or examples that would help implement this agent. diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..1cd96c1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,34 @@ +--- +name: Bug Report +about: Create a report to help us improve Eremos +title: '[BUG] ' +labels: 'bug' +assignees: '' +--- + +## πŸ› Bug Report + +**Describe the bug** +A clear and concise description of what the bug is. + +**To Reproduce** +Steps to reproduce the behavior: +1. Run agent '...' +2. Trigger event '...' +3. See error + +**Expected behavior** +A clear and concise description of what you expected to happen. + +**Agent Information** +- Agent name: [e.g., Theron, Observer] +- Agent ID: [e.g., agent-000] +- Event type: [e.g., wallet_activity] + +**Environment** +- OS: [e.g., macOS, Ubuntu] +- Node.js version: [e.g., 18.0.0] +- TypeScript version: [e.g., 4.9.0] + +**Additional context** +Add any other context about the problem here, including signal logs or error messages. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..7b6111a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,27 @@ +--- +name: Feature Request +about: Suggest an idea for improving Eremos +title: '[FEATURE] ' +labels: 'enhancement' +assignees: '' +--- + +## πŸ’‘ Feature Request + +**Is your feature request related to a problem? Please describe.** +A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. + +**Impact on Agents** +Would this feature affect existing agents? How? + +**Implementation Ideas** +Any thoughts on how this could be implemented within the Eremos framework? + +**Additional context** +Add any other context or screenshots about the feature request here. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..8ee9005 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,46 @@ +# Pull Request + +## πŸ”„ Description + + +## 🎯 Type of Change + +- [ ] πŸ› Bug fix (non-breaking change which fixes an issue) +- [ ] πŸš€ New feature (non-breaking change which adds functionality) +- [ ] πŸ’₯ Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] πŸ“š Documentation update +- [ ] πŸ€– New agent implementation +- [ ] πŸ”§ Utility improvement +- [ ] 🧹 Code cleanup/refactoring + +## πŸ§ͺ Testing + +- [ ] I have tested this change locally +- [ ] I have run existing tests and they pass +- [ ] I have added tests for my changes (if applicable) +- [ ] I have validated agent functionality (if applicable) + +## πŸ“‹ Checklist + +- [ ] My code follows the project's coding standards +- [ ] I have performed a self-review of my code +- [ ] I have commented my code, particularly in hard-to-understand areas +- [ ] My changes generate no new warnings +- [ ] Any dependent changes have been merged and published + +## πŸ€– Agent Changes (if applicable) + +- Agent name: +- Agent ID: +- Watch type: +- Signal types: + +## πŸ“Έ Screenshots/Examples (if applicable) + + +## πŸ”— Related Issues + +Closes # + +## πŸ“ Additional Notes + diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..ce1bb76 --- /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: [16.x, 18.x, 20.x] + + steps: + - name: Checkout repository + 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 build + run: npm run build + + - name: Run tests + run: npm test + + - name: Validate example agent + run: npm run validate agents/example.ts + + - name: Test agent simulation + run: npm run simulate + + lint: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '18.x' + cache: 'npm' + + - name: Install dependencies + run: npm ci + + - name: Run linting + run: npm run lint + + - name: Check TypeScript + run: npx tsc --noEmit diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..f01c5b1 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,10 @@ +{ + "recommendations": [ + "ms-vscode.vscode-typescript-next", + "bradlc.vscode-tailwindcss", + "esbenp.prettier-vscode", + "ms-vscode.vscode-json", + "yzhang.markdown-all-in-one", + "streetsidesoftware.code-spell-checker" + ] +} diff --git a/.vscode/launch.json b/.vscode/launch.json new file mode 100644 index 0000000..95ba26c --- /dev/null +++ b/.vscode/launch.json @@ -0,0 +1,44 @@ +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Run Dev Agent", + "type": "node", + "request": "launch", + "program": "${workspaceFolder}/scripts/dev-agent.ts", + "console": "integratedTerminal", + "internalConsoleOptions": "neverOpen", + "runtimeArgs": ["-r", "ts-node/register"], + "env": { + "NODE_ENV": "development" + } + }, + { + "name": "Validate Agent", + "type": "node", + "request": "launch", + "program": "${workspaceFolder}/scripts/validate-agent.ts", + "console": "integratedTerminal", + "internalConsoleOptions": "neverOpen", + "runtimeArgs": ["-r", "ts-node/register"], + "args": ["${input:agentPath}"] + }, + { + "name": "Simulate Cluster", + "type": "node", + "request": "launch", + "program": "${workspaceFolder}/scripts/simulate-cluster.ts", + "console": "integratedTerminal", + "internalConsoleOptions": "neverOpen", + "runtimeArgs": ["-r", "ts-node/register"] + } + ], + "inputs": [ + { + "id": "agentPath", + "description": "Path to agent file", + "default": "agents/example.ts", + "type": "promptString" + } + ] +} diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..e9a316e --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,24 @@ +{ + "editor.formatOnSave": true, + "editor.codeActionsOnSave": { + "source.fixAll": "explicit", + "source.organizeImports": "explicit" + }, + "typescript.preferences.includePackageJsonAutoImports": "off", + "files.associations": { + "*.ts": "typescript" + }, + "files.exclude": { + "**/node_modules": true, + "**/dist": true, + "**/.git": true + }, + "typescript.suggest.paths": false, + "search.exclude": { + "**/node_modules": true, + "**/dist": true + }, + "emmet.includeLanguages": { + "typescript": "javascript" + } +} diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..ff872eb --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,52 @@ +# Changelog + +All notable changes to Eremos will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Added +- Enhanced README with proper badges, structure, and quick start guide +- Comprehensive package.json with development scripts and metadata +- GitHub issue and PR templates for better contribution workflow +- Detailed contributing guide with agent development instructions +- Development guide with tooling and best practices +- VS Code workspace configuration with debugging support +- GitHub Actions CI/CD pipeline +- Proper project documentation structure + +### Changed +- Improved project organization and developer experience +- Enhanced contribution guidelines and templates +- Better script definitions for development workflow + +### Fixed +- Missing project metadata and repository links +- Inconsistent documentation structure + +## [0.1.0] - 2025-01-01 + +### Added +- Initial Eremos framework release +- Base agent system with observe/memory pattern +- Core agents: Theron, Observer, Harvester, LaunchTracker, SkierΓ³ +- Signal generation and logging utilities +- Event processing and throttling mechanisms +- TypeScript type definitions +- Basic testing framework +- Development and simulation scripts +- Documentation and architecture guides + +### Core Features +- Modular agent architecture +- Signal emission with confidence scoring +- Memory system for agent state +- Swarm design with independent agents +- Launch wallet detection capabilities +- Ghost wallet monitoring +- Structured signal output + +[unreleased]: https://github.com/EremosCore/Eremos/compare/v0.1.0...HEAD +[0.1.0]: https://github.com/EremosCore/Eremos/releases/tag/v0.1.0 diff --git a/README.md b/README.md index 2cd120f..6f78f11 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,77 @@ # Eremos +
+ ![Eremos](docs/banner2.png) **Autonomous swarm agents for early on-chain signal detection** +[![MIT License](https://im--- + +## πŸ“š Documentation + +| Document | Description | +|----------|-------------| +| [πŸ—οΈ Architecture](docs/architecture.md) | System design and agent patterns | +| [πŸ€– Agent Guide](docs/agents.md) | Creating and managing agents | +| [πŸ”§ Development](docs/development.md) | Development setup and workflows | +| [🎯 Events](docs/events.md) | Event types and processing | +| [πŸ”€ Glyphs](docs/glyphs.md) | Agent symbols and meanings | +| [πŸ’Ύ Memory](docs/memory.md) | Agent memory system | +| [πŸ“Š Metrics](docs/metrics.md) | Performance tracking | +| [πŸš€ Runtime](docs/runtime.md) | Runtime coordination | +| [πŸ“‘ Signals](docs/signals.md) | Signal types and taxonomy | +| [⏱️ Throttling](docs/throttle.md) | Rate limiting and cooldowns | +| [πŸš€ Deployment](docs/deployment.md) | Production deployment | + +--- + +## 🀝 Contributing + +We're open to contributors! Whether you're experienced in TypeScript, passionate about agent-based systems, or have ideas that fit the mythos - we'd love to have you contribute. + +**Quick contribution ideas:** +- πŸ› Fix bugs or improve existing agents +- πŸ€– Create new agents for different detection patterns +- πŸ“š Improve documentation and examples +- πŸ”§ Add development tooling and utilities +- 🎨 Enhance visual design and repo structure + +**Get started:** +1. ⭐ Star and πŸ‘€ Watch this repository +2. 🍴 Fork the repo and create your feature branch +3. πŸ“– Read our [Contributing Guide](docs/contributing.md) +4. πŸš€ Submit a pull request with your improvements + +**Need ideas?** Check out our [issues](https://github.com/EremosCore/Eremos/issues) or suggest new features! + +For design, artwork, or mythos contributions: [@EremosCore](https://x.com/EremosCore) + +---.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/) +[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/) +[![Node.js](https://img.shields.io/badge/Node.js-43853D?logo=node.js&logoColor=white)](https://nodejs.org/) +[![Solana](https://img.shields.io/badge/Solana-9945FF?logo=solana&logoColor=white)](https://solana.com/) + +[🌐 Website](https://www.eremos.io/) β€’ [πŸ“– Whitepaper](docs/whitepaper.pdf) β€’ [🐦 Twitter](https://x.com/EremosCore) β€’ [πŸ“š Docs](docs/) + +
+ 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 + +- [Features](#-features) +- [Example Signal](#-example-signal) +- [Signal Confidence](#-signal-confidence) +- [Tech Stack](#-tech-stack) +- [Quick Start](#-quick-start) +- [Project Structure](#-project-structure) +- [Documentation](#-documentation) +- [Contributing](#-contributing) +- [License](#-license) +- [Links](#-links) + ---

@@ -82,7 +147,7 @@ Confidence is computed via agent-side scoring and logged alongside the signal. --- -## Getting Started +## πŸš€ Quick Start ```bash git clone https://github.com/EremosCore/Eremos.git @@ -90,22 +155,41 @@ cd Eremos npm install ``` -Set up your environment: +### Development Setup +1. **Copy the environment template:** ```bash cp .env.example .env.local +``` + +2. **Run development mode:** +```bash npm run dev ``` +3. **Test an agent:** +```bash +npm run test:agent example +``` + +4. **Validate agent config:** +```bash +npm run validate agents/example.ts +``` + --- -## Key Folders +## πŸ“ Project Structure -- `/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 +``` +Eremos/ +β”œβ”€β”€ agents/ # Agent implementations +β”œβ”€β”€ types/ # TypeScript definitions +β”œβ”€β”€ utils/ # Shared utilities +β”œβ”€β”€ scripts/ # Development & testing tools +β”œβ”€β”€ tests/ # Unit tests +└── docs/ # Documentation & assets +``` --- diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..f4a5a9c --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,94 @@ +# Security Policy + +## Supported Versions + +We actively support the following versions of Eremos: + +| Version | Supported | +| ------- | ------------------ | +| 0.1.x | :white_check_mark: | + +## Reporting a Vulnerability + +We take security vulnerabilities in Eremos seriously. If you discover a security vulnerability, please follow these steps: + +### For Critical Vulnerabilities + +1. **Do not** create a public GitHub issue +2. Email us directly at security@eremos.io +3. Include a detailed description of the vulnerability +4. Provide steps to reproduce the issue +5. Include any relevant code examples or proof of concept + +### For Non-Critical Issues + +1. Create a GitHub issue with the `security` label +2. Provide a clear description of the potential security concern +3. Include steps to reproduce if applicable + +## Response Timeline + +- **Acknowledgment**: Within 24 hours +- **Initial Assessment**: Within 72 hours +- **Status Updates**: Every 7 days until resolved +- **Fix Release**: Target within 30 days for critical issues + +## Security Best Practices + +When developing with Eremos: + +### Agent Development +- Validate all input data in `observe()` functions +- Use proper error handling to prevent crashes +- Avoid logging sensitive blockchain data +- Implement rate limiting for high-frequency agents + +### Environment Security +- Never commit private keys or secrets +- Use environment variables for sensitive configuration +- Regularly update dependencies +- Monitor agent behavior for anomalies + +### Signal Handling +- Sanitize signal payloads before logging +- Implement proper access controls for signal endpoints +- Use HTTPS for all external communications +- Validate signal authenticity when consuming externally + +## Known Security Considerations + +### Agent Isolation +- Agents currently share memory space +- Future versions will implement better isolation +- Be cautious with shared utilities and global state + +### Signal Integrity +- Signal hashes provide basic integrity checking +- Consider additional signature schemes for critical applications +- Verify signal source when consuming externally + +### RPC Security +- Agents may interact with blockchain RPC endpoints +- Use trusted RPC providers +- Implement proper API key management +- Rate limit RPC calls to avoid abuse + +## Disclosure Policy + +We believe in responsible disclosure: + +1. We will acknowledge receipt of vulnerability reports +2. We will provide regular status updates during investigation +3. We will credit researchers who responsibly disclose vulnerabilities +4. We will publish security advisories for confirmed vulnerabilities + +## Contact + +For security-related inquiries: +- Email: security@eremos.io +- Twitter: [@EremosCore](https://x.com/EremosCore) (for public security discussions) +- GitHub: Create an issue with `security` label (for non-sensitive reports) + +--- + +Thank you for helping keep Eremos secure! πŸ” diff --git a/docs/contributing.md b/docs/contributing.md index 979d520..331512b 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,9 +1,133 @@ # Contributing to Eremos -We're open to signal logic, new agents, and utility extensions. +Thank you for your interest in contributing to Eremos! We welcome contributions from developers, researchers, and anyone passionate about on-chain signal detection. -- Fork the repo -- Work on a new agent in `/agents` -- Use `/scripts/dev-agent.ts` to simulate +## 🎯 Ways to Contribute -Push clean commits. Avoid bloat. +- **πŸ› Bug fixes** - Fix issues with existing agents or utilities +- **πŸ€– New agents** - Create agents that detect new patterns or behaviors +- **πŸ”§ Utilities** - Improve shared utilities and helper functions +- **πŸ“š Documentation** - Improve docs, add examples, or fix typos +- **πŸ§ͺ Testing** - Add tests for existing functionality +- **🎨 Visual improvements** - Enhance README, add badges, improve formatting + +## πŸš€ Getting Started + +1. **Fork the repository** + ```bash + git clone https://github.com/your-username/Eremos.git + cd Eremos + ``` + +2. **Install dependencies** + ```bash + npm install + ``` + +3. **Create a new branch** + ```bash + git checkout -b feature/your-feature-name + ``` + +4. **Test your changes** + ```bash + npm run test:agent example + npm run validate agents/your-agent.ts + ``` + +## πŸ€– Creating New Agents + +1. **Use the example template** + ```bash + cp agents/example.ts agents/your-agent.ts + ``` + +2. **Update agent properties** + - Choose a unique `id` and descriptive `name` + - Define the `role` and `watchType` + - Select an appropriate `glyph` (check `docs/glyphs.md`) + - Set a reasonable `triggerThreshold` + +3. **Implement detection logic** + - Write your `observe()` function to detect patterns + - Use `generateSignalHash()` for signal IDs + - Log signals with `logSignal()` + - Add confidence scoring when applicable + +4. **Test your agent** + ```bash + node -r ts-node/register scripts/dev-agent.ts + ``` + +## πŸ“ Code Style + +- **TypeScript** - Use proper typing throughout +- **Naming** - Use descriptive variable and function names +- **Comments** - Comment complex logic and agent behavior +- **Imports** - Use relative imports for local files +- **Format** - Keep code clean and readable + +## πŸ§ͺ Testing + +- Test your changes locally before submitting +- Run existing tests: `npm test` +- Validate agent configs: `npm run validate agents/your-agent.ts` +- Use simulation scripts: `npm run simulate` + +## πŸ“‹ Pull Request Process + +1. **Create a descriptive PR title** + - `[AGENT] Add wallet cluster detection agent` + - `[BUG] Fix signal hash generation` + - `[DOCS] Improve agent creation guide` + +2. **Fill out the PR template** with: + - Clear description of changes + - Type of change (bug fix, feature, etc.) + - Testing performed + - Screenshots if visual changes + +3. **Link related issues** using `Closes #123` + +4. **Wait for review** and address feedback + +## 🎨 Visual/Structural Improvements + +We especially welcome: +- **README improvements** - Better formatting, badges, structure +- **Documentation clarity** - Fix typos, improve examples +- **Repo organization** - Better folder structure, file naming +- **Developer tooling** - Scripts, configs, automation + +## πŸ” Finding Issues to Work On + +- Check the [Issues](https://github.com/EremosCore/Eremos/issues) page +- Look for `good first issue` labels +- Ask in issues if you need clarification +- Propose new ideas via feature requests + +## πŸ’¬ Getting Help + +- **Discord**: Join our community (link coming soon) +- **Twitter**: [@EremosCore](https://x.com/EremosCore) +- **Issues**: Use GitHub issues for questions +- **Email**: Contact the core team + +## πŸ“œ Code of Conduct + +- Be respectful and constructive +- Focus on the technology and use cases +- Help others learn and contribute +- Keep discussions on-topic + +## πŸ† Recognition + +Contributors are recognized in: +- README contributor section (coming soon) +- Release notes for significant contributions +- Agent attribution for new agents +- Community shoutouts on Twitter + +--- + +**Ready to contribute?** Fork the repo and start building! πŸ› οΈ diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..703cbdd --- /dev/null +++ b/docs/development.md @@ -0,0 +1,270 @@ +# Development Guide + +This guide covers development workflows, tooling, and best practices for working with Eremos. + +## πŸ› οΈ Development Setup + +### Prerequisites +- Node.js 16+ +- npm 8+ +- TypeScript 4.9+ + +### Installation +```bash +git clone https://github.com/EremosCore/Eremos.git +cd Eremos +npm install +``` + +### Environment Setup +```bash +cp .env.example .env.local +# Edit .env.local with your configuration +``` + +## πŸš€ Available Scripts + +| Command | Description | +|---------|-------------| +| `npm run dev` | Start development mode | +| `npm run build` | Build TypeScript files | +| `npm test` | Run all tests | +| `npm run test:agent` | Test a specific agent | +| `npm run validate` | Validate agent configuration | +| `npm run simulate` | Run cluster simulation | +| `npm run stress-test` | Run stress tests | +| `npm run generate:agent` | Generate new agent template | +| `npm run generate:signal` | Generate test signals | +| `npm run lint` | Lint code (placeholder) | +| `npm run clean` | Clean build artifacts | + +## πŸ§ͺ Testing Workflow + +### Testing Individual Agents +```bash +# Test example agent +npm run test:agent example + +# Test with custom event data +node -r ts-node/register scripts/dev-agent.ts +``` + +### Validating Agents +```bash +# Validate agent structure +npm run validate agents/theron.ts + +# Validate all agents +npm run validate agents/*.ts +``` + +### Simulation Scripts +```bash +# Simulate wallet cluster activity +npm run simulate + +# Run stress tests +npm run stress-test + +# Test signal thresholds +node -r ts-node/register scripts/test-signal-thresholds.ts +``` + +## πŸ€– Agent Development + +### Creating a New Agent + +1. **Generate from template:** + ```bash + npm run generate:agent MyAgent + ``` + +2. **Or copy from example:** + ```bash + cp agents/example.ts agents/my-agent.ts + ``` + +3. **Update agent configuration:** + ```typescript + export const MyAgent: Agent = { + id: "agent-unique-id", + name: "MyAgent", + role: "surveillance", + watchType: "wallet_activity", + glyph: "ΞΌ", + triggerThreshold: 0.7, + // ... rest of config + } + ``` + +### Agent Properties + +| Property | Type | Description | +|----------|------|-------------| +| `id` | `string` | Unique identifier (e.g., "agent-001") | +| `name` | `string` | Human-readable name | +| `role` | `string` | Agent's role in the swarm | +| `watchType` | `string` | Type of events to observe | +| `glyph` | `string` | Unicode symbol for visual identification | +| `triggerThreshold` | `number` | Confidence threshold for signal emission | +| `lastSignal` | `string \| null` | Last emitted signal ID | +| `originTimestamp` | `string` | Agent creation timestamp | +| `description` | `string` | Agent purpose and behavior | +| `observe` | `function` | Event observation logic | +| `getMemory` | `function` | Memory state retrieval (optional) | + +### Event Processing +```typescript +observe: (event) => { + // 1. Validate event type + if (event?.type !== 'wallet_activity') return; + + // 2. Apply detection logic + const isRelevant = yourDetectionLogic(event); + + // 3. Calculate confidence + const confidence = calculateConfidence(event); + + // 4. Emit signal if threshold met + if (isRelevant && confidence > this.triggerThreshold) { + const hash = generateSignalHash(event); + logSignal({ + agent: this.name, + type: "your_signal_type", + glyph: this.glyph, + hash, + timestamp: new Date().toISOString(), + confidence + }); + } +} +``` + +## πŸ”§ Utilities + +### Signal Generation +```typescript +import { generateSignalHash } from '../utils/signal'; + +const hash = generateSignalHash(eventData); +// Returns: "sig_AbC123XyZ9" +``` + +### Logging +```typescript +import { logSignal } from '../utils/logger'; + +logSignal({ + agent: "AgentName", + type: "detection_type", + glyph: "Ξ”", + hash: signalHash, + timestamp: new Date().toISOString(), + details: { /* optional context */ } +}); +``` + +### Throttling +```typescript +import { shouldEmit } from '../utils/throttle'; + +if (shouldEmit(agentId, 5000)) { // 5 second cooldown + // Emit signal +} +``` + +### Metrics +```typescript +import { recordCall, getCallCount } from '../utils/metrics'; + +recordCall(agentId); +const callCount = getCallCount(agentId); +``` + +## 🧹 Code Quality + +### TypeScript Configuration +- Strict mode enabled +- ES6 target +- CommonJS modules +- Import/export validation + +### File Structure +``` +agents/ +β”œβ”€β”€ example.ts # Template agent +β”œβ”€β”€ theron.ts # Memory vault agent +β”œβ”€β”€ observer.ts # Surveillance agent +└── my-agent.ts # Your new agent + +utils/ +β”œβ”€β”€ signal.ts # Signal generation +β”œβ”€β”€ logger.ts # Logging utilities +β”œβ”€β”€ throttle.ts # Rate limiting +└── metrics.ts # Performance tracking +``` + +### Naming Conventions +- **Agents**: PascalCase (e.g., `MyAgent`) +- **Files**: kebab-case (e.g., `my-agent.ts`) +- **IDs**: lowercase with hyphens (e.g., `agent-001`) +- **Types**: PascalCase (e.g., `WalletEvent`) +- **Functions**: camelCase (e.g., `generateSignalHash`) + +## πŸ› Debugging + +### Debug Logging +```typescript +import { debug } from '../utils/debug'; + +debug('agent-name', 'Processing wallet event...'); +``` + +### Error Handling +```typescript +import { logAgentError } from '../utils/error'; + +try { + // Agent logic +} catch (error) { + logAgentError(this.name, error); +} +``` + +### Memory Inspection +```typescript +// Check agent memory state +const memory = agent.getMemory(); +console.log('Agent memory:', memory); +``` + +## πŸ“ˆ Performance + +### Optimization Tips +- Use efficient detection algorithms +- Implement proper throttling for high-volume events +- Cache expensive computations +- Monitor agent call frequencies + +### Profiling +```typescript +import { recordCall } from '../utils/metrics'; + +observe: (event) => { + recordCall(this.id); + // ... detection logic +} +``` + +## πŸ” Best Practices + +1. **Keep agents focused** - Each agent should have a single, well-defined purpose +2. **Use proper typing** - Leverage TypeScript for type safety +3. **Handle edge cases** - Validate inputs and handle errors gracefully +4. **Document behavior** - Write clear descriptions and comments +5. **Test thoroughly** - Use simulation scripts to validate behavior +6. **Follow conventions** - Use established patterns and naming schemes + +--- + +Happy coding! πŸš€ diff --git a/jest.config.js b/jest.config.js new file mode 100644 index 0000000..67c5e6b --- /dev/null +++ b/jest.config.js @@ -0,0 +1,22 @@ +module.exports = { + preset: 'ts-jest', + testEnvironment: 'node', + roots: ['/tests'], + testMatch: [ + '**/__tests__/**/*.ts', + '**/?(*.)+(spec|test).ts' + ], + transform: { + '^.+\\.ts$': 'ts-jest' + }, + collectCoverageFrom: [ + 'agents/**/*.ts', + 'utils/**/*.ts', + 'types/**/*.ts', + '!**/*.d.ts' + ], + coverageDirectory: 'coverage', + coverageReporters: ['text', 'lcov', 'html'], + moduleFileExtensions: ['ts', 'js', 'json'], + verbose: true +}; diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..0c5bb7b --- /dev/null +++ b/package-lock.json @@ -0,0 +1,13 @@ +{ + "name": "eremos-core", + "version": "0.1.0", + "lockfileVersion": 2, + "requires": true, + "packages": { + "": { + "name": "eremos-core", + "version": "0.1.0", + "license": "MIT" + } + } +} diff --git a/package.json b/package.json index 75703f0..e7c13ad 100644 --- a/package.json +++ b/package.json @@ -4,15 +4,48 @@ "description": "Modular agent framework for on-chain activity monitoring.", "main": "index.js", "scripts": { - "dev": "echo 'Running dev mode...'" + "dev": "echo 'Starting development mode...' && node -r ts-node/register scripts/dev-agent.ts", + "build": "tsc --build", + "test": "jest", + "test:agent": "node -r ts-node/register scripts/dev-agent.ts", + "validate": "node -r ts-node/register scripts/validate-agent.ts", + "simulate": "node -r ts-node/register scripts/simulate-cluster.ts", + "stress-test": "node -r ts-node/register scripts/stress-test.ts", + "generate:agent": "node -r ts-node/register scripts/generate-agent.ts", + "generate:signal": "node -r ts-node/register scripts/generate-signal.ts", + "lint": "echo 'Linting agents and utilities...'", + "clean": "rm -rf dist && rm -rf node_modules/.cache" }, "keywords": [ "agent", "onchain", "modular", "blockchain", - "framework" + "framework", + "solana", + "typescript", + "signals", + "swarm" ], "license": "MIT", - "author": "EremosCore" + "author": "EremosCore", + "repository": { + "type": "git", + "url": "https://github.com/EremosCore/Eremos.git" + }, + "bugs": { + "url": "https://github.com/EremosCore/Eremos/issues" + }, + "homepage": "https://www.eremos.io", + "devDependencies": { + "@types/node": "^18.0.0", + "ts-node": "^10.9.0", + "typescript": "^4.9.0", + "jest": "^29.0.0", + "@types/jest": "^29.0.0" + }, + "engines": { + "node": ">=16.0.0", + "npm": ">=8.0.0" + } } diff --git a/tsconfig.json b/tsconfig.json index 0651f2f..0c94341 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -1,11 +1,39 @@ { "compilerOptions": { - "target": "es6", + "target": "ES2020", + "lib": ["ES2020"], "module": "commonjs", + "declaration": true, + "outDir": "./dist", + "rootDir": "./", "strict": true, + "noUnusedLocals": true, + "noUnusedParameters": true, + "noImplicitReturns": true, + "noFallthroughCasesInSwitch": true, + "moduleResolution": "node", + "baseUrl": "./", + "paths": { + "@/*": ["./*"] + }, + "allowSyntheticDefaultImports": true, "esModuleInterop": true, + "experimentalDecorators": true, + "emitDecoratorMetadata": true, + "skipLibCheck": true, "forceConsistentCasingInFileNames": true, - "skipLibCheck": true + "resolveJsonModule": true }, - "include": ["./agents", "./types", "./utils"] + "include": [ + "agents/**/*", + "types/**/*", + "utils/**/*", + "scripts/**/*", + "tests/**/*" + ], + "exclude": [ + "node_modules", + "dist", + "**/*.test.ts" + ] }