How anima-sui/anima-protocol works
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: page.tsx Agent page · orchestrator.py Orchestrator · wallet_agent.py Wallet mgmt · ptb.service.ts PTB service
Components 23
On-chain protocol
Sui Move contracts that define ANIMA state and enforcement
- Protocol · Core agent object, custody rules, and protocol enforcement
contracts/sources/protocol.move - Wallet · Vault behavior and controlled asset movement
contracts/sources/wallet.move - Skill registry · On-chain skill references mapped to off-chain blobs
contracts/sources/skill_registry.move - Events · Protocol telemetry emitted for indexing and history
contracts/sources/events.move
Agent runtime
Python autonomous execution and wallet management
- Orchestrator · Coordinates inspection, decisioning, and execution flow
agent-runtime/src/orchestrator.py - Predictor · Monitors state and decides whether the agent should act
agent-runtime/src/predictor.py - Sui client · Builds reads and transaction interactions against Sui
agent-runtime/src/sui_client.py - Walrus client · Fetches skill and strategy config from Walrus
agent-runtime/src/walrus_client.py - Wallet mgmt · 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 · HTTP boundary for agent-related operations
backend/src/agent/agent.controller.ts - PTB service · Constructs and executes Sui programmable transaction blocks
backend/src/ptb/ptb.service.ts - Sui service · Shared Sui interaction layer for backend features
backend/src/sui/sui.service.ts - DeepBook · Swap routing and DeFi execution support
backend/src/deepbook/deepbook.service.ts - Indexer svc · Backend-side event ingestion and processing
backend/src/indexer/indexer.service.ts - Event store · Application event storage and translation layer
backend/src/events/store.ts
Indexing
Event listeners and persistence paths for protocol activity
Explorer console
Operational UI for inspecting agents and history
- Agent page · Agent detail surface for identity, wallet, skills, and actions
explorer/app/agents/[id]/page.tsx - Data hooks · Loads live agent state, actions, and protocol stats
explorer/hooks/useAgent.ts - Explorer Sui · Reads live agent and protocol state from Sui RPC
explorer/lib/sui.ts - Supabase · Queryable history and indexed activity data
explorer/lib/supabase.ts
Public app
Marketing and minting frontend
- Landing app · Public marketing and protocol entry experience
app/app/page.tsx - Mint page · Minting flow for the public-facing app
app/app/mint/page.tsx
Connections 24
- 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