MNTShield

Mantle-native smart contract security. Input an address, not your source code.

MNTShield is a web-based smart contract security tool for the Mantle L2 network. Enter a deployed contract address — MNTShield fetches on-chain context via RPC, scans bytecode opcodes deterministically for Mantle-specific risk patterns, then runs a Grounded AI engine that can only reason about what the opcode scanner already confirmed.

No source code is ever submitted. No data is stored. Analysis is stateless.

---

Features

• Address-only input — no source code paste, no file upload, no accounts
• On-chain context fetch — bytecode, ABI, name, deployer, balance, recent txs via Mantle RPC + Explorer API
• Opcode scanner — deterministic bytecode analysis for Mantle-specific risks (M001–M005)
• Grounded AI — LLM reasons only within confirmed opcode findings; validateFindings() prevents hallucinations
• Offline fallback — deterministic rule descriptions when LLM is unavailable
• Audit score — max(0, 100 - (critical×25 + high×10 + medium×5 + low×2))
• On-chain commitment — keccak256(score || salt || contractAddress) stored on Mantle Sepolia via commitment scheme (score never public)
• Gas intelligence — dual-fee (L1 + L2) cost estimates per function from ABI

---

Tech Stack

Layer	Technology
Frontend	Next.js 14 App Router, TypeScript, Tailwind CSS
Wallet	wagmi v2 + viem
Charts	Recharts
Backend	Hono on Cloudflare Workers
RPC Client	viem — Mantle RPC
Explorer API	Mantle Explorer (Blockscout-compatible)
LLM	Anthropic Claude API + offline fallback
Smart Contract	Solidity 0.8.24, Foundry — Mantle Sepolia
Deployment	Cloudflare Workers + Vercel + Mantle Sepolia

---

---

Quick Start

git clone [email protected]:hackonteam/mntshield.git
cd mntshield

Backend

cd backend
npm install
npm run dev

Backend starts at http://localhost:8787. Health check: curl http://localhost:8787/health.

Set MNTS_MOCK=1 to run with offline fallback (no API key needed):

MNTS_MOCK=1 npm run dev

Frontend

cd frontend
npm install
NEXT_PUBLIC_API_URL=http://localhost:8787 NEXT_PUBLIC_COMMITMENT_ADDRESS=0xEFf5284031D5bA06AA2E5b77e27F97934dC12708 npm run dev

Frontend starts at http://localhost:3000.

Contracts

cd contracts
forge build
forge test

---

Project Structure

mntshield/
├── contracts/                       # Solidity + Foundry
│   ├── src/MNTShieldCommitment.sol  # On-chain commitment registry
│   ├── test/                        # Foundry tests (9/9 pass)
│   ├── script/Deploy.s.sol          # Deploy script
│   └── deployments/                 # Deployment artifacts
├── backend/                         # Cloudflare Worker (Hono)
│   ├── src/
│   │   ├── index.ts                 # API routes: /health, /api/analyze
│   │   ├── types.ts                 # Shared TypeScript interfaces
│   │   ├── fetcher/onchain.ts       # RPC + Explorer fetch
│   │   ├── analyzer/
│   │   │   ├── opcodes.ts           # Deterministic opcode scanner
│   │   │   └── rules.ts             # 5 Mantle rule definitions
│   │   ├── llm/
│   │   │   ├── auditor.ts           # Grounded AI engine
│   │   │   ├── validator.ts         # Hallucination checker
│   │   │   └── fallback.ts          # Offline fallback
│   │   ├── gas/model.ts             # Dual-fee gas estimates
│   │   └── __tests__/               # Vitest tests (17/17 pass)
│   └── wrangler.toml
├── frontend/                        # Next.js 14 App Router
│   ├── app/                         # Pages + layout
│   ├── components/                  # React components
│   ├── hooks/                       # useAudit, useUrlState
│   └── lib/                         # API client, wagmi, commitment crypto
├── docs/                            # Documentation
│   ├── SPEC.md
│   ├── TECHNICAL_DESIGN.md
│   ├── UI_UX_PRINCIPAL.md
│   └── COMMITMENT_DELTA.md
├── LICENSE                          # Apache 2.0
└── README.md

---

Opcode Rules

Rule ID	Opcode(s)	Severity	Risk
M001	CALLVALUE (0x34)	High	Native token is MNT, not ETH
M002	GAS (0x5A)	Critical	L1 calldata fee unaccounted
M003	TIMESTAMP (0x42), NUMBER (0x43)	High	Sequencer-controlled time
M004	Cross-chain ABI patterns	Medium	7-day challenge window
M005	DELEGATECALL (0xF4)	Medium	Storage layout risk

---

On-Chain Commitment Scheme

Score is never stored on-chain. Only keccak256(score || salt || contractAddress) is committed to MNTShieldCommitment.sol on Mantle Sepolia. The auditor keeps the (score, salt) pair in a proof package — sharing it proves the score to anyone via verifyReveal().

---

Tests

# Backend (17 tests)
cd backend && npm test

# Contracts (9 tests)
cd contracts && forge test

---

Deployment

Contract

cd contracts
forge script script/Deploy.s.sol \
  --rpc-url https://rpc.sepolia.mantle.xyz \
  --broadcast --verify \
  --private-key $PRIVATE_KEY

Backend

cd backend
npm run deploy
npx wrangler secret put ANTHROPIC_API_KEY

Frontend

cd frontend
npx vercel --prod

Vercel env vars:

• NEXT_PUBLIC_API_URL — production backend URL
• NEXT_PUBLIC_COMMITMENT_ADDRESS — deployed contract address

---

Environment Variables

Backend (backend/.dev.vars)

ANTHROPIC_API_KEY=sk-ant-...
MNTS_MOCK=0

Frontend (frontend/.env.local)

NEXT_PUBLIC_API_URL=http://localhost:8787
NEXT_PUBLIC_COMMITMENT_ADDRESS=0xEFf5284031D5bA06AA2E5b77e27F97934dC12708

---

Authors

MNTShield is built by HackOn Team:

• Bernie — Architecture, Grounded AI engine, opcode scanner, backend API
• Davy — Smart contract development, deployment, testing
• Vu — Frontend components, UI/UX, state management
• Ngoc — Documentation, demo, devops

---

License

Apache 2.0. See LICENSE.

---

Hackathon

Built for Mantle Turing Test Hackathon 2026 — Track 05: AI DevTools. Tag: #MantleAIHackathon