Mantle Guard

**MantleGuard** - Transaction Simulation & Security Analysis SDK

---

## Tagline
*Know before you sign. Simulate, analyze, and protect every transaction on Mantle.*

---

## Project Description

MantleGuard is a production-grade transaction simulation and security analysis SDK built specifically for Mantle Network. It empowers wallets, dApps, and trading bots to show users exactly what will happen before they sign a transaction.

### The Problem

When users interact with DeFi protocols, they face several risks:

1. **Blind Signing**: Users see "Confirm transaction to 0xabc..." without knowing the outcome
2. **Approval Exploits**: Malicious sites request unlimited token approvals
3. **Phishing Contracts**: Fake interfaces that drain wallets
4. **Gas Surprises**: Transactions fail or cost 10x more than expected

### Our Solution

MantleGuard provides complete transaction transparency:

```
Before signing:
+----------------------------------------------------------------+
|  Transaction Analysis                                           |
|                                                                 |
|  Simulation: SUCCESS                                            |
|  Risk Level: LOW                                                |
|  Gas Cost: 0.0012 MNT                                           |
|                                                                 |
|  Token Changes:                                                 |
|  - Send: 10 MNT                                                 |
|  - Receive: 24.5 USDC                                           |
|                                                                 |
|  Contract: Merchant Moe Router (Verified)                       |
|                                                                 |
|  [Approve Transaction]  [Reject]                                |
+----------------------------------------------------------------+
```

---

## Key Features

### 1. Real Transaction Simulation
- Uses `eth_call` with state overrides
- No mocks - actual EVM execution
- Returns success/failure, logs, gas used

### 2. Accurate Gas Estimation
- `eth_estimateGas` with buffer calculations
- Real-time gas price recommendations
- Cost predictions in MNT

### 3. Comprehensive Security Scanning
- Known drainer address detection
- Unlimited approval warnings
- Unverified contract alerts
- Phishing pattern recognition

### 4. Token Impact Analysis
- Parse ERC-20, ERC-721, ERC-1155 events
- Calculate balance changes
- Identify approvals and their risks

### 5. Contract Verification
- Explorer API integration
- Source code availability check
- Known protocol identification

---

## Technical Architecture

```
+------------------------------------------------------------------+
|                          MANTLEGUARD                              |
+------------------------------------------------------------------+
|  SDK Interface: MantleGuard Class                                 |
|  - analyzeTransaction()                                           |
|  - simulate()                                                     |
|  - estimateGas()                                                  |
|  - scanSecurity()                                                 |
+------------------------------------------------------------------+
|  Core Modules:                                                    |
|  +------------------+  +------------------+  +------------------+ |
|  | EthCallSimulator |  | SecurityScanner  |  | TokenImpact      | |
|  | - simulate()     |  | - scan()         |  | Analyzer         | |
|  | - trace()        |  | - detectDrainer  |  | - parseEvents()  | |
|  +------------------+  +------------------+  +------------------+ |
|  +------------------+  +------------------+                       |
|  | GasEstimator     |  | CallDataDecoder  |                       |
|  | - estimate()     |  | - decode()       |                       |
|  | - getGasPrice()  |  | - parseSig()     |                       |
|  +------------------+  +------------------+                       |
+------------------------------------------------------------------+
|  RPC Layer: eth_call | eth_estimateGas | debug_traceCall         |
+------------------------------------------------------------------+
```

---

## Deployed Contracts (Mantle Sepolia)

| Contract | Address | Purpose |
|----------|---------|---------|
| Multicall3 | `0x9BB5CFE7cDFF4ccC535A944B2b3Ff278b8365b0A` | Batch RPC calls |
| SimulationHelper | `0x1274fBab8F6c9a582ad8eE92B899E6C9aD781118` | Simulation utilities |

---

## SDK Usage

### Installation

```bash
npm install @mantle-guard/sdk
```

### Basic Usage

```typescript
import { MantleGuard } from '@mantle-guard/sdk';

const guard = new MantleGuard({
  rpcUrl: 'https://rpc.sepolia.mantle.xyz',
  chainId: 5003,
});

// Analyze a transaction before signing
const analysis = await guard.analyzeTransaction({
  from: '0xUser...',
  to: '0xContract...',
  data: '0xCalldata...',
  value: 0n,
});

console.log(analysis);
// {
//   simulation: { success: true, gasUsed: 150000n, ... },
//   security: { overallRisk: 'LOW', warnings: [], isSafe: true },
//   gas: { estimatedCostMNT: '0.0018', ... },
//   impacts: { transfers: [...], balanceChanges: [...] }
// }
```

### Wallet Integration

```typescript
// Before showing transaction confirmation
async function analyzeBeforeSign(tx: Transaction) {
  const analysis = await guard.analyzeTransaction(tx);

  if (analysis.security.overallRisk === 'CRITICAL') {
    showBlockedWarning(analysis.security.warnings);
    return false;
  }

  showTransactionPreview({
    gasEstimate: analysis.gas.estimatedCostMNT,
    tokenChanges: analysis.impacts.balanceChanges,
    riskLevel: analysis.security.overallRisk,
  });

  return true;
}
```

---

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/simulate` | Basic simulation |
| POST | `/simulate/full` | Full analysis with security |
| POST | `/simulate/gas` | Gas estimation only |
| POST | `/analyze/risk` | Quick security check |
| POST | `/analyze/decode` | Decode calldata |
| GET | `/analyze/contract/:addr` | Contract verification |
| GET | `/analyze/allowance` | Check token allowance |
| GET | `/analyze/gas-price` | Gas price recommendations |

---

## Security Threat Detection

| Threat | Detection Method | Risk Level |
|--------|-----------------|------------|
| Known Drainer | Address blacklist (ScamSniffer data) | CRITICAL |
| Phishing Contract | Community reports database | CRITICAL |
| Unlimited Approval | Approval amount check | HIGH |
| Unverified Contract | Explorer API verification | MEDIUM |
| Suspicious Patterns | Bytecode analysis | HIGH |
| Honeypot Tokens | Transfer simulation | HIGH |

### Known Drainers Database

```typescript
const KNOWN_DRAINERS = [
  '0x0000db5c8b030ae20308ac975898e09741e70000', // Pink Drainer
  '0x000000000000cd17e94e6f43f9cc7a7fc91e8e00', // Inferno Drainer
  '0x00000000000006b794fb6dc3b88f44abb000000', // Angel Drainer
  '0x0000000000a39bb272e79075ade125fd152bc34', // Acedrainer
];
```

---

## Technology Stack

| Layer | Technology |
|-------|------------|
| SDK | TypeScript, viem |
| Build | tsup, ESM/CJS dual export |
| API | Hono (Bun/Node compatible) |
| Contracts | Solidity 0.8.24, Hardhat |
| RPC | Mantle Sepolia/Mainnet |

---

## Risk Level Scoring

| Level | Score | Action |
|-------|-------|--------|
| LOW | 0-25 | Safe to proceed |
| MEDIUM | 26-50 | Proceed with caution |
| HIGH | 51-75 | Review carefully |
| CRITICAL | 76-100 | Do not proceed |

---

## Use Cases

### For Wallets
- Pre-transaction security screening
- Clear token impact visualization
- Gas cost predictions

### For dApps
- Transaction preview in swap interfaces
- Approval amount recommendations
- Failed transaction prevention

### For Trading Bots
- Pre-execution simulation
- Slippage validation
- MEV protection analysis