# ArcLeap MCP — мост USDC для ИИ-агентов

MCP-сервер, который даёт агенту возможность переводить нативные USDC между сетями через **Circle CCTP V2** (сжигание → аттестация Circle → выпуск). Без обёрнутых токенов и пулов ликвидности.

Сети: Ethereum, Base, Arbitrum, OP Mainnet, Polygon PoS, Avalanche — и их тестнеты плюс **Arc Testnet**.

## Почему отдельный сервер, а не веб-интерфейс

У агента нет браузера и всплывающих окон кошелька, зато есть три специфические проблемы, которых нет у человека:

1. **Перевод длится минуты.** Аттестация Standard Transfer занимает от нескольких минут до ~20. Поэтому `bridge_start` возвращается сразу после сжигания, а выпуск делается отдельным вызовом `bridge_status`. Агент не висит в блокирующем вызове.
2. **Агент может упасть или потерять контекст.** Состояние каждого перевода лежит на диске, `bridge_history` показывает незавершённые переводы, а `bridge_status` доводит их до конца в любой момент.
3. **Агент может зациклиться и повторить вызов.** Отсюда обязательный `idempotencyKey`: повторный запуск с тем же ключом вернёт уже созданный перевод, а не сожжёт средства второй раз.

## Установка

```bash
npm install
npm run build
```

## Настройка подписанта

Поддерживаются два режима — ключи никогда не попадают в контекст агента.

**Вариант A. Circle Developer-Controlled Wallets (рекомендуется для реальных средств).** Подпись выполняется на стороне Circle, у агента нет ни ключа, ни seed-фразы, доступны политики и аудит Circle.

```bash
ARCLEAP_SIGNER=circle
CIRCLE_API_KEY=...
CIRCLE_ENTITY_SECRET=...
CIRCLE_WALLET_ID=...
CIRCLE_WALLET_ADDRESS=0x...
npm install @circle-fin/developer-controlled-wallets
```

**Вариант B. Локальный приватный ключ.** Просто и быстро, но ключ лежит на машине — только для горячего кошелька с небольшими суммами.

```bash
ARCLEAP_SIGNER=privateKey
ARCLEAP_PRIVATE_KEY=0x...
```

## Ограничители

```bash
ARCLEAP_MAX_PER_TRANSFER=100   # максимум USDC за один перевод (mainnet)
ARCLEAP_MAX_DAILY=500          # суточный лимит на кошелёк (mainnet)
ARCLEAP_STATE_DIR=~/.arcleap-mcp
```

Лимиты применяются только к mainnet: в тестнете агент может экспериментировать свободно. Превышение возвращает ошибку до отправки любых транзакций.

## Подключение к Claude

`claude_desktop_config.json` (или `.mcp.json` для Claude Code):

```json
{
  "mcpServers": {
    "arcleap-bridge": {
      "command": "node",
      "args": ["/абсолютный/путь/arcleap-mcp/dist/index.js"],
      "env": {
        "ARCLEAP_SIGNER": "privateKey",
        "ARCLEAP_PRIVATE_KEY": "0x...",
        "ARCLEAP_MAX_PER_TRANSFER": "50",
        "ARCLEAP_MAX_DAILY": "200"
      }
    }
  }
}
```

## Инструменты

| Инструмент | Назначение |
| --- | --- |
| `bridge_list_chains` | Сети и их CCTP-домены |
| `bridge_quote` | Проверка без транзакций: балансы USDC и газа, комиссия, лимиты |
| `bridge_start` | Approve + сжигание, возвращает `transferId` |
| `bridge_status` | Проверяет аттестацию и выпускает USDC в целевой сети |
| `bridge_history` | Переводы и журнал аудита, список незавершённых |
| `bridge_wallet_info` | Адрес и тип подписанта, текущие лимиты |

## Типичный сценарий агента

```
bridge_quote   { from: "base", to: "arbitrum", amount: "10" }
bridge_start   { from: "base", to: "arbitrum", amount: "10", idempotencyKey: "task-42" }
   → { id: "…", status: "burned", burnTx: "0x…" }
bridge_status  { transferId: "…" }     # повторять раз в минуту
   → { status: "minted", mintTx: "0x…" }
```

Начинать стоит с `dryRun: true` — пройдут все проверки, но ни одна транзакция не будет отправлена.

## Важное о газе

Выпуск (`receiveMessage`) выполняется в **целевой** сети и требует там нативного токена на газ. `bridge_quote` заранее предупредит, если у получателя пустой баланс — иначе средства окажутся сожжены и будут ждать выпуска.

## Об Arc

CCTP-домен Arc (26) существует только в тестовой сети. В mainnet такого домена нет, поэтому маршрут в Arc доступен лишь для `arc-testnet`. Как только Circle запустит Arc mainnet и выделит домен, сеть добавляется одной строкой в `src/chains.ts`.