create-mantle-agent

Scaffold a non-custodial Mantle AI agent with Tencent Hunyuan explanations, deterministic transaction auditing, pre-sign simulation, and on-chain proof.

npx create-mantle-agent@latest my-agent --yes

Requires Node.js 23 or newer.

Generated Agent — Feature List

| # | Feature | Description | |---|---------|-------------| | 1 | Non-custodial wallet | No server-side private key. All transactions are signed by the user's MetaMask. The agent returns pending_signature objects; the browser submits them. | | 2 | AI chat | Streaming chat endpoint (POST /api/chat) backed by Amazon Bedrock (Claude Haiku 4.5). Memory is persisted via LibSQL so conversations resume across page reloads. | | 3 | Deterministic audit | POST /api/audit runs 9+ rule-based checks (chain ID, address format, allowance scope, slippage, deadline, gas balance, mainnet confirmation, …) and produces a keccak256 report hash for on-chain proof. | | 4 | Pre-sign simulation | Each audit call simultaneously simulates the transaction against the Mantle RPC and surfaces gas estimates or revert reasons before the user signs. | | 5 | Tencent Hunyuan AI explanation | After deterministic checks pass, the audit pipeline calls Tencent Hunyuan to generate a human-readable explanation and remediation recommendations. | | 6 | DeFi — Agni Finance swaps | 3-step swap flow (quote → approve → execute) on the Agni Finance Uniswap V3 fork. Supports direct pools and multi-hop routing via WMNT. Auto-detects the best fee tier (100 / 500 / 2500 / 10000 bps). | | 7 | Portfolio analytics | Read wallet MNT/WMNT balances, any ERC-20 token balance, and all active ERC-20 allowances. | | 8 | Risk evaluation | Pre-execution risk scoring (slippage, liquidity depth, allowance scope) integrated into the agent tool chain. | | 9 | Address registry | Bundled verified-address registry for Mantle mainnet and Sepolia. Resolves token symbols and contract names; flags unverified targets. | | 10 | Smart contract tools | Contract architecture templates, access-control validation, deployment checklists, and deployment-package preparation — all via agent tools. | | 11 | Historical data indexer | Query on-chain event history and protocol analytics via pluggable indexer backends. | | 12 | RPC debugger | Decodes RPC errors using a curated error-signature map and troubleshooting playbook. | | 13 | Counter demo | On-chain Counter contract tools (read state / increment / incrementBy / reset) deployed on Mantle Sepolia — useful as a write-operation tutorial. | | 14 | Mastra skills | 10 bundled skills (network primer, DeFi operator, portfolio analyst, risk evaluator, tx simulator, readonly debugger, data indexer, address registry, contract developer, contract deployer) provide structured domain knowledge injected into the agent at runtime. | | 15 | Observability | Pino structured logging + Mastra OpenTelemetry traces with a SensitiveDataFilter that redacts keys/tokens before export. |

System Architecture

graph TD
    subgraph Browser["Browser (Next.js client)"]
        UI[Chat UI / AuditWorkbench]
        MM[MetaMask]
        TxCard[TxSignCard]
    end

    subgraph Server["Next.js API Routes (Node.js)"]
        ChatRoute[POST /api/chat]
        AuditRoute[POST /api/audit]
        HealthRoute[GET /api/health]
    end

    subgraph Mastra["Mastra Agent Runtime"]
        Agent[mantleAgent\nClaude Haiku 4.5 via Bedrock]
        Memory[Memory\nLibSQL]
        Skills[10× Mantle Skills]
        Tools[25+ Mastra Tools]
    end

    subgraph AuditPipeline["Audit Pipeline"]
        DetChecks[Deterministic Checks\n9 rule-based checks]
        Simulation[Simulation\nMantle RPC eth_call]
        Hunyuan[Tencent Hunyuan\nAI Explanation]
        ReportHash[keccak256 Report Hash]
    end

    subgraph Blockchain["Mantle Network"]
        Mainnet[Mantle Mainnet\nChain ID 5000]
        Sepolia[Mantle Sepolia\nChain ID 5003]
        AgniFinance[Agni Finance\nSwapRouter / QuoterV2]
    end

    UI -->|stream messages| ChatRoute
    ChatRoute --> Agent
    Agent --> Memory
    Agent --> Skills
    Agent --> Tools

    UI -->|unsigned tx| AuditRoute
    AuditRoute --> DetChecks
    AuditRoute --> Simulation
    AuditRoute --> Hunyuan
    DetChecks --> ReportHash

    Tools -->|read RPC| Mainnet
    Tools -->|read RPC| Sepolia
    Tools -->|swap quote / execute| AgniFinance
    Simulation -->|eth_call| Sepolia
    Simulation -->|eth_call| Mainnet

    Agent -->|pending_signature| ChatRoute
    ChatRoute -->|pending_signature| UI
    UI --> TxCard
    TxCard -->|sign| MM
    MM -->|signed tx| UI
    UI -->|broadcast| Mainnet
    UI -->|broadcast| Sepolia

