# anima-sui/anima-protocol architecture

> Architecture diagram of the GitHub repository anima-sui/anima-protocol, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anima-sui/anima-protocol
- Repository: https://github.com/anima-sui/anima-protocol

## Overview

1. **Repository shape**
   - This is a multi-package monorepo for the ANIMA protocol.
   - It combines on-chain Sui Move contracts, off-chain agent execution in Python, a TypeScript/NestJS backend, a separate event indexer, and two Next.js frontends: a public landing app and an explorer/console.

2. **Core protocol boundary: Sui Move contracts**
   - `contracts/` is the trust anchor.
   - The main modules are `protocol.move`, `wallet.move`, `skill_registry.move`, and `events.move`.
   - These define the agent object, ownership/capability rules, sovereign vault behavior, skill registration, and emitted telemetry events.

3. **Agent identity and custody model**
   - ANIMA’s central on-chain object is the NFA/agent container.
   - Human guardians hold privileged capabilities such as `OwnerCap`.
   - The agent itself can control a dedicated vault, but only through contract-enforced rules and an authorized operator address, which creates the key architectural safety boundary.

4. **Skill and strategy storage**
   - Skills are not stored as heavy on-chain logic; they are referenced by ID.
   - The skill registry points to Walrus blob IDs, and the off-chain runtime retrieves the corresponding strategy/config from Walrus.
   - This keeps strategy metadata decentralized while keeping the on-chain object small and auditable.

5. **Off-chain agent runtime**
   - `agent-runtime/` is the autonomous execution layer, written in Python.
   - It contains orchestration, prediction/monitoring, Sui and Walrus clients, and wallet-management logic.
   - Its role is to inspect the agent’s state and skill config, decide whether to act, and construct Sui Programmable Transaction Blocks for execution.

6. **Execution flow**
   - The runtime uses an operator hot wallet to sign PTBs.
   - The PTB calls into the Sui contracts to extract funds or perform agent actions, then the resulting assets are sent to a target protocol or recipient.
   - This separates decision-making off-chain from enforcement and state changes on-chain.

7. **Backend execution and relaying**
   - `backend/` is a NestJS service layer around Sui interactions.
   - It exposes agent-related endpoints, wraps PTB construction/execution, and includes integration points for Sui, DeepBook swap logic, and an indexer service.
   - It also hosts a global exception filter, suggesting it acts as the controlled API boundary for off-chain operations.

8. **Event indexing and persistence**
   - There are two indexing paths: `backend/src/indexer/` and the standalone `indexer/` package.
   - Both are centered on listening to Sui events from the ANIMA package and translating them into application data.
   - The persisted event data feeds analytics and action history, with Supabase/PostgreSQL used by the explorer side for queryable state.

9. **Explorer console**
   - `explorer/` is the operational UI for inspecting agents.
   - It reads live agent state from Sui RPC and historical actions from Supabase.
   - The agent detail view includes identity, wallet/vault status, skill registry, action feed, and a kill-switch/guardian flow tied to `OwnerCap`.

10. **Public web app**
    - `app/` is a separate Next.js frontend focused on the protocol’s public-facing marketing and minting experience.
    - It contains landing-page sections plus a mint page, so it likely serves as the primary user entry point before users move into the explorer/console workflow.

11. **Data sources and external dependencies**
    - The architecture depends materially on Sui testnet fullnodes for chain reads/writes, Walrus for decentralized config blobs, and Supabase/PostgreSQL for indexed activity history.
    - DeepBook support in the backend indicates the protocol can route agent execution into DeFi swaps rather than just simple transfers.

12. **Overall system diagram perspective**
    - The best architectural split is: on-chain protocol state and enforcement, off-chain autonomous decision/execution, event ingestion/persistence, and user-facing observability/control.
    - The trust boundary is the chain contract plus capabilities; the runtime and frontends are convenience/control layers, not the source of truth.

