docs: add CHANGELOG.md to repo root (#373)

CHANGELOG.md

@@ -0,0 +1,129 @@
+# 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.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### On-Chain Contracts
+
+#### router-core
+- Central dispatcher for route resolution and registration
+- Global and per-route pause controls
+- Event emission on route resolution
+- Support for versioned routing through router-registry
+
+#### router-registry
+- Versioned contract address registry with `(name, version)` keying
+- Monotonic version enforcement
+- Deprecation support with `get_latest` for non-deprecated entries
+- Contract address versioning and migration support
+
+#### router-access
+- Three-tier role-based access control (RBAC)
+  - Super admin: Full permissions
+  - Role admin: Can grant/revoke specific named roles
+  - Role members: Hold named roles
+- Address blacklisting to prevent role grants
+- Role enumeration and querying capabilities
+
+#### router-middleware
+- Pre/post call hooks for routing operations
+- Per-route rate limiting with configurable time windows
+- Global and per-route enable/disable toggles
+- Call event logging and audit trails
+- Circuit breaker protection for failing routes
+
+#### router-timelock
+- Delayed execution queue for sensitive router configuration changes
+- Configurable minimum delay enforcement
+- Operation cancellation before execution
+- Event logging for all state changes
+
+#### router-multicall
+- Batch execution of multiple cross-contract calls in single transaction
+- Required vs. optional call classification
+- Batch failure handling with success/failure counts
+- Public execute_batch interface (not admin-only)
+- Configurable maximum batch size
+
+### Off-Chain Components
+
+#### router-api-server
+- Off-chain API server for transaction simulation and preview
+- Real-time transaction status tracking via WebSocket
+- Route breakdown analysis and fee estimation
+- Estimated fee calculation with surge multiplier detection
+- Transaction status events (PENDING, SUBMITTED, CONFIRMED, FAILED)
+
+#### router-metrics-exporter
+- Prometheus/OpenTelemetry metrics exporter for contract state polling
+- Scrapes all six router contracts at configurable intervals
+- Exposes standard metrics: `router_*` prefixed counters, gauges, and histograms
+- Contract-level metrics for circuit breaker state, call counts, and failure tracking
+- Exporter health metrics (scrape duration, error counts, uptime)
+- Docker support with multi-stage build
+- Docker Compose integration with Prometheus and Grafana
+- Prometheus alerting rules for operational monitoring
+
+### Features
+
+#### Security
+- Multi-signature support via Stellar native accounts
+- Admin key rotation via `transfer_admin` / `transfer_super_admin`
+- Replay protection through transaction sequence numbers
+- Nonce-based HTTP request replay detection (api-server middleware)
+- Blacklist enforcement across all role assignments
+
+#### Reliability
+- Circuit breaker pattern for failure isolation
+- Graceful degradation with optional vs. required calls
+- Event logging for all state-changing operations
+- Exporter health checks and metrics staleness detection
+
+#### Developer Experience
+- Comprehensive SDK documentation
+- Plugin system for liquidity providers
+- WebSocket real-time transaction tracking
+- Transaction fee estimation before execution
+- Grafana dashboard template included
+
+### Building & Testing
+
+- Integrated test suite with 42+ tests across all contracts
+- Integration tests for cross-contract interactions
+- Load testing tools (artillery-based and custom scripts)
+- Docker Compose environment for local development
+- CI/CD pipeline with automated testing and builds
+
+## Versioning Policy
+
+We follow [Semantic Versioning](https://semver.org/):
+
+- **MAJOR**: Breaking changes to contract interfaces or off-chain APIs
+- **MINOR**: New functionality added in a backward-compatible manner
+- **PATCH**: Bug fixes and non-breaking improvements
+
+## Migration Guide
+
+For upgrading between versions:
+1. Review the changelog entry for your current → target version
+2. Check for any breaking changes marked with ⚠️
+3. Follow upgrade instructions in `docs/upgrading.md`
+4. Test migrations in testnet before mainnet
+
+## Contributing
+
+When adding changes, please:
+1. Update this CHANGELOG under `[Unreleased]` section
+2. Follow the "Added", "Changed", "Deprecated", "Removed", "Fixed", "Security" categories
+3. Link to related GitHub issues using `#123` format
+4. Keep entries concise and user-focused
+
+## Previous Releases
+
+Check the `metrics/CHANGELOG.md` for the metrics-exporter component's independent release history.
+
+