Aegis Middleware

Aegis Middleware is a Soroban-native middleware library for high-TVL DeFi protocols that need plug-and-play security modules. The first focus areas are re-entrancy guards, access control, and rate-limiting primitives that can be composed into protocol contracts without re-implementing the same protection logic in every codebase.

This repo is being shaped as a contribution-ready starter for building and testing those security modules alongside a lightweight web scaffold for local development and contract exploration.

Architecture

The repository is organized around a small set of layers:

• contracts/ contains Soroban contract examples and the security primitives they will evolve into.
• packages/ contains TypeScript clients generated from the contracts for local integration workflows.
• src/ contains the React app used to inspect, document, and interact with contracts during development.
• target/ stores build artifacts and compiled WASM output.

The intended middleware surface is modular:

• Re-entrancy locks to prevent nested execution paths from mutating shared state unexpectedly.
• Access control helpers to centralize admin, operator, and protocol-role checks.
• Rate-limiting controls to cap sensitive actions by address, asset, or action type.
• Test helpers and fixtures that make the security modules easy to fuzz and reason about.

Getting Started

1. Install the Rust and Node.js toolchains required by the Stellar scaffold.
2. Run npm install from the repo root to install the frontend and workspace packages.
3. Use npm run dev to launch the local app and contract workflow.
4. Use the Contract Explorer and Transaction Explorer in the app to inspect contract behavior while you build security modules.

If you are extending the Rust contracts, keep the package boundaries small and prefer one responsibility per module so the middleware remains easy to audit.

Roadmap

• Add reusable re-entrancy guard primitives for Soroban contracts.
• Ship access-control helpers with clear role definitions and tests.
• Add rate-limiting middleware for high-frequency protocol actions.
• Expand exhaustive unit tests for success, failure, and edge cases.
• Add fuzz tests that probe state transitions and lock-release behavior.
• Publish implementation docs that protocol developers can copy into their own codebases.

Wave Issue Strategy

Work in Waves keeps the repo focused and reviewable:

• Wave 1: security core. Re-entrancy locks, role checks, and the first middleware interfaces.
• Wave 2: verification. Exhaustive unit tests, fuzz tests, and regression coverage for failure paths.
• Wave 3: developer experience. Documentation, examples, and integration guidance for protocol teams.

When opening issues, prefer a tight scope, an explicit success condition, and a clear test plan. If the work touches security behavior, include the threat model or misuse case the issue is meant to address.