🌐 AOXCORE

Enterprise DAO, Security, and AI Governance Stack on XLayer

AOXCORE is a modular monorepo engineered for enterprise-grade governance, security, and AI-assisted operational control on XLayer.

Institutional Hardening Notice
This repository is currently in its Core Hardening Phase.
Architectural foundations are established while security gates, upgrade guarantees, and validation workflows are being progressively strengthened.

Production Risk Disclosure (Pre-Mainnet / Design-Hardening Stage)
AOXCORE is currently under active architecture and security hardening.
Until an independent external audit and final governance signoff are completed, this codebase should be treated as pre-production and operationally risky for unmanaged mainnet use.

---

Overview

AOXCORE provides a layered architecture for decentralized governance infrastructure combined with operational intelligence systems.

The strategic objective is explicit:

Deliver a deterministic, auditable, and upgrade-safe DAO execution environment in which AI can assist operators under strict policy boundaries.

The system focuses on:

• upgrade-safe smart contract infrastructure
• deterministic governance execution
• AI-assisted operational analysis
• enterprise-grade monitoring and logging systems

---

Repository Architecture

The repository is organized into layered components.

Protocol Layer (/src, /test, /script)

Core on-chain logic and validation environment.

Includes:

• upgradeable Solidity modules (UUPS + namespaced storage)
• DAO governance primitives
• treasury and finance modules
• registry infrastructure
• security sentinel modules

Validation includes:

• unit testing
• integration testing
• fuzz testing
• storage layout verification

---

Backend Layer (/backend)

Operational service layer for monitoring and automation.

Capabilities include:

• Sentinel risk analysis API
• structured logging pipelines
• forensic event tracking
• operator policy enforcement

---

Frontend Layer (/frontend)

React-based operational console.

Features include:

• governance telemetry
• audit visibility dashboards
• protocol health monitoring
• operator workflow controls

---

CLI Layer (/cli)

Command-line utilities for operators.

Includes tools for:

• state inspection
• governance interaction
• reconciliation diagnostics
• operational reporting

---

Governance & Delivery (/docs)

Engineering documentation and rollout procedures.

Includes:

• migration runbooks
• security hardening plans
• engineering evolution roadmap
• CI guardrails for storage-slot safety
• XLayer + Sui legacy-honor execution plan
• AoxCore-XAS modest revolution plan
• V1→V2 mainnet migration and audit readiness baseline

---

Repository Structure

aoxcore/
│
├─ src/            # Solidity smart contracts
│  └─ aoxcore-xas/ # New XAS-centric Move + Solidity modules
├─ test/           # Foundry test suite
├─ script/         # Deployment and tooling scripts
│
├─ backend/        # Sentinel API services
├─ frontend        # Operator console
├─ cli             # Command-line operational tools
│
├─ docs            # Governance and architecture documentation
│
├─ foundry.toml
├─ package.json
└─ README.md

---

Core Design Principles

Determinism Before Automation

AI assists operational workflows but does not replace governance controls.

Privileged actions remain:

• policy gated
• attributable
• reviewable

---

Upgrade Safety by Default

Upgrade discipline relies on:

• ERC-7201 namespaced storage
• migration rehearsal
• post-upgrade invariant verification

---

Logs as Operational Truth

Operational reliability depends on structured logging.

Capabilities include:

• request correlation identifiers
• event categorization
• forensic reconstruction support

---

Separation of Duties

Governance authority is distributed across distinct roles:

• governance execution
• security sentinel
• audit verification
• upgrade authorization

---

Progressive Hardening

Security posture improves continuously through:

• CI validation gates
• regression testing
• storage-slot parity checks
• automated remediation workflows

---

Quick Start

Protocol Engineering

Prerequisite: Foundry (Forge) Installation

If forge is not available on your system, use the repository installer:

bash script/install_foundry.sh

What the installer does:

• verifies required system tools (bash, curl, git)
• installs foundryup if missing
• installs/updates the stable Foundry toolchain (forge, cast, anvil, chisel)
• verifies tool versions and surfaces actionable warnings for common repo issues (e.g., empty lib/ dependency folders)

Manual fallback (official method):

curl -fsSL https://foundry.paradigm.xyz | bash
foundryup

Post-install verification:

forge --version
cast --version
anvil --version
chisel --version

Build contracts:

forge build

Verify storage layout:

python script/check_storage_slots.py

Run tests:

forge test

Run fuzz testing:

forge test --fuzz

---

Backend Sentinel API

cd backend
npm install
npm run dev

---

Frontend Operational Console

cd frontend
npm install
npm run dev

---

Security Gates

Storage Slot Safety

python script/check_storage_slots.py

Static Solidity Validation

python script/static_solidity_sanity.py

---

Upgrade Model

AOXCORE contracts use the UUPS Upgradeable Proxy pattern.

Upgrade process includes:

1. storage layout verification
2. migration rehearsal
3. multisig governance approval
4. invariant verification after upgrade

---

Migration Readiness References

Key operational documents:

• docs/V1_V2_PARITY_MATRIX.md
• docs/MIGRATION_REHEARSAL_RUNBOOK.md
• script/RehearseV1ToV2.s.sol
• script/VerifyV1ToV2Invariants.s.sol

---

Logging and Observability

AOXCORE uses structured logging to support operational forensics.

Features include:

• request IDs for every backend call
• security event categorization
• operator-safe error reporting
• full forensic diagnostic context

Documentation:

• docs/LOGGING_AND_OPERATIONS_STANDARD.md
• docs/DEVELOPMENT_FULL_EVOLUTION_PLAN.md
• docs/XLAYER_SUI_FULL_GATEWAY_BLUEPRINT.md
• docs/WEB_PUBLISH_AND_RC_CHECKLIST.md
• docs/GOVERNANCE_ENTERPRISE_REFACTOR_PLAN.md

---

Development Workflow

Typical development cycle:

1. implement feature
2. add tests
3. run storage validation
4. run fuzz testing
5. open pull request
6. CI validation executes

Only validated changes are merged.

---

Contribution Guidelines

Contributions must:

• include relevant tests
• preserve upgrade safety
• follow repository coding standards
• pass CI validation

See docs/CONTRIBUTING.md.

---

License

This project is licensed under the MIT License.

See the LICENSE file for details.

---

_{© 2026 AOXCORE Protocol | Secure. Auditable. Upgrade-Safe.}

---

Mainnet Migration Readiness (V1 → V2)

For production upgrade discipline (storage continuity, governance safety, and audit evidence), follow:

• docs/V1_V2_MAINNET_AUDIT_READINESS.md
• docs/MIGRATION_REHEARSAL_RUNBOOK.md
• docs/V1_V2_PARITY_MATRIX.md
• docs/SECURITY.md

These documents define the minimum acceptance criteria before mainnet upgrade execution.

---

Library Consumer Integration (AOXCHAIN)

For external-chain consumption (e.g. aoxchain), use the wrapper modules under src/aoxc-library and the generated approved-manifest:

python3 script/generate_library_manifest.py
cat src/aoxc-library/manifest/approved-modules.json

Detailed integration and migration blueprint:

• docs/AOXCHAIN_LIBRARY_INTEGRATION.md

Additional sectioned standalone layout docs:

• docs/AOXC_STANDALONE_LIBRARY_LAYOUT.md
• docs/AOXCHAIN_BACKEND_INTERFACE_CONTRACT.md

---

Foundry Installation Runbook (Production-Friendly)

Use this checklist for deterministic local setup and CI runners:

1. Install toolchain with bash script/install_foundry.sh.
2. Confirm PATH includes ~/.foundry/bin.
3. Pin and inspect versions using forge --version.
4. Initialize dependencies if needed:

   git submodule update --init --recursive

5. Run repository validation pipeline:

   bash script/validate_foundry_pipeline.sh

Troubleshooting

• forge: command not found
  • Re-open your shell, or run:

    export PATH="$HOME/.foundry/bin:$PATH"

• TLS/HTTPS download failures
  • Ensure CA certificates are installed on your OS.
• Build fails due to missing imports in lib/
  • Run submodule/dependency initialization before forge build.
• CI environment mismatches
  • Print tool versions as an explicit CI step and fail fast when forge is absent.

This workflow is designed to be idempotent and safe to run repeatedly across developer machines and ephemeral CI agents.