Main entry points: [`explorer/app/agents/[id]/page.tsx`](https://github.com/anima-sui/anima-protocol/blob/main/explorer/app/agents/[id]/page.tsx) (Agent page), [`agent-runtime/src/orchestrator.py`](https://github.com/anima-sui/anima-protocol/blob/main/agent-runtime/src/orchestrator.py) (Orchestrator), [`agent-runtime/wallet_management/wallet_agent.py`](https://github.com/anima-sui/anima-protocol/blob/main/agent-runtime/wallet_management/wallet_agent.py) (Wallet mgmt), [`backend/src/ptb/ptb.service.ts`](https://github.com/anima-sui/anima-protocol/blob/main/backend/src/ptb/ptb.service.ts) (PTB service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_onchain["On-chain protocol"]
  node_contracts_protocol{{"Protocol<br/>Move module<br/>[protocol.move]"}}
  node_contracts_wallet{{"Wallet<br/>Move module<br/>[wallet.move]"}}
  node_contracts_skills{{"Skill registry<br/>Move module"}}
  node_contracts_events{{"Events<br/>Move module<br/>[events.move]"}}
end

subgraph group_runtime["Agent runtime"]
  node_runtime_orchestrator["Orchestrator<br/>Python control<br/>[orchestrator.py]"]
  node_runtime_predictor["Predictor<br/>Python policy<br/>[predictor.py]"]
  node_runtime_sui["Sui client<br/>Python chain client<br/>[sui_client.py]"]
  node_runtime_walrus["Walrus client<br/>Python blob client<br/>[walrus_client.py]"]
  node_runtime_wallet["Wallet mgmt<br/>Python wallet flow<br/>[wallet_agent.py]"]
end

subgraph group_backend["Backend API"]
  node_backend_agent["Agent API<br/>NestJS controller"]
  node_backend_ptb["PTB service<br/>NestJS executor<br/>[ptb.service.ts]"]
  node_backend_sui["Sui service<br/>NestJS chain<br/>[sui.service.ts]"]
  node_backend_deepbook["DeepBook<br/>Swap integration"]
  node_backend_indexer["Indexer svc<br/>NestJS indexer<br/>[indexer.service.ts]"]
  node_backend_store[("Event store<br/>Event persistence<br/>[store.ts]")]
end

subgraph group_indexing["Indexing"]
  node_standalone_indexer["Indexer<br/>TS listener<br/>[index.ts]"]
  node_indexer_listener["Listener<br/>TS stream<br/>[listener.ts]"]
end

subgraph group_explorer["Explorer console"]
  node_explorer_agent["Agent page<br/>Next.js view<br/>[page.tsx]"]
  node_explorer_hooks["Data hooks<br/>React data<br/>[useAgent.ts]"]
  node_explorer_sui["Explorer Sui<br/>Frontend chain client<br/>[sui.ts]"]
  node_explorer_supabase[("Supabase<br/>Postgres store<br/>[supabase.ts]")]
end

subgraph group_public["Public app"]
  node_public_home["Landing app<br/>Next.js frontend<br/>[page.tsx]"]
  node_public_mint["Mint page<br/>Next.js view<br/>[page.tsx]"]
end

node_runtime_orchestrator -->|"decides"| node_runtime_predictor
node_runtime_orchestrator -->|"reads chain"| node_runtime_sui
node_runtime_orchestrator -->|"loads config"| node_runtime_walrus
node_runtime_orchestrator -->|"builds action"| node_runtime_wallet
node_runtime_wallet -->|"PTB calls"| node_contracts_protocol
node_runtime_wallet -->|"custody"| node_contracts_wallet
node_runtime_walrus -->|"skill refs"| node_contracts_skills
node_backend_agent -->|"executes"| node_backend_ptb
node_backend_ptb -->|"uses"| node_backend_sui
node_backend_ptb -->|"swaps"| node_backend_deepbook
node_backend_indexer -->|"persists"| node_backend_store
node_backend_indexer -->|"listens"| node_contracts_events
node_standalone_indexer -->|"streams"| node_indexer_listener
node_indexer_listener -->|"subscribes"| node_contracts_events
node_indexer_listener -->|"writes"| node_backend_store
node_explorer_hooks -->|"reads live"| node_explorer_sui
node_explorer_hooks -->|"reads history"| node_explorer_supabase
node_explorer_agent -->|"renders"| node_explorer_hooks
node_explorer_agent -->|"inspects"| node_contracts_protocol
node_explorer_agent -->|"shows"| node_contracts_wallet
node_explorer_agent -->|"shows"| node_contracts_skills
node_explorer_agent -->|"history"| node_explorer_supabase
node_public_home -->|"navigates"| node_public_mint
node_public_home -.->|"handoff"| node_explorer_agent

click node_contracts_protocol "https://github.com/anima-sui/anima-protocol/blob/main/contracts/sources/protocol.move"
click node_contracts_wallet "https://github.com/anima-sui/anima-protocol/blob/main/contracts/sources/wallet.move"
click node_contracts_skills "https://github.com/anima-sui/anima-protocol/blob/main/contracts/sources/skill_registry.move"
click node_contracts_events "https://github.com/anima-sui/anima-protocol/blob/main/contracts/sources/events.move"
click node_runtime_orchestrator "https://github.com/anima-sui/anima-protocol/blob/main/agent-runtime/src/orchestrator.py"
click node_runtime_predictor "https://github.com/anima-sui/anima-protocol/blob/main/agent-runtime/src/predictor.py"
click node_runtime_sui "https://github.com/anima-sui/anima-protocol/blob/main/agent-runtime/src/sui_client.py"
click node_runtime_walrus "https://github.com/anima-sui/anima-protocol/blob/main/agent-runtime/src/walrus_client.py"
click node_runtime_wallet "https://github.com/anima-sui/anima-protocol/blob/main/agent-runtime/wallet_management/wallet_agent.py"
click node_backend_agent "https://github.com/anima-sui/anima-protocol/blob/main/backend/src/agent/agent.controller.ts"
click node_backend_ptb "https://github.com/anima-sui/anima-protocol/blob/main/backend/src/ptb/ptb.service.ts"
click node_backend_sui "https://github.com/anima-sui/anima-protocol/blob/main/backend/src/sui/sui.service.ts"
click node_backend_deepbook "https://github.com/anima-sui/anima-protocol/blob/main/backend/src/deepbook/deepbook.service.ts"
click node_backend_indexer "https://github.com/anima-sui/anima-protocol/blob/main/backend/src/indexer/indexer.service.ts"
click node_backend_store "https://github.com/anima-sui/anima-protocol/blob/main/backend/src/events/store.ts"
click node_standalone_indexer "https://github.com/anima-sui/anima-protocol/blob/main/indexer/index.ts"
click node_indexer_listener "https://github.com/anima-sui/anima-protocol/blob/main/indexer/listener.ts"
click node_explorer_agent "https://github.com/anima-sui/anima-protocol/blob/main/explorer/app/agents/[id]/page.tsx"
click node_explorer_hooks "https://github.com/anima-sui/anima-protocol/blob/main/explorer/hooks/useAgent.ts"
click node_explorer_sui "https://github.com/anima-sui/anima-protocol/blob/main/explorer/lib/sui.ts"
click node_explorer_supabase "https://github.com/anima-sui/anima-protocol/blob/main/explorer/lib/supabase.ts"
click node_public_home "https://github.com/anima-sui/anima-protocol/blob/main/app/app/page.tsx"
click node_public_mint "https://github.com/anima-sui/anima-protocol/blob/main/app/app/mint/page.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_contracts_protocol,node_contracts_wallet,node_contracts_skills,node_contracts_events toneBlue
class node_runtime_orchestrator,node_runtime_predictor,node_runtime_sui,node_runtime_walrus,node_runtime_wallet toneAmber
class node_backend_agent,node_backend_ptb,node_backend_sui,node_backend_deepbook,node_backend_indexer,node_backend_store toneMint
class node_standalone_indexer,node_indexer_listener toneRose
class node_explorer_agent,node_explorer_hooks,node_explorer_sui,node_explorer_supabase toneIndigo
class node_public_home,node_public_mint toneTeal
```

## Components

### On-chain protocol

Sui Move contracts that define ANIMA state and enforcement

- [Protocol](https://github.com/anima-sui/anima-protocol/blob/main/contracts/sources/protocol.move): Move module · Core agent object, custody rules, and protocol enforcement · `contracts/sources/protocol.move`
- [Wallet](https://github.com/anima-sui/anima-protocol/blob/main/contracts/sources/wallet.move): Move module · Vault behavior and controlled asset movement · `contracts/sources/wallet.move`
- [Skill registry](https://github.com/anima-sui/anima-protocol/blob/main/contracts/sources/skill_registry.move): Move module · On-chain skill references mapped to off-chain blobs · `contracts/sources/skill_registry.move`
- [Events](https://github.com/anima-sui/anima-protocol/blob/main/contracts/sources/events.move): Move module · Protocol telemetry emitted for indexing and history · `contracts/sources/events.move`

### Agent runtime

Python autonomous execution and wallet management

- [Orchestrator](https://github.com/anima-sui/anima-protocol/blob/main/agent-runtime/src/orchestrator.py): Python control · Coordinates inspection, decisioning, and execution flow · `agent-runtime/src/orchestrator.py`
- [Predictor](https://github.com/anima-sui/anima-protocol/blob/main/agent-runtime/src/predictor.py): Python policy · Monitors state and decides whether the agent should act · `agent-runtime/src/predictor.py`
- [Sui client](https://github.com/anima-sui/anima-protocol/blob/main/agent-runtime/src/sui_client.py): Python chain client · Builds reads and transaction interactions against Sui · `agent-runtime/src/sui_client.py`
- [Walrus client](https://github.com/anima-sui/anima-protocol/blob/main/agent-runtime/src/walrus_client.py): Python blob client · Fetches skill and strategy config from Walrus · `agent-runtime/src/walrus_client.py`
- [Wallet mgmt](https://github.com/anima-sui/anima-protocol/blob/main/agent-runtime/wallet_management/wallet_agent.py): Python wallet flow · Operator hot-wallet and action construction helpers · `agent-runtime/wallet_management/wallet_agent.py`

### Backend API

NestJS service for PTB execution, Sui access, and DeepBook integration

- [Agent API](https://github.com/anima-sui/anima-protocol/blob/main/backend/src/agent/agent.controller.ts): NestJS controller · HTTP boundary for agent-related operations · `backend/src/agent/agent.controller.ts`
- [PTB service](https://github.com/anima-sui/anima-protocol/blob/main/backend/src/ptb/ptb.service.ts): NestJS executor · Constructs and executes Sui programmable transaction blocks · `backend/src/ptb/ptb.service.ts`
- [Sui service](https://github.com/anima-sui/anima-protocol/blob/main/backend/src/sui/sui.service.ts): NestJS chain · Shared Sui interaction layer for backend features · `backend/src/sui/sui.service.ts`
- [DeepBook](https://github.com/anima-sui/anima-protocol/blob/main/backend/src/deepbook/deepbook.service.ts): Swap integration · Swap routing and DeFi execution support · `backend/src/deepbook/deepbook.service.ts`
- [Indexer svc](https://github.com/anima-sui/anima-protocol/blob/main/backend/src/indexer/indexer.service.ts): NestJS indexer · Backend-side event ingestion and processing · `backend/src/indexer/indexer.service.ts`
- [Event store](https://github.com/anima-sui/anima-protocol/blob/main/backend/src/events/store.ts): Event persistence · Application event storage and translation layer · `backend/src/events/store.ts`

### Indexing

Event listeners and persistence paths for protocol activity

- [Indexer](https://github.com/anima-sui/anima-protocol/blob/main/indexer/index.ts): TS listener · Standalone Sui event listener for ANIMA activity · `indexer/index.ts`
- [Listener](https://github.com/anima-sui/anima-protocol/blob/main/indexer/listener.ts): TS stream · Consumes chain events and dispatches handlers · `indexer/listener.ts`

### Explorer console

Operational UI for inspecting agents and history

- [Agent page](https://github.com/anima-sui/anima-protocol/blob/main/explorer/app/agents/[id]/page.tsx): Next.js view · Agent detail surface for identity, wallet, skills, and actions · `explorer/app/agents/[id]/page.tsx`
- [Data hooks](https://github.com/anima-sui/anima-protocol/blob/main/explorer/hooks/useAgent.ts): React data · Loads live agent state, actions, and protocol stats · `explorer/hooks/useAgent.ts`
- [Explorer Sui](https://github.com/anima-sui/anima-protocol/blob/main/explorer/lib/sui.ts): Frontend chain client · Reads live agent and protocol state from Sui RPC · `explorer/lib/sui.ts`
- [Supabase](https://github.com/anima-sui/anima-protocol/blob/main/explorer/lib/supabase.ts): Postgres store · Queryable history and indexed activity data · `explorer/lib/supabase.ts`

### Public app

Marketing and minting frontend

- [Landing app](https://github.com/anima-sui/anima-protocol/blob/main/app/app/page.tsx): Next.js frontend · Public marketing and protocol entry experience · `app/app/page.tsx`
- [Mint page](https://github.com/anima-sui/anima-protocol/blob/main/app/app/mint/page.tsx): Next.js view · Minting flow for the public-facing app · `app/app/mint/page.tsx`

## Connections

- Orchestrator → Predictor: decides · Chooses when the agent should act
- Orchestrator → Sui client: reads chain · Inspects agent state and protocol data
- Orchestrator → Walrus client: loads config · Fetches strategy and skill payloads
- Orchestrator → Wallet mgmt: builds action · Prepares operator-signed execution flow
- Wallet mgmt → Protocol: PTB calls · Invokes contract-enforced agent actions
- Wallet mgmt → Wallet: custody · Moves assets through sovereign vault rules
- Walrus client → Skill registry: skill refs · Resolves on-chain skill IDs to blob-backed config
- Agent API → PTB service: executes · Routes requests into PTB construction and submission
- PTB service → Sui service: uses · Relies on shared Sui access and transaction plumbing
- PTB service → DeepBook: swaps · Can route execution into DeepBook swap logic
- Indexer svc → Event store: persists · Stores translated event and activity data
- Indexer svc → Events: listens · Consumes ANIMA protocol event stream
- Indexer → Listener: streams · Event listener processes protocol events
- Listener → Events: subscribes · Tracks emitted on-chain telemetry
- Listener → Event store: writes · Feeds history and analytics persistence
- Data hooks → Explorer Sui: reads live · Pulls current agent and protocol state
- Data hooks → Supabase: reads history · Fetches indexed actions and records
- Agent page → Data hooks: renders · Composes agent detail panels from hooks
- Agent page → Protocol: inspects · Shows identity and vault state anchored on-chain
- Agent page → Wallet: shows · Surfaces wallet and vault status
- Agent page → Skill registry: shows · Displays the registered skill set
- Agent page → Supabase: history · Displays action feed and indexed past behavior
- Landing app → Mint page: navigates · Public entry leads into minting flow
- Landing app → Agent page: handoff · Users can move from public entry to operational console