Skip to content

README.md

Latest commit

 

History

History
160 lines (122 loc) · 6.58 KB

README.md

File metadata and controls

160 lines (122 loc) · 6.58 KB
Raw

SuiAgentWallet

AI Agent wallet powered by Sui blockchain, featuring zkLogin passwordless auth, Deepbook Dex trading, and on-chain delegation-based fund management.

SuiAgentWallet Screenshot

SuiAgentWallet Screenshot

SuiAgentWallet Screenshot

Sui Core Features

  • ZkLogin Agent Wallet — Google login, zero private key management
  • PTB Execution — Backend tools return PTB → frontend buildTransactionFromPtb builds → zkLogin signing → on-chain submission
  • Delegation List — Filtered by current wallet address, live on-chain status refresh

Frontend

Tech stack: React 19 + Vite + Zustand + React Query + i18n (zh-CN / en-US)

Sidebar Navigation

Module Route Function
AI Assistant /home Multi-turn chat + tool execution + streaming
Sui Wallet /wallet Balance, send/receive, transaction history, PTB approval
Delegations /delegations On-chain delegation management (create, query, refresh status)
MCP /mcp MCP protocol server configuration
Skills /skills Agent Skills management
Webhooks /webhooks Webhook registration
Channels /channels Multi-channel notifications
Settings /settings Application settings
Admin /admin Admin panel

Backend

Tech stack: FastAPI + SQLModel + APScheduler + 80+ tools + multi-model routing

Sui Tools (tools/sui/)

Tool Purpose
create_delegation Build PTB to create delegation (auto-discovers wallet address/coin/network)
list_delegations List saved delegation records + on-chain status refresh
check_delegation Query on-chain delegation state (balance, allowance, expiry)
revoke_delegation Revoke delegation
place_grid_orders Place grid limit orders on Deepbook (auto-withdraw settled funds)
cancel_order Cancel order + withdraw returned funds
get_open_orders Query BM for open/filled orders
get_pool_info Query Deepbook pool info
withdraw_settled Withdraw funds from BM
swap Direct Deepbook token swap
trade_history On-chain TradeRecord query
guardian PTB risk assessment

Delegation Contract (contracts/delegation/)

Delegation<T> shared object with physically locked funds.

Write Methods

Method Caller Description
create<T>(agent, coin, max_amount, expires_at_ms, clock, ctx) owner Create delegation (target restricted to owner)
create_with_targets<T>(agent, coin, max_amount, expires_at_ms, allowed_targets, clock, ctx) owner Create delegation with target whitelist
spend<T>(delegation, amount, target, clock, ctx) → Coin<T> agent Spend from delegation, atomic within PTB. Enforces: agent identity, not revoked, not expired, target in whitelist, cumulative ≤ cap
spend_and_transfer<T>(delegation, amount, target, clock, ctx) agent spend + auto-transfer to sender
deposit<T>(delegation, coin) owner Add funds (does not change max_amount)
extend_cap<T>(delegation, new_max, ctx) owner Raise max_amount
revoke<T>(delegation, ctx) → Coin<T> owner Revoke delegation, return all balance

Read-Only Methods

Method Description
remaining_balance<T>(delegation) → u64 Current balance
remaining_allowance<T>(delegation) → u64 Remaining allowance (max_amount - spent)
is_active<T>(delegation, clock) → bool Active check (not revoked + not expired)
owner<T>(delegation) → address Owner address
agent<T>(delegation) → address Agent address

Events

Event Trigger
DelegationCreated Delegation created
SpendExecuted Agent spent successfully
DelegationRevoked Delegation revoked
DelegationToppedUp Funds deposited

Agent Context

Each chat request includes sui_address + sui_network from the frontend → stored in session metadata → injected into context.extra. Tools read these automatically — the agent never needs to ask for address, network, or coin IDs.

Data Flow

User input → ChatView → runChatStream (with sui_address + network)
  → POST /chat/stream → Agent (QueryEngine)
    → Tool call (create_delegation / place_grid_orders / ...)
    → PTB instructions { instructions: [...] }
  ← Server-Sent Events (SSE)
→ SuiPtbToolCard auto-execute / PTBApprovalDialog manual confirm
  → resolveWalletCoins (coin discovery fallback)
  → buildTransactionFromPtb (PTB → Transaction)
  → zkLogin signing → executeTransactionBlock
  → Parse events → saveOrderRecords / saveDelegationToDb
  → notifyAgentOfPtbResult → Continue conversation

Environment Configuration

Backend .env

Variable Description Required
SUIAGENT_ZKLOGIN__ENABLED Enable zkLogin (true / false) Yes
SUIAGENT_ZKLOGIN__GOOGLE_CLIENT_ID Google OAuth Client ID Yes
SUIAGENT_ZKLOGIN__SALT_MASTER_SEED 64-char hex salt seed Yes
SUIAGENT_ZKLOGIN__SESSION_TOKEN_SECRET 64-char hex session secret Yes
SUIAGENT_ZKLOGIN__PROVER_URL zkLogin prover URL (default: Mysten dev) Optional
SUIAGENT_ZKLOGIN__PROVER_URL_TESTNET Per-network override (testnet) Optional
SUIAGENT_ZKLOGIN__PROVER_URL_MAINNET Per-network override (mainnet) Optional
SUIAGENT_ZKLOGIN__PROVER_URL_DEVNET Per-network override (devnet) Optional
SUIAGENT_SUI__DELEGATION_PACKAGE_ID Delegation contract package ID Yes
DEEPSEEK_API_KEY DeepSeek API Key Optional
DATABASE_URL PostgreSQL URL (defaults to SQLite) Optional

Full example: backend/.env.example.

Frontend .env

Variable Description Required
VITE_API_BASE_URL Backend API URL Yes
VITE_GOOGLE_CLIENT_ID Google OAuth Client ID (same as backend) Yes
VITE_SUI_RPC_TESTNET Sui testnet RPC (optional, defaults to public fullnode) Optional
VITE_SUI_RPC_MAINNET Sui mainnet RPC (recommend Shinami) Optional

Full example: frontend/.env.example.

Quick Start

# Backend
cd backend && uv sync && uv run python -m suiagent

# Frontend
cd frontend && npm install && npm run dev

License

Apache License 2.0 — see LICENSE.