Transaction Signing Sequence

sequenceDiagram
    participant User
    participant UI as Browser UI
    participant Chat as POST /api/chat
    participant Agent as mantleAgent
    participant Tool as Mastra Tool
    participant MM as MetaMask
    participant RPC as Mantle RPC

    User->>UI: Type intent (e.g. "Swap 0.01 WMNT → USDT")
    UI->>Chat: POST { messages, userWalletAddress }
    Chat->>Agent: handleChatStream (Mastra v6)

    Note over Agent: Step 1 — Quote
    Agent->>Tool: agni-swap-quote(tokenIn, tokenOut, amountIn)
    Tool->>RPC: simulateContract(QuoterV2.quoteExactInputSingle)
    RPC-->>Tool: quotedAmountOut, feeTier
    Tool-->>Agent: { quotedAmountOut, amountOutMinimum, feeTier }
    Agent-->>UI: Stream: "Estimated output: X USDT"

    Note over Agent: Step 2 — Approve
    Agent->>Tool: agni-swap-approve(tokenIn, amountIn, fromAddress)
    Tool->>RPC: estimateGas (approve calldata)
    RPC-->>Tool: gasEstimate
    Tool-->>Agent: pending_signature { unsignedTx }
    Agent-->>UI: Stream: pending_signature (approve)
    UI->>MM: eth_sendTransaction(unsignedTx)
    MM-->>UI: txHash (approve)
    UI->>Chat: Follow-up message: txHash = 0xABC…
    Chat->>Agent: wait-for-tx-receipt(0xABC…)
    Agent->>RPC: eth_getTransactionReceipt
    RPC-->>Agent: receipt { status: success }
    Agent-->>UI: "Approval confirmed"

    Note over Agent: Step 3 — Execute Swap
    Agent->>Tool: agni-swap-execute(tokenIn, tokenOut, amountIn, amountOutMinimum, fromAddress)
    Tool-->>Agent: pending_signature { unsignedTx }
    Agent-->>UI: Stream: pending_signature (swap)
    UI->>MM: eth_sendTransaction(unsignedTx)
    MM-->>UI: txHash (swap)
    UI->>Chat: Follow-up message: txHash = 0xDEF…
    Chat->>Agent: wait-for-tx-receipt(0xDEF…)
    Agent->>RPC: eth_getTransactionReceipt
    RPC-->>Agent: receipt { status: success }
    Agent-->>UI: "Swap confirmed. Explorer: explorer.mantle.xyz/tx/0xDEF…"

Audit Pipeline Sequence

sequenceDiagram
    participant UI as Browser UI
    participant Audit as POST /api/audit
    participant Det as Deterministic Checks
    participant Sim as Simulation (RPC)
    participant HY as Tencent Hunyuan

    UI->>Audit: POST { network, from, transaction, context }
    Note over Audit: Parallel execution
    par
        Audit->>Det: runDeterministicChecks()
        Det-->>Audit: checks[], verdict (pass/warn/block)
    and
        Audit->>Sim: eth_call / eth_estimateGas
        Sim-->>Audit: SimulationEvidence { status, gasEstimate }
    and
        Audit->>Sim: eth_getBalance (MNT gas check)
        Sim-->>Audit: nativeBalanceWei
    end

    Audit->>HY: explain({ request, verdict, checks, simulation })
    HY-->>Audit: { explanation, recommendations }

    Audit-->>UI: AuditReport { verdict, checks, simulation,\n aiExplanation, reportHash, decodedCall }

Deterministic Audit Checks

| Check ID | Label | Block condition | Warn condition | |----------|-------|-----------------|----------------| | chain | Chain and RPC | RPC chain ID ≠ expected | Chain ID not confirmed | | address-format | Address format | Zero address or invalid format | — | | registry | Verified target registry | — | Target not in bundled registry | | calldata | Calldata decode | — | Unknown function selector | | allowance | Approval scope | Unlimited (MAX_UINT256) ERC-20 approval | Finite non-zero approval | | slippage | Slippage | > 100 bps | Not supplied or 50–100 bps | | deadline | Deadline | Expired | Not supplied | | recipient | Recipient | — | Output recipient ≠ connected wallet | | gas-balance | MNT gas balance | Balance < 0.00001 MNT | Balance not confirmed | | mainnet-confirmation | Mainnet confirmation (mainnet only) | No quoteId or mainnetConfirmed !== true | — |

Tech Stack

Frontend

| Package | Version | Role | |---------|---------|------| | Next.js | 16.2 | App Router, RSC, API routes | | React | 19 | UI framework | | Tailwind CSS | v4 | Utility-first styling | | shadcn/ui (Radix UI) | latest | Accessible component primitives | | @ai-sdk/react | ^3 | useChat hook for streaming | | @xyflow/react | ^12 | Node graph visualization | | motion | ^12 | Animation | | viem | ^2 | Ethereum type-safe client (browser) | | streamdown | ^2 | Markdown streaming renderer with CJK/code/math support |

Agent & AI

| Package | Version | Role | |---------|---------|------| | mastra / @mastra/core | ^1.5 / ^1.24 | Agent orchestration, tool registry, skills | | @mastra/ai-sdk | ^1.3 | AI SDK ↔ Mastra bridge (handleChatStream) | | @mastra/memory | ^1.15 | Persistent conversation memory | | @mastra/observability | ^1.9 | OpenTelemetry traces + sensitive data filter | | @mastra/loggers | ^1.1 | Pino-based structured logging | | ai (Vercel AI SDK) | ^6 | Streaming protocol, createUIMessageStreamResponse | | @ai-sdk/amazon-bedrock | ^4 | Amazon Bedrock LLM provider | | @aws-sdk/credential-providers | ^3 | AWS credential chain | | Tencent Hunyuan API | — | Audit AI explanation (custom provider class) |

Blockchain & Cryptography

| Package | Version | Role | |---------|---------|------| | viem | ^2.49 | ABI encoding/decoding, RPC clients, keccak256 | | zod | ^4 | Request schema validation |

Storage & Runtime

| Package | Version | Role | |---------|---------|------| | @mastra/libsql | ^1.8 | LibSQL (SQLite / Turso) for agent memory & traces | | @mastra/duckdb | ^1.1 | DuckDB adapter (analytics queries) | | Node.js | ≥ 23 | Runtime (ESM, native test runner) |

Developer Tooling

| Tool | Role | |------|------| | TypeScript 5 | Type safety | | Biome 2 | Linter + formatter | | tsx | TypeScript execution for scripts & tests | | ESLint 9 + eslint-config-next | Next.js lint rules |

Project Structure (generated)

my-agent/
├── src/
│   ├── app/
│   │   ├── api/
│   │   │   ├── chat/route.ts       # Streaming AI chat endpoint
│   │   │   ├── audit/route.ts      # Transaction audit endpoint
│   │   │   └── health/route.ts     # Health check
│   │   └── page.tsx                # Chat UI entry point
│   ├── components/
│   │   ├── mantle/                 # Mantle-specific UI components
│   │   │   ├── AuditWorkbench.tsx  # Audit form + results display
│   │   │   ├── TxSignCard.tsx      # Unsigned tx → MetaMask signing card
│   │   │   ├── MantleTopBar.tsx    # Header with wallet badge
│   │   │   └── ...
│   │   ├── ai-elements/            # Generic AI UI primitives
│   │   └── ui/                     # shadcn/ui components
│   ├── lib/
│   │   ├── audit/
│   │   │   ├── core.ts             # Deterministic checks + report assembly
│   │   │   ├── simulation.ts       # RPC simulation helpers
│   │   │   ├── hunyuan.ts          # Tencent Hunyuan provider
│   │   │   ├── config.ts           # Network configs + verified address sets
│   │   │   └── types.ts            # AuditRequest / AuditReport types
│   │   ├── viem-clients.ts         # Public viem clients per network
│   │   └── client-wallet.ts        # Client-side MetaMask helpers
│   └── mastra/
│       ├── agents/mantle-agent.ts  # mantleAgent definition + system prompt
│       ├── tools/                  # 25+ Mastra tools
│       ├── skills/                 # 10 bundled Mantle skills
│       ├── models/index.ts         # Amazon Bedrock + Gemini model config
│       ├── workspace.ts            # Mastra workspace (skills loader)
│       └── index.ts                # Mastra instance (storage, observability)
├── scripts/
│   └── benchmark.ts                # Audit pipeline benchmark
├── .env.example                    # Required environment variables
└── package.json

Environment Variables

# AWS credentials for Amazon Bedrock (Claude Haiku 4.5)
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_REGION=ap-northeast-1          # Bedrock region

# Tencent Cloud — for audit AI explanations (optional; deterministic checks work without it)
TENCENTCLOUD_SECRET_ID=
TENCENTCLOUD_SECRET_KEY=

# LibSQL / Turso — defaults to local SQLite (file:./mastra.db)
LIBSQL_URL=
LIBSQL_AUTH_TOKEN=

# Mastra Cloud tracing (optional)
MASTRA_CLOUD_ACCESS_TOKEN=