Aegis RWA Contracts

Core smart contract infrastructure for the Aegis RWA Protocol. Built on the Stellar network using the Soroban SDK.

Overview

Aegis enables the fractional tokenization of Real-World Assets (RWAs). The contracts strictly enforce regulatory compliance at the ledger level, ensuring tokens can only be minted to and transferred between KYC-whitelisted addresses.

Prerequisites

• Rust (>= 1.71)
• Soroban CLI

Setup & Build

1. Install the wasm32-unknown-unknown target:

   rustup target add wasm32-unknown-unknown

2. Build the contract:

   make build

Testing

Run the comprehensive test suite locally:

make test

Before opening a PR, run make verify (fmt-check + clippy + test + build) -- this is the same gate CI enforces, and failing checks can block PR approval. See the CI & Contributing section below, especially the Failing CI Response Guide, if anything fails.

SDK integration fixtures

Deterministic example outputs for downstream SDK, dashboard, and indexer repos live in fixtures/sdk/. They are generated from real contract invocations and re-verified on every test run, so contract drift fails CI here instead of reaching consumers:

make test-fixtures          # verify committed fixtures still match
make update-fixtures        # regenerate after an intentional change

See SDK Integration Fixtures for the format, the value-encoding rules, and the no-real-user-data guarantee.

Security & Compliance

Important: Please read our Legal Boundary Disclaimer to understand the off-chain assumptions and limitations of the RWA tokenization model.

• RWA Protocol Threat Model — protected assets, trust boundaries, threat catalog (compliance bypass, admin/role misuse, minting and transfer risks, pause misuse, event reliability), and explicit off-chain/legal out-of-scope items

• Emergency Pause Policy — global pause mechanism, authorization, and trust model

• Admin Roles & Permissions — role-based access control (RBAC) design

• Admin Misuse Risks — threat model and mitigations

• Supply Cap Amendment Governance — 2-step cap amendment workflow and enforcement

• Protocol Configuration Governance — global configuration module (ProtocolConfig) 2-step governance workflow and RWA guardrails

• Compliance Status Lifecycle — five-state investor lifecycle (Unknown/Pending/Approved/Revoked/Blocked), enforced transition matrix, authorization rules, and mint/transfer enforcement

• Compliance Status Transitions — the approved/revoked/blocked/pending/unknown state machine, its transition matrix under authorised and unauthorised callers, and the invariant transition tests that guard it (audit readiness)

• Compliance Batch Updates - atomic multi-address lifecycle updates, edge cases, event ordering, and SDK/dashboard guidance

Errors

• Contract Error Code Standard — standardized error codes for compliance, admin, minting, transfer, and storage failures, plus SDK/dashboard mapping guidance

• Transfer Restriction Reason Codes — granular blocked-transfer reasons (non-compliant sender/recipient, paused/retired/blocked asset, cap breaches, unauthorised operation), pre-flight reason reads, and the SDK/dashboard mapping contract

• SDK Integration Fixtures — deterministic example outputs for compliance, minting, transfer, event, error, and capability scenarios, for cross-repo testing

• Investor Holding Restriction Checks — per-investor holding cap workflow and enforcement

Investor Tooling

• Investor Eligibility Read Helpers — compliance, holding-cap, and transfer eligibility read helpers for SDKs and dashboards

• Dashboard Integration Readiness Review — API gaps, event limitations, and SEP-41 token compatibility risks for front-end integrations

• Dashboard Release Readiness Review (MVP) — UI/UX gaps, test coverage requirements, and security flow risks for the dashboard application

• Requirement Traceability Mapping — mandatory completion table format for PR acceptance criteria mapping, with status tracking and incomplete criteria handling

• Compliance Registry Reads and Indexing Strategy — supported point reads, event-indexed pagination, consistency guarantees, and dashboard/SDK boundaries

• Dashboard Integration Readiness Review — API gaps, event limitations, and SEP-41 token compatibility risks for front-end integrations

• Dashboard Release Readiness Review (MVP) — UI/UX gaps, test coverage requirements, and security flow risks for the dashboard application

• Dashboard Local Troubleshooting Guide — practical fixes for Freighter setup, RPC errors, and Next.js configuration

Contributor Guides

• Contributor Evaluation Policy — formal policy covering evaluation expectations, self-review, maintainer review standards, GrantFox evaluation, testing/CI, acceptance criteria completion, and payment-period conduct
• Contributor Self-Review Form — mandatory self-review covering requirements, implementation, tests, CI, documentation, and known limitations
• Local Deployment Guide — deployment assumptions, environment variables, Makefile reference, Soroban CLI usage, and common errors
• Reviewer Checklist — standardized quality and security checklist for PR reviewers
• Contributor Experience Review — known onboarding friction and follow-up items

CI & Contributing

Failure type	Where to look	Local fix command
Compilation error	cargo build output	make build
Test failure	cargo test output	make test
Formatting	unformatted files	make fmt (or make fmt-check to check only)
Lint warnings	cargo clippy output	make clippy
All of the above	full pre-push gate	make verify

See Failing CI Response Guide for detailed causes and fixes per category.

• Evaluation Readiness Summary — central page summarizing what makes a contribution evaluation-ready: testing standards, CI workflow, PR evidence, acceptance criteria mapping, self-review, and conduct guidance
• PR Evidence Checklist — mandatory evidence checklist for every PR: issue reference, implementation summary, tests, commands run, CI status, and acceptance criteria coverage
• Local Verification Command — run make verify (fmt-check + clippy + test + build) before pushing to avoid failing CI
• Failing CI Response Guide — how to reproduce and fix Rust, Soroban, Makefile, dependency, and workflow failures (failing checks can block approval)
• Payment-Period Conduct Note — contributor expectations during paid periods: no spam, self-review, GrantFox evaluation, CI/testing
• Meaningful Implementation Checklist — what counts as real contract work: behaviour, security, tests, events, acceptance criteria + reviewer checks
• Meaningful Change Threshold Guide — why line count alone is not the standard, small-but-complete vs. small-but-incomplete examples, and reviewer scope-assessment guidance
• Aegis Contracts Contribution Examples — side-by-side comparisons of low-effort, partial, under-tested, failing-CI, and acceptable contributions (reference before opening a PR)
• Minimum Testing Standards — mandatory testing requirements per module, happy-path and negative-path expectations, integration fixtures, manual verification guidance, and no-test justification policy

Contributing

Please see CONTRIBUTING.md for guidelines on how to submit pull requests, branch naming conventions, and testing requirements.