From 899dba29858e2bfd20b21766e9253ceac3c31248 Mon Sep 17 00:00:00 2001 From: Devdave-0x Date: Tue, 26 May 2026 22:45:14 +0000 Subject: [PATCH 1/4] docs: add root CHANGELOG.md with on-chain contracts overview --- CHANGELOG.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..3c0c5af --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,50 @@ +# 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 From a6f7aaf6bc8671d526b0c5d5f5fd10321d1de739 Mon Sep 17 00:00:00 2001 From: Devdave-0x Date: Tue, 26 May 2026 22:45:28 +0000 Subject: [PATCH 2/4] docs: add off-chain components to CHANGELOG (api-server, metrics-exporter) --- CHANGELOG.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3c0c5af..6fc518d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -48,3 +48,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/). - 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 + From 36f8bc9b150002ef0aaf12c2cf077242bc4df8ae Mon Sep 17 00:00:00 2001 From: Devdave-0x Date: Tue, 26 May 2026 22:45:45 +0000 Subject: [PATCH 3/4] docs: add features and building/testing sections to CHANGELOG --- CHANGELOG.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6fc518d..0a6c2b7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -68,3 +68,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/). - 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 + + From 8d9e399e596c4fba966597949bafb4a0c43d8c59 Mon Sep 17 00:00:00 2001 From: Devdave-0x Date: Tue, 26 May 2026 22:46:01 +0000 Subject: [PATCH 4/4] docs: add versioning policy and contribution guidelines to CHANGELOG --- CHANGELOG.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0a6c2b7..e6c1034 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -98,4 +98,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/). - 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. +