diff --git a/.cursorrules b/.cursorrules new file mode 100644 index 0000000..fc2d3d0 --- /dev/null +++ b/.cursorrules @@ -0,0 +1,156 @@ +# Yellowstone Vixen Project Rules + +## Commit Message Conventions +```rules +# Commit Message Format +type(scope): description + +# Types +- feat: New features or enhancements +- fix: Bug fixes +- chore: Maintenance tasks, dependencies, cleanup +- docs: Documentation updates +- test: Test-related changes +- refactor: Code refactoring +- perf: Performance improvements + +# Scopes +- parser: Transaction parser related changes +- proto: Protocol buffer definitions +- config: Configuration related changes +- metrics: Monitoring and metrics +- ci: CI/CD related changes +``` + +## Code Style Rules +```rules +# Rust Formatting +- Use rustfmt with project's .rustfmt.toml configuration +- Maximum line length: 100 characters +- Use 4 spaces for indentation +- Sort imports alphabetically + +# Naming Conventions +- Use snake_case for functions and variables +- Use PascalCase for types and traits +- Use SCREAMING_SNAKE_CASE for constants +- Prefix trait implementations with trait name + +# File Organization +- Keep modules in separate files +- Group related functionality in modules +- Place tests in a tests module +``` + +## Project Structure Requirements +```rules +# Directory Organization +/crates/ + - Separate crates for distinct functionality + - Each crate must have its own Cargo.toml +/examples/ + - Demonstrate specific use cases + - Include documentation +/docs/ + - Keep documentation up to date + - Use markdown format + - Include diagrams where helpful + +# Dependencies +- Pin dependency versions in Cargo.toml +- Document major dependency updates +- Keep dependencies up to date +``` + +## Testing Requirements +```rules +# Test Coverage +- Unit tests for all public functions +- Integration tests for parser implementations +- Documentation tests for public APIs +- Performance benchmarks for critical paths + +# Test Organization +- Place unit tests in the same file as code +- Integration tests in tests/ directory +- Benchmark tests in benches/ directory +``` + +## Protocol Buffer Rules +```rules +# Proto Files +- Use proto3 syntax +- Follow Google's Protocol Buffer style guide +- Document all messages and fields +- Version all proto definitions + +# Parser Implementation +- Implement proper error handling +- Include validation for all fields +- Support backward compatibility +- Document breaking changes +``` + +## Performance Guidelines +```rules +# Optimization Rules +- Profile before optimizing +- Document performance improvements +- Include benchmarks for changes +- Consider memory usage + +# Resource Management +- Implement proper cleanup +- Use async/await where appropriate +- Handle connection pooling efficiently +``` + +## Security Requirements +```rules +# Security Practices +- Validate all inputs +- Handle errors gracefully +- No hardcoded credentials +- Use secure defaults + +# Code Review Requirements +- Security review for parser changes +- Performance review for critical paths +- Documentation review for public APIs +``` + +## Documentation Requirements +```rules +# Code Documentation +- Document all public APIs +- Include examples in documentation +- Keep README.md up to date +- Document breaking changes + +# Architecture Documentation +- Update architecture diagrams +- Document design decisions +- Include performance considerations +``` + +## CI/CD Requirements +```rules +# Build Process +- Must pass all tests +- Must pass clippy lints +- Must pass security checks +- Must update documentation + +# Release Process +- Update CHANGELOG.md +- Tag releases with semver +- Include migration guides +``` + +## Monitoring and Metrics +```rules +# Observability +- Include relevant metrics +- Add tracing for new features +- Document monitoring points +- Update dashboards \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..a1d1f31 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,279 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### 2024-01-15 +- Fixed: Improve onboarding of the project ([b056d2b]) + +### 2024-11-29 +- Fixed: Truncate the id for parsers to be below 32 characters to meet grpc validations ([4b61e84]) + +### 2024-11-21 +- Added: Use crates for proto and gRPC client [#145] ([538b3e3]) + +### 2024-11-20 +- Changed: Change vixen example config ([7d3fd2c]) +- Added: Make prometheus username and password optional ([8a54308]) + +### 2024-11-11 +- Added: Add setter for prefilter accounts field ([c81f7a1]) + +### 2024-10-30 +- Added: Example vixen toml ([02f250b]) + +### 2024-10-29 +- Fixed: gRPC reflection issues ([39bcfac]) +- Changed: Update readme and add orca, raydium proto parsers to example binary ([f5a0b9d]) +- Changed: Cleanup ([1af377d]) + +### 2024-10-28 +- Added: Add protobufs for orca and raydium ([86b64e5]) + +### 2024-10-26 +- Changed: Run clippy ([43313b0]) +- Merged: Pull request #34 for version conflict with zeroize ([51d164c]) + +### 2024-10-25 +- Fixed: Zeroize dependency conflicts ([84a13ee]) +- Changed: Cleanup ([0c3e083]) +- Added: Adding flag ([75a1b97]) +- Changed: Updating this error on crates ([85d921f]) + +### 2024-10-18 +- Changed: Cleanup ([7045d8b]) +- Changed: Update README ([6735934]) +- Changed: Cleanup ([df20d73]) +- Merged: Pull request #22 from rpcpool/naga-jup-program-parsers-rebase ([3efcbe9]) + +### 2024-10-17 +- Fixed: Bump upstream dep versions ([c20ef77]) +- Merged: Pull request #30 from Taylor123/fix-versioning ([31e4375]) + +### 2024-10-15 +- Merged: Pull request #29 from rpcpool/june/stream-reflection ([4e6fa91]) +- Changed: Change proto_helpers module to proto module in helpers ([4594a88]) + +### 2024-10-14 +- Changed: Change directory structure ([881f1dd]) +- Changed: Change dir structure and change acc, ix parsers naming conventions ([73964e1]) + +### 2024-10-12 +- Added: Add stream builder method to add gRPC descriptors ([8e1b41a]) + +### 2024-10-11 +- Changed: Format JSON ([c338008]) +- Changed: Cleanup ([19664c1]) +- Fixed: Typo fix ([bb0e2ed]) +- Changed: Refactor mock crate to run fixtures as well as parsing ([d9600e4]) + +### 2024-10-10 +- Changed: Cleanup ([1863f76]) + +### 2024-10-09 +- Merged: Pull request #25 from rpcpool/naga/protobufs-ixs ([661276b]) +- Merged: Pull request #28 from rpcpool/june/parser-refactor ([097f66b]) + +### 2024-10-03 +- Added: Complete Jupiter:Raydium account and instruction parsers ([228cc6a]) + +### 2024-09-27 +- Changed: Rebase off of june/parser-refactor ([156494b]) + +### 2024-09-26 +- Added: Init Raydium ([5964918]) +- Changed: Clean up error & pubkey types in the parser crate ([2423bcc]) +- Changed: Pass 1 at removing extraneous helpers from parser ([e81b37e]) + +### 2024-09-24 +- Changed: WIP: Jupiter programs ([84ce5c4]) + +### 2024-09-23 +- Added: Add all proto declarations for extensions instructions ([b493d6f]) +- Changed: Format code ([b86bba7]) +- Changed: Cleanup ([e381c8c]) +- Changed: Format and cleanup ([0a35edd]) +- Changed: Resolve clippy warnings ([c485077]) + +### 2024-09-20 +- Changed: WIP: Extensions instructions ([7c56a6c], [c1b4e5d]) + +### 2024-09-19 +- Fixed: Stream error with duplicate program IDs ([ba53df2]) +- Merged: Pull request #23 from rpcpool/june/docs ([4b2d423]) + +### 2024-09-18 +- Added: WIP: Add token extensions instruction parsing ([a646118]) +- Changed: WIP: Extensions ([3fb3c68]) +- Changed: Pull upstream ([d338bfe]) +- Merged: Pull request #24 from rpcpool/naga/protobufs-accs-ixs ([6b4668b]) +- Changed: Format code ([128d12f]) +- Merged: Pull request #26 from rpcpool/june/mock-refactor ([e801cc3]) + +### 2024-09-17 +- Added: Add instructions proto for token program ([1f94712]) +- Added: Unwrap fixture data in fixture macros ([1fad542]) + +### 2024-09-16 +- Changed: Cleanup and add readme to stream-parser example ([c81859a], [fce8459]) +- Changed: Refactor proto bytes to string for pubkey fields ([a312803]) + +### 2024-09-13 +- Changed: Format and cleanup ([baa45cb]) +- Added: Finish up proto account parsers for token program and token extensions ([2bb863f]) + +### 2024-09-11 +- Added: Add token program and token extensions protobuf ([b7df6a7]) + +### 2024-09-10 +- Changed: Add raydium program parsers ([c56b1cf]) +- Changed: Resolve lints, plus first pass at documentation ([27dff1b]) + +### 2024-09-09 +- Changed: Update mocking ([7681283]) +- Fixed: Format ([feb3181]) +- Added: Add filters to fixtures ([7ced3fb]) + +### 2024-09-06 +- Fixed: Remove Vixen toml ([3498f8b]) +- Merged: Pull request #20 from rpcpool/main-fix-readme ([524c21d]) +- Fixed: README ([f153739]) + +### 2024-09-05 +- Added: Add Orca account and instruction parsers ([0eb1c2b]) +- Changed: Rename examples ([4333241]) +- Merged: Pull request #19 from rpcpool/naga/tx-parsers-rebased ([3ba383e]) +- Merged: Pull request #18 from rpcpool/june/streams ([ded47de]) + +### 2024-09-04 +- Changed: Update READMEs and cleanup ([8a13be5], [b6f6fd2]) +- Changed: Format using nightly toolchain ([3e3a554]) +- Changed: Add metrics placeholder config for prometheus in Vixen.toml ([5bd4fd3]) +- Changed: Update READMEs ([30e65a3]) + +### 2024-09-03 +- Changed: Refactor Ix parsers logic to consume InstructionUpdate ([f7a55d2]) + +### 2024-08-30 +- Added: Add missing clippy config to remaining crates ([04b43d6]) +- Added: Add support for adapting prebuilt parsers to gRPC ([ad74dee]) + +### 2024-08-28 +- Added: Add InstructionPipeline for reparsing instructions ([2d36c79]) + +### 2024-08-24 +- Added: Add OpenTelemetry exporter to hold meter provider ([3182a24]) + +### 2024-08-23 +- Changed: WIP: Implement gRPC streams + refactor everything ([3a74a1d]) + +### 2024-08-22 +- Added: Add example crate for basic OpenTelemetry metrics ([f7bf29f]) + +### 2024-08-21 +- Changed: Retool metrics, reinstate OTel, bump dependencies ([99dda82]) + +### 2024-08-13 +- Changed: Merge pull request #17 from rpcpool/vixen-metrics-setup ([e77e897]) + +### 2024-08-10 +- Removed: Drop OpenTelemetry ([c2f51ce], [cfb1255]) + +### 2024-08-08 +- Added: Setup metrics for OpenTelemetry and Prometheus ([7963de3]) +- Changed: Cleanup ([5e74813]) + +### 2024-08-07 +- Changed: Setup Ixs Parsers (Token program and Token extensions program) #16 ([84c9cc5]) +- Changed: Merge pull request #13 from rpcpool/vixen-parsers ([5971be2]) +- Changed: Merge branch 'main' into vixen-parsers ([9af4912]) +- Changed: Refactor code for mock ([e422188]) + +### 2024-08-06 +- Fixed: Formatting ([4032158]) +- Changed: Update cargo.lock ([4c318b5]) + +### 2024-08-05 +- Changed: Update feature flags ([17001a8]) +- Changed: Cleanup ([c8589d4]) + +### 2024-08-01 +- Changed: Cleanup ([43f9fbf]) +- Fixed: README ([9c524b9]) + +### 2024-07-31 +- Changed: Update mock README ([68025da]) +- Fixed: Add env setup in mock README ([a068b7f]) +- Added: Add dotenv to fetch RPC_ENDPOINT and CLUSTER ([e4d5152]) + +### 2024-07-30 +- Changed: Cleanup ([11f6925], [575cfb0], [6725f5b], [f41588d]) +- Fixed: README ([5cb349e]) +- Fixed: Add imports and installation info on readme ([9746dcf]) +- Changed: Refactor token extension parsing ([01e26e6]) +- Fixed: Feature flags ([3fe77a3]) +- Changed: Resolve PR comments ([16243ef]) +- Added: Add readme for parser and mock ([6183f63]) +- Added: Setup mock testing suite ([30fb5da]) + +### 2024-07-26 +- Added: Setup unit tests for parsers ([305ceaf]) +- Added: Add extended account data ([4fa3843]) + +### 2024-07-24 +- Added: Create crate for housing parsers sponsored by vixen ([8b80adb]) +- Added: Implement token program parser using SPL token program ([cc17443]) +- Changed: Merge pull request #11 from WilfredAlmeida/patch-1 ([5379be7]) + +### 2024-07-22 +- Added: Scaffold streams crate and remove Solana SDK deps ([8ce8a62]) + +### 2024-07-16 +- Added: Add metrics and wrap entry in Runtime to configure ([c52b29c]) + +### 2024-07-07 +- Fixed: Fix path ([af0f404]) + +### 2024-06-21 +- Added: Update readme, add contributing and code of conduct ([961b584]) +- Changed: Merge pull request #7 from rpcpool/june/runtime ([1cce465]) +- Added: Add developers and section on dragonmouth to readme ([2481072]) +- Fixed: Name of project on the readme ([53386e0]) +- Fixed: Typos ([e565d67]) +- Changed: Merge pull request #9 from rpcpool/typos-20240621 ([e298286]) + +### 2024-06-20 +- Added: Add signal handlers & real runtime error reporting ([4e384d0]) +- Changed: Resolve TODOs, change lints, and fix linter errors ([627e900]) + +### 2024-06-19 +- Fixed: Runtime panic in topograph ([dca0f46]) + +### 2024-06-18 +- Changed: WIP: Cleaned up some handler creation boilerplate ([0c64c96]) + +### 2024-06-12 +- Added: Quick'n'dirty scaffold of handler manager creation ([2c1ae0d]) + +### 2024-06-04 +- Changed: Merge pull request #4 from rpcpool/june/runtime ([88c73ff]) + +### 2024-05-31 +- Changed: WIP: Refactor Parser trait to allow extern parsers ([54d2063]) + +### 2024-05-15 +- Added: WIP: Minimum viable example parsing SPL Token 2022 ([07be095]) + +### 2024-05-04 +- Changed: Continue scaffolding runtime framework for parsers ([13dd1ea]) + +### 2024-04-23 +- Added: WIP: Begin designing subscriber runtime framework ([3f2a269]) + +### 2024-04-16 +- Added: Initial readme ([a65f4dc]) + diff --git a/docs/onboarding/01-project-overview.md b/docs/onboarding/01-project-overview.md new file mode 100644 index 0000000..8262f96 --- /dev/null +++ b/docs/onboarding/01-project-overview.md @@ -0,0 +1,92 @@ +# Yellowstone Vixen - Project Overview + +## Introduction +Yellowstone Vixen is a high-performance Rust-based project that provides a gRPC service for parsing Solana transactions. It's designed to work seamlessly with the Yellowstone ecosystem, offering efficient and reliable transaction parsing capabilities. + +## Architecture Overview + +```mermaid +graph TB + Client[Client Applications] -->|gRPC Requests| Vixen[Yellowstone Vixen Service] + Vixen -->|Parse| Transactions[Solana Transactions] + Vixen -->|Metrics| Prometheus[Prometheus Monitoring] + Vixen -->|Tracing| OpenTelemetry[OpenTelemetry] + + subgraph "Vixen Service Components" + Parser[Transaction Parser] + ProtoGen[Protocol Buffer Definitions] + Metrics[Metrics Collection] + Config[Configuration Management] + end + + Vixen --> Parser + Vixen --> ProtoGen + Vixen --> Metrics + Vixen --> Config +``` + +## Key Components + +### 1. gRPC Service +- Provides a high-performance interface for transaction parsing +- Uses Protocol Buffers for efficient data serialization +- Supports bi-directional streaming capabilities +- Configurable connection pooling and resource management + +### 2. Parser System +```mermaid +flowchart LR + TX[Raw Transaction] --> Parser[Transaction Parser] + Parser --> Accounts[Account Parser] + Parser --> Instructions[Instruction Parser] + Parser --> |Optional| PreFilter[Account PreFilter] + + Accounts --> |Proto| ParsedAccounts[Parsed Accounts] + Instructions --> |Proto| ParsedInstructions[Parsed Instructions] +``` + +### 3. Monitoring & Observability +- Prometheus integration for metrics +- OpenTelemetry support for distributed tracing +- Configurable logging levels +- Performance monitoring dashboards + +## Technology Stack +- **Language**: Rust (nightly-2024-02-01) +- **Framework**: gRPC with Tonic +- **Serialization**: Protocol Buffers +- **Monitoring**: Prometheus & OpenTelemetry +- **Configuration**: TOML-based with dynamic reloading + +## Development Environment +```mermaid +graph LR + Dev[Development] -->|Rust Toolchain| Build[Build Process] + Build --> Tests[Testing] + Build --> Docker[Docker Image] + Docker --> Deploy[Deployment] + + subgraph "Development Tools" + Clippy[Clippy Linter] + Fmt[Rustfmt] + Proto[Protobuf Compiler] + Test[Test Framework] + end +``` + +## Project Structure +``` +yellowstone-vixen/ +├── crates/ # Workspace crates +│ ├── core/ # Core types and traits +│ ├── parser/ # Transaction parsers +│ ├── proto/ # Protocol buffer definitions +│ └── test/ # Testing utilities +├── docs/ # Documentation +│ └── onboarding/ # Onboarding guides +├── examples/ # Usage examples +└── scripts/ # Development scripts +``` + +## Getting Started +For detailed setup instructions, see [Getting Started Guide](03-getting-started.md). \ No newline at end of file diff --git a/docs/onboarding/02-technical-decisions.md b/docs/onboarding/02-technical-decisions.md new file mode 100644 index 0000000..81f3303 --- /dev/null +++ b/docs/onboarding/02-technical-decisions.md @@ -0,0 +1,127 @@ +# Technical Decisions & Architecture + +## Core Technical Decisions + +### 1. Choice of Rust +- **Memory Safety**: Rust's ownership model ensures thread-safety and prevents memory-related bugs +- **Performance**: Zero-cost abstractions and minimal runtime overhead +- **Ecosystem**: Strong Solana ecosystem support and crypto-related libraries +- **Tooling**: Excellent development tools (rustfmt, clippy, cargo) + +### 2. gRPC Implementation +```mermaid +graph TB + subgraph "gRPC Architecture" + Client[gRPC Client] -->|Protocol Buffers| Server[gRPC Server] + Server --> Parser[Transaction Parser] + Parser --> ProtoGen[Proto Generation] + Parser --> Accounts[Account Parsing] + Parser --> Instructions[Instruction Parsing] + end +``` + +**Benefits**: +- Strongly typed interface definitions +- Efficient binary serialization +- Bi-directional streaming support +- Language-agnostic client support +- High performance with Tonic implementation +- Truncated identifiers for better compatibility + +### 3. Protocol Buffer Design +- Structured message definitions for transactions +- Versioned protocol support +- Efficient serialization/deserialization +- Support for both Orca and Raydium protocols +- Jupiter and Naga program parsers support + +### 4. Monitoring Architecture +```mermaid +graph LR + Service[Vixen Service] -->|Metrics| Prometheus[Prometheus] + Service -->|Push Gateway| PushGateway[Prometheus Push Gateway] + Service -->|Traces| OpenTelemetry[OpenTelemetry] + Service -->|Logs| Logger[Structured Logging] + Prometheus -->|Visualization| Grafana[Grafana] + PushGateway -->|Metrics| Prometheus + OpenTelemetry -->|Analysis| TraceViewer[Trace Viewer] + Logger -->|Aggregation| LogAggregator[Log Aggregator] +``` + +## Design Patterns + +### 1. Parser Architecture +- Modular parser design with trait-based implementation +- Clear separation of concerns between parsing layers +- Extensible plugin system for new program parsers +- Efficient prefiltering mechanism +- Refactored parser system for better maintainability + +### 2. Configuration Management +```mermaid +flowchart TB + Config[TOML Config] --> Parser[Parser Config] + Config --> Metrics[Metrics Config] + Config --> Service[Service Config] + Config --> Features[Feature Flags] + Config --> Auth[Optional Auth] + + Parser --> Runtime[Runtime] + Metrics --> Runtime + Service --> Runtime + Features --> Runtime + Auth --> Runtime +``` + +### 3. Error Handling +- Custom error types with detailed context +- Proper error propagation through async boundaries +- Structured logging for errors +- Graceful failure handling with recovery strategies +- Metric tracking for error rates +- Version conflict resolution strategies + +## Security Considerations + +### 1. Input Validation +- Strict validation of incoming requests +- Size limits on messages +- Rate limiting capabilities +- Protocol buffer validation +- Truncated gRPC identifiers for safety + +### 2. Authentication & Authorization +- Optional username/password authentication +- Configurable security policies +- TLS support for secure communication +- Role-based access control +- API key management +- Flexible authentication configuration + +## Performance Optimizations + +### 1. Parsing Optimizations +```mermaid +graph LR + Input[Raw Input] --> Prefilter[Account Prefilter] + Prefilter --> Cache[Parser Cache] + Cache --> Parser[Main Parser] + Parser --> ProgramParsers[Program Parsers] + Parser --> Output[Parsed Output] +``` + +### 2. Resource Management +- Efficient memory usage with pooling +- Connection pooling for gRPC +- Proper resource cleanup +- Configurable thread pools +- Backpressure handling +- Build flag optimizations + +### 3. Testing Strategy +- Comprehensive unit test coverage +- Integration tests with mock data +- Performance benchmarks +- Fuzzing tests for parser +- Continuous integration pipeline +- Program-specific parser tests \ No newline at end of file diff --git a/docs/onboarding/03-getting-started.md b/docs/onboarding/03-getting-started.md new file mode 100644 index 0000000..7269c68 --- /dev/null +++ b/docs/onboarding/03-getting-started.md @@ -0,0 +1,296 @@ +# Getting Started with Yellowstone Vixen + +## Prerequisites + +Before you begin, ensure you have the following installed: +- Rust (nightly-2024-02-01) +- Protocol Buffer compiler +- OpenSSL development libraries +- Git + +
+macOS Installation + +```bash +# Install Homebrew if not already installed +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" + +# Install Rust +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + +# Install Protocol Buffers +brew install protobuf + +# Install OpenSSL +brew install openssl@3 + +# Set required environment variables +export OPENSSL_DIR=$(brew --prefix openssl@3) +``` +
+ +
+Linux Installation + +```bash +# Install Rust +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + +# Ubuntu/Debian +sudo apt-get update +sudo apt-get install -y protobuf-compiler libssl-dev pkg-config + +# Fedora +sudo dnf install -y protobuf-compiler openssl-devel pkg-config + +# Arch Linux +sudo pacman -S protobuf openssl pkg-config +``` +
+ +
+Windows Installation + +```powershell +# Install Rust +Invoke-WebRequest https://win.rustup.rs/x86_64 -OutFile rustup-init.exe +.\rustup-init.exe + +# Install Chocolatey if not already installed +Set-ExecutionPolicy Bypass -Scope Process -Force +[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072 +iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1')) + +# Install Protocol Buffers +choco install protoc + +# Install OpenSSL +choco install openssl +``` +
+ +## Setting Up the Development Environment + +1. **Clone the Repository** +```bash +git clone https://github.com/rpcpool/yellowstone-vixen.git +cd yellowstone-vixen +``` + +2. **Set Rust Toolchain** +```bash +# Install nightly toolchain +rustup toolchain install nightly-2024-02-01 +rustup override set nightly-2024-02-01 + +# Install required components +rustup component add rustfmt +rustup component add clippy +``` + +3. **Build the Project** +```bash +# Build all crates +cargo build + +# Run tests +cargo test + +# Run with features +cargo build --features "proto token-program" +``` + +## Project Configuration + +1. **Create Configuration File** +```bash +# Copy example configuration +cp Vixen.example.toml Vixen.toml + +# Edit configuration as needed +$EDITOR Vixen.toml +``` + +2. **Environment Setup** +```bash +# Set development environment variables +export RUST_LOG=debug +export RUST_BACKTRACE=1 +``` + +## Running the Service + +1. **Start the Service** +```bash +# Run in development mode +cargo run --bin yellowstone-vixen + +# Run with specific features +cargo run --bin yellowstone-vixen --features "proto token-program" +``` + +2. **Development Tools** +```bash +# Format code +cargo fmt + +# Run linter +cargo clippy + +# Run tests with coverage +cargo tarpaulin +``` + +## Common Development Tasks + +### Adding a New Parser + +1. Create a new module in `crates/parser/src/` +2. Implement the `Parser` trait +3. Add tests in the module's test directory +4. Register the parser in `lib.rs` + +Example: +```rust +use yellowstone_vixen_core::{Parser, ParseResult}; + +pub struct MyParser; + +impl Parser for MyParser { + type Input = InstructionUpdate; + type Output = InstructionUpdate; + + fn id(&self) -> std::borrow::Cow { + "my_parser::MyParser".into() + } + + async fn parse(&self, instruction: &Self::Input) -> ParseResult { + // Implementation here + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[tokio::test] + async fn test_my_parser() { + // Test implementation + } +} +``` + +### Running Integration Tests + +```bash +# Run all integration tests +cargo test --test '*' + +# Run specific test suite +cargo test --test integration_test +``` + +### Debugging + +1. **Enable Logging** +```bash +export RUST_LOG=debug +export RUST_BACKTRACE=1 +``` + +2. **Use VS Code Debug Configuration** +```json +{ + "version": "0.2.0", + "configurations": [ + { + "type": "lldb", + "request": "launch", + "name": "Debug Vixen", + "cargo": { + "args": ["build", "--bin=yellowstone-vixen"] + }, + "args": [], + "cwd": "${workspaceFolder}" + } + ] +} +``` + +## Monitoring & Metrics + +1. **Start Prometheus** +```bash +docker-compose up -d prometheus +``` + +2. **Start Grafana** +```bash +docker-compose up -d grafana +``` + +3. **Access Dashboards** +- Prometheus: http://localhost:9090 +- Grafana: http://localhost:3000 + +## Contributing + +1. Create a new branch +```bash +git checkout -b feature/my-feature +``` + +2. Make changes and commit +```bash +git add . +git commit -m "feat(parser): add new feature" +``` + +3. Run checks +```bash +# Format code +cargo fmt + +# Run linter +cargo clippy + +# Run tests +cargo test +``` + +4. Push changes and create PR +```bash +git push origin feature/my-feature +``` + +## Troubleshooting + +### Common Issues + +1. **Build Failures** +- Check Rust toolchain version +- Verify protobuf compiler installation +- Ensure OpenSSL is properly configured + +2. **Runtime Errors** +- Check configuration file +- Verify environment variables +- Review log output + +3. **Test Failures** +- Run tests with verbose output +- Check test dependencies +- Verify mock data + +### Getting Help + +- Check existing issues on GitHub +- Join our Discord community +- Review documentation in `/docs` +- Contact maintainers + +## Next Steps + +- Review [Technical Decisions](02-technical-decisions.md) +- Explore [Project Overview](01-project-overview.md) +- Join development discussions \ No newline at end of file