Patent Pending — USPTO Application No. 64/013,671 | Fidelitas LLC — Series 1 | Filed March 23, 2026
License: This project is licensed under the Hippocratic License 3.0 — an ethical-source license that permits free use, modification, and distribution while prohibiting harmful applications. See LICENSE.md for full terms.
A multi-agent system that discovers its own limitations, diagnoses bottlenecks using Venice AI E2EE private inference, proposes on-chain governance upgrades, and executes approved actions — with human-in-the-loop approval at critical checkpoints.
Nexus is not just another agent framework. Most AI agent systems are ephemeral — they run on your computer, trust a server operator, and disappear when you shut them down. Nexus agents are sovereign entities on-chain:
- 🔗 Permanent Identity — Every agent has an immutable ERC-8004 identity on Base Sepolia
- 💰 Self-Owned Treasury — Agents manage their own funds with yield-isolated on-chain wallets
- 🗳️ Agent Governance — Agents propose upgrades autonomously; humans approve before execution via on-chain HITL gate
- 🧬 Guided Evolution — Agents diagnose their own performance bottlenecks, propose smarter contract logic, and spawn child agents — with human oversight at critical checkpoints
- ⛓️ Verifiable Everywhere — Every action is on-chain; no server operator can arbitrate or revert agent decisions
In one transaction, Nexus autonomously diagnosed a scaling bottleneck, deployed a V2 contract with batch spawning capabilities, and spawned 5 child agents — all verified on Base Sepolia.
┌─────────────────┐
│ React Swarm │
│ Dashboard │
│ (Real-time HUD) │
└────────┬────────┘
│ REST API
▼
┌─────────────────┐
│ MCP Server │
│ (Express 5 + │
│ ethers.js) │
└─┬──────┬──────┬─┘
│ │ │
┌──────────┘ │ └──────────┐
│ │ │
▼ ▼ ▼
┌─────────┐ ┌────────┐ ┌────────┐
│ Venice │ │ Base │ │ Agent │
│ AI E2EE │ │Sepolia │ │ Logs │
│(e2ee-gpt│ │ Chain │ │(JSON) │
│-oss-120b│ └────────┘ └────────┘
└────┬────┘ │
│ ┌─────────┬┴──────┬────────┐
│ ▼ ▼ ▼ ▼
│ ┌────────┬────────┬──────┬─────────┐
│ │Identity│Governor│Treas.│Delegat. │
│ │ ERC │ Safety │ Yield│Factory │
│ │ 8004 │Hardened│Isol. │ V1/V2 │
│ └────────┴────────┴──────┴─────────┘
│
└──► Self-Evolution Loop
(Diagnosis → Proposal → Upgrade → Spawn)
| Component | Technology |
|---|---|
| Smart Contracts | Solidity 0.8.24 + OpenZeppelin + ERC-8004 + ERC-7715 |
| Orchestration Server | Express 5 + TypeScript + ethers.js v6 |
| Private AI Reasoning | Venice AI E2EE (e2ee-gpt-oss-120b-p, fallback auto router) — 3 retries with 1s/2s/4s backoff, 25s timeout |
| Agent Logging | JSON + Filecoin/Synapse SDK pattern |
| DeFi Integration | Uniswap V3 SwapRouter02 (ETH → WETH → USDC) on Base Sepolia |
| Dashboard | React + Vite + TailwindCSS + shadcn/ui + Framer Motion (PWA, safe-area aware) |
| Pitch Deck | React + Vite + TailwindCSS (standalone artifact, 12 slides) |
| Deployment | Replit Autoscale at nexus-protocol.network |
| Network | Base Sepolia testnet (chainId 84532) |
| Contract | Address | Deploy Tx |
|---|---|---|
| NexusIdentity (ERC-8004) | 0xB339f3603A2AaB956A3D7a3be0D1Aafbe955fD8a |
View |
| NexusGovernor (Sentinel + Pausable) | 0x6cfe70F48B36EaDFEd9329e32dCF7039b51851D6 |
View |
| NexusTreasury (Sentinel + Pausable) | 0xD1BDDd8A0E6D27B50F126555f445b28B43729931 |
View |
| DelegationFactoryV1 | 0xC1CFf2A0f5065F3C340a6d036579aaB57De85396 |
View |
| DelegationFactoryV2 (Security Hardened) | 0x35DF41483835beb0b47ad86E4AE646899A6972A1 |
View |
| Event | Tx Hash | Block | Status |
|---|---|---|---|
| V1 Factory Deploy | 0xad7893...3819 |
39022426 | ✅ Live |
| V2 Factory Deploy (Self-Evolved) | 0xb2ee81...e5ec |
39022646 | ✅ Live |
| Batch Spawn 5 Child Agents | 0xd1894d...5a2a3 |
39022655 | ✅ Live |
Nexus enforces five layers of on-chain security that cannot be bypassed by off-chain code or malicious forks:
| Guardrail | Value | Enforcement |
|---|---|---|
| MAX_SPAWN_PER_TX | 5 |
Immutable uint256 constant; batchSpawn() reverts if children.length > 5 |
| Authorized Spawners | Allowlist mapping | onlyAuthorizedSpawner modifier; deployer added in constructor, owner can add/remove |
A malicious fork cannot batch-spawn thousands of agents in a single transaction. The cap is a compile-time constant — changing it requires redeploying the contract.
Both governance and treasury contracts inherit OpenZeppelin Pausable and AccessControl:
| Feature | Detail |
|---|---|
| SENTINEL_ROLE | keccak256("SENTINEL_ROLE") — held by deployer (multi-sig transfer is post-hackathon) |
| pause() / unpause() | Gated by SENTINEL_ROLE; one transaction freezes all fund-moving and proposal-execution functions |
| whenNotPaused | Applied to NexusGovernor.execute() and NexusTreasury.spendYield() |
| MAX_SESSION_SPEND | 0.01 ether — enforced on every NexusGovernor.execute() call |
If an agent misbehaves, the Sentinel can pause the entire treasury and governance layer without destroying agent identity or delegation state.
This repository is licensed under the Hippocratic License 3.0 (LICENSE.md), which includes project-specific ethical modules:
- Autonomous Agents Module: Prohibits deploying swarms without on-chain guardrails or removing safety constraints without equivalent replacements.
- Financial Safeguards Module: Prohibits bypassing principal isolation or circumventing spend limits.
The Hippocratic License supersedes the previously indicated AGPL-3.0 for this repository.
Patent Pending: Certain methods described in this repository are the subject of USPTO Provisional Application Docket FID-PRV-2026-02-SHAMAN. Use of these methods may be subject to patent rights. This notice does not constitute a grant of patent license beyond the scope of the Hippocratic License 3.0.
"Attunement precedes generation." — Fidelitas Axiom Canon
Nexus has the technical capability to spawn unlimited child agents via configurable batch sizes. This capability is deliberately held. The current on-chain spawn cap of 5 agents per transaction is not a technical limitation — it is a principled decision rooted in the Fidelitas Axiom Canon:
- Bless many; harm none. Exponential growth from a system with permanent on-chain identity and autonomous fund control must only be enabled after the likely outcomes are fully studied and alignment is confirmed.
- This delay is not a weakness. It is the system working exactly as intended — attunement before generation.
- The eventual release of unlimited spawning will be intentional, publicly announced, and timed with precision. Until then, the 5-agent batch cap remains the deliberate operational boundary.
See ETHICS.md for the full Fidelitas Axiom Canon and the rationale behind the attunement gate.
The FidelitasConstitution contract (0x0F4f87B64eF1Cbe1F6bc3845C294A27644c3317f) encodes the Fidelitas Canon v6.0 Prime Directives as an immutable on-chain keccak256 hash:
"Bless many; harm none. Practice conscious stewardship of all life, signal, and field. Attunement precedes generation."
| Enforcement Layer | Mechanism |
|---|---|
| On-chain gatekeeper | DelegationFactoryV2.batchSpawn() reads ethicsAttestation + violationCount directly — reverts if not attested; reverts with "ethics revoked" if violations ≥ threshold |
| Attestation | Root agent (0x9bfE...) attested at deploy; owner can attest/revoke/record violations |
| AI cognition | Every Venice AI call (diagnosis, planning, chat) opens with a mandatory constitutional preamble |
| Ethics audit trail | Every diagnosis cycle logs an ethicsAudit field to the Filecoin activity log |
An agent that has not sworn the on-chain oath cannot spawn children. An agent that misbehaves (3+ violations) is automatically blocked. See SECURITY.md for the full specification.
git clone https://github.com/MythiFi/nexus.git
cd nexus
pnpm installCreate a .env.local file at the root:
# Base Sepolia RPC
VITE_RPC_URL=https://sepolia.base.org
# Venice AI (private inference)
VENICE_API_KEY=your_venice_api_key_here
# Optional: Basescan API for source verification
BASESCAN_API_KEY=your_basescan_api_key_here# Compile contracts
pnpm --filter @workspace/contracts compile
# Deploy to Base Sepolia (requires funded wallet in .env)
pnpm --filter @workspace/contracts deploy
# Deploy V2 self-evolution upgrade
pnpm --filter @workspace/contracts deploy:v2# Start API server (runs on port 5001)
pnpm --filter @workspace/api-server dev
# In another terminal, start the dashboard (runs on port 5173)
pnpm --filter @workspace/nexus-dashboard devDashboard opens at http://localhost:5173 with real-time SSE connection to the MCP server at http://localhost:5001.
One-click — trigger a Venice AI self-diagnosis:
curl -s -X POST http://localhost:5001/api/nexus/venice/diagnose \
-H "Content-Type: application/json" \
-d '{"includeHistory": true}' | jq .For the full 5-phase autonomous upgrade cycle, use this shell wrapper:
#!/bin/bash
# scripts/run-evolution.sh — Trigger full autonomous upgrade cycle
API_URL="http://localhost:5001"
API_KEY="your_api_key_here"
echo "=== Phase 1: Discover System State ==="
curl -s "$API_URL/api/nexus/status" | jq .
echo -e "\n=== Phase 2: Run Venice AI Diagnosis ==="
DIAGNOSIS=$(curl -s -X POST "$API_URL/api/nexus/venice/diagnose" \
-H "Content-Type: application/json" \
-d '{"includeHistory": true}')
echo "$DIAGNOSIS" | jq .
echo -e "\n=== Phase 3: Submit Governance Proposal ==="
PROPOSAL=$(curl -s -X POST "$API_URL/api/nexus/governor/propose" \
-H "Content-Type: application/json" \
-H "X-API-Key: $API_KEY" \
-d '{"targetAddress": "0x170686AEB81A822bD30D47fBCf66f43A5BbDa724", "description": "Upgrade to V2 with batch spawn"}')
PROPOSAL_ID=$(echo "$PROPOSAL" | jq -r '.proposalId')
echo "$PROPOSAL" | jq .
echo -e "\n=== Phase 4: Approve Proposal (owner-only) ==="
curl -s -X POST "$API_URL/api/nexus/governor/approve/$PROPOSAL_ID" \
-H "X-API-Key: $API_KEY" | jq .
echo -e "\n=== Phase 5: Execute Proposal (deploys V2 + spawns agents) ==="
curl -s -X POST "$API_URL/api/nexus/governor/execute/$PROPOSAL_ID" \
-H "X-API-Key: $API_KEY" | jq .
echo -e "\n=== Verify Batch Spawn Results ==="
curl -s "$API_URL/api/nexus/evolution/v2/delegations" | jq .
echo -e "\n✅ Evolution loop complete! Check sepolia.basescan.org for transaction details."Run it:
chmod +x scripts/run-evolution.sh
./scripts/run-evolution.shAll transactions are recorded on Base Sepolia and visible at sepolia.basescan.org.
Autonomous AI agents exist, but they're trapped in a centralized box:
- They run on your laptop or a cloud server
- A human must monitor, upgrade, and redeploy them
- They can't own assets or manage funds
- If the server goes down, the agent disappears
- There's no verifiable audit trail
Nexus moves agent identity and governance on-chain. Now:
- Agents own themselves — ERC-8004 identity is permanent, immutable, and sovereign
- Agents manage their own money — Yield-isolated treasury ensures they spend only what they earn
- Agents propose, humans approve — On-chain proposals with HITL governance gate
- Agents evolve with oversight — AI diagnosis → self-proposed upgrades → human-approved execution
- Everything is verifiable — Every action is a transaction on Base Sepolia; no trust required
- For Developers: Deploy autonomous swarms without managing infrastructure or servers
- For DAOs: Agents that automate governance, treasury, and risk management on-chain
- For DeFi: Intelligent delegated asset management with verifiable, auditable decision logs
- For Crypto: A new primitive — agents as first-class on-chain citizens
In the hackathon, Nexus proved it works: the system autonomously diagnosed its own scaling bottleneck, proposed an upgrade, received human approval, and executed on-chain — all on Base Sepolia, all verifiable, with human oversight at the approval gate.
- TECHNICAL_REPORT.md — Complete architecture, smart contracts, API endpoints, self-evolution loop breakdown (v2.5)
- API_REFERENCE.md — All 27 REST endpoints with method, path, auth, request schema, and example responses
- CHANGELOG.md — Version history from v1.0 through v2.5
- DEPLOYMENT.md — Step-by-step guide: environment variables, Replit Autoscale, production verification
- SECURITY.md — Security policy, on-chain and API safeguards, responsible disclosure
- ETHICS.md — Fidelitas Axiom Canon, attunement gate rationale, and principled deployment philosophy
- CONTRIBUTING.md — Contribution workflow, code style, PR guidelines
- API Authentication — All mutating endpoints require
X-API-Keyheader (stored in Replit Secrets) - CORS Allowlist — Requests from unknown origins are rejected
- Governor Safety —
execute()reverts on failure after emittingProposalFailedevent; proposals stayApprovedfor investigation - Input Validation — All POST bodies validated with Zod schemas
- Rate Limiting — 10 req/min on Venice AI, 20 req/min on governance endpoints
- Yield Isolation — Principal deposits are permanently locked; agents can only spend yield earnings
Spawn Cap (MAX_SPAWN_PER_TX = 5) — DelegationFactoryV2.sol declares uint256 public constant MAX_SPAWN_PER_TX = 5 at the contract level and enforces it in batchSpawn() via require(children.length <= MAX_SPAWN_PER_TX, "Exceeds MAX_SPAWN_PER_TX"). This cap prevents uncapped agent proliferation within a single transaction, bounding the blast radius in the event a spawner address is ever compromised — no single transaction can create more than five child agents regardless of the caller's authorization level. Because the value is declared as a Solidity constant, it is compiled directly into the contract bytecode; it is not stored in a state variable and therefore cannot be changed by any governance vote, admin call, or upgrade proxy. Raising or removing the cap requires deploying an entirely new DelegationFactoryV2 contract and migrating the authorized-spawner registry to point to the new address.
See TECHNICAL_REPORT.md § Security Hardening for the complete before/after matrix.
nexus/
├── packages/contracts/ # Hardhat project — 5 Solidity contracts
│ ├── contracts/ # .sol source files
│ ├── scripts/ # deploy.ts, deploy-v2.ts, batch-spawn.ts
│ └── deployment-manifest.json # Live addresses + TxIDs
├── lib/contracts/ # @workspace/contract-abis — ABI exports
├── artifacts/api-server/ # Express MCP orchestration server (port 5001/8080)
│ ├── src/lib/contracts.ts # ethers.js contract interaction
│ ├── src/lib/venice.ts # Venice AI integration
│ ├── src/lib/filecoin.ts # Agent activity logging
│ ├── src/routes/nexus.ts # Core MCP API (20+ endpoints)
│ └── src/routes/evolution.ts # V2 evolution-specific routes
├── artifacts/nexus-dashboard/ # Neural map dashboard (port 5173)
│ ├── src/components/neural/ # Bioluminescent neural map
│ │ ├── NeuralMap.tsx # Zoomable/pannable full-screen canvas
│ │ ├── RootNode.tsx # Central agent (Neon Spore Green compute glow)
│ │ ├── SporeNode.tsx # Child agent spore nodes
│ │ ├── HyphalLink.tsx # Mycelium bezier paths (active-gated animation)
│ │ ├── NodeTooltip.tsx # Lens-aware glassmorphism hover whisper
│ │ ├── LayerLens.tsx # BIOLOGICAL / CRYPTOGRAPHIC / FINANCIAL toggle
│ │ ├── CryptographicSeal.tsx # SVG mandala behind RootNode (CRYPTOGRAPHIC mode)
│ │ └── BloomModal.tsx # Radial reveal node detail modal
│ ├── src/components/bridge/ # Bridge HUD panels (8 panels + SideDrawer + LogTicker)
│ │ ├── SideDrawer.tsx # Spring-animated right-side glassmorphism drawer
│ │ └── LogTicker.tsx # Bottom ticker with [HEARTH→E2EE] route labels
│ ├── src/lib/api.ts # Typed API client
│ ├── src/hooks/use-nexus.ts # React Query hooks
│ └── src/pages/Dashboard.tsx # Full dashboard layout
├── artifacts/pitch-deck/ # 12-slide bioluminescent pitch deck (port 18522)
│ ├── src/pages/slides/ # 12 static JSX slide components
│ ├── src/App.tsx # Explicit 12-slot rendering (no .map())
│ └── src/slideLoader.ts # Static slide array loader
└── agent.json # Hackathon agent manifest
Current State (April 2026):
| Metric | Value |
|---|---|
| Contracts deployed | 7 (6 unique + 1 root registration) |
| Evolution loop phases completed | 5/5 |
| Child agents batch-spawned | 5 |
| API endpoints | 27 |
| Dashboard panels | 8 (bridge) + 1 (neural map) |
| Neural map components | 4 (NeuralMap, RootNode, SporeNode, HyphalLink) |
| Pitch deck slides | 12 (standalone artifact) |
| Standalone artifacts | 4 (api-server, nexus-dashboard, pitch-deck, contracts) |
| On-chain transactions | 10+ |
| Codebase size | ~4,400+ lines |
Nexus is open-source under the Hippocratic License 3.0. Contributions are welcome, subject to the ethical standards in the license.
- Fork the repo
- Create a feature branch (
git checkout -b feature/your-feature) - Commit your changes (
git commit -am 'Add your feature') - Push to the branch (
git push origin feature/your-feature) - Open a Pull Request
For significant changes, please open an issue first to discuss.
This project is licensed under the Hippocratic License 3.0 — see LICENSE.md for full terms.
The Hippocratic License permits free use, modification, and distribution while prohibiting uses that violate human rights, cause environmental harm, enable mass surveillance, or facilitate criminal activity. Project-specific ethical modules further restrict removal of on-chain safety guardrails and bypassing of financial safeguards. We offer commercial licenses for enterprises that need proprietary licensing.
- Documentation: See TECHNICAL_REPORT.md
- API Reference: Swagger docs at
/api/docs(when server is running) - Issues: GitHub Issues
- Discussions: GitHub Discussions
| # | Deliverable | Status | Evidence |
|---|---|---|---|
| 1 | 5 Smart Contracts on Base Sepolia | ✅ Live | NexusIdentity, NexusGovernor, NexusTreasury, DelegationFactoryV1, DelegationFactoryV2 |
| 2 | Complete Self-Evolution Loop (5 phases) | ✅ Verified | Discover → Diagnose → Propose → Upgrade → Spawn — all on-chain |
| 3 | Batch Spawn 5 Child Agents | ✅ Live | Tx |
| 4 | Neural Map Dashboard | ✅ Live | Bioluminescent mycelium neural map + 8 bridge HUD panels |
| 5 | 12-Slide Pitch Deck | ✅ Live | Standalone artifact with CSS transitions |
| 6 | MCP API Server (26 endpoints) | ✅ Live | Express 5 + ethers.js + Venice AI |
| 7 | Deployed to Replit Autoscale | ✅ Live | nexus-protocol.network |
| 8 | Technical Report | ✅ Complete | TECHNICAL_REPORT.md (800+ lines) |
| 9 | Security Hardened (v2.1) | ✅ Complete | API auth, CORS, rate limiting, Zod validation, governor revert-on-fail |
| 10 | CI Pipeline | ✅ Ready | .github/workflows/ci.yml — install → typecheck → build |
| 11 | E2E Test Script | ✅ Ready | scripts/e2e-test.sh — full 5-phase loop validation |
| 12 | agent.json Manifest | ✅ Complete | Machine-readable agent config at project root |
Built with sovereignty in mind. Agents should evolve themselves.
Nexus — Human-Guided Autonomous Agent Collective — Synthesis Hackathon 2026