wwall

Политический предохранитель между ИИ-агентом и кошельком.

Aleph Hackathon 2026 · трек WDK · Tether

Дайте агенту кошелёк — и вы отдали ему свои деньги. wwall — это MCP-сервер, который стоит между ними: агент может предложить платёж, но локальная политика, написанная человеком, решает, будет ли он исполнен, нужно ли одобрение человека, или же он будет отклонён. Каждое решение записывается в подписываемый журнал с добавлением только новых записей.

Агент никогда не касается @tetherto/wdk. Он работает с wwall, а wwall работает с WDK.

┌─────────────┐   MCP/stdio   ┌──────────────────────────┐        ┌──────────┐
│  AI agent   │──────────────▶│  wwall                   │───────▶│   WDK    │──▶ Polygon
│ (Claude…)   │  propose_     │  ├ predicates.ts (guard) │ only   │  wallet  │
│             │   payment     │  ├ ledger.jsonl (signed) │ if     └──────────┘
└─────────────┘◀──────────────│  └ policy.json           │ allowed
                 verdict      └──────────────────────────┘
                                          │ holds NEEDS_CONFIRM
                                          ▼
                                   ┌─────────────┐
                                   │   human     │  wwall pending / confirm / reject
                                   └─────────────┘

Главный инвариант

Ни один вызов инструмента не может достичь wallet.send() без прохождения через evaluatePredicates().

Всё остальное устроено так, чтобы этот инвариант соблюдался:

• Сервер регистрирует ровно три инструмента — propose_payment, get_balance, get_pending. Нет ни send, ни transfer, ни sign, ни инструмента для сырых транзакций, и тест проверяет список инструментов по именам и по шаблонам.

• Кошелёк открывается лениво, только по пути, который уже был разрешён. Отклонённое предложение вообще не создаёт экземпляр WDK — конфигурация токена, необходимая для ответа, передаётся отдельно именно по этой причине.

• Токен выплат фиксируется конфигурацией. Если агент называет другой токен, он получает отказ до запуска каких-либо правил. (Без этого SPEND_CAP{token:"USDT0"} просто не применился бы к token:"MONOPOLY", политика разрешила бы платёж, и кошелёк перевёл бы реальные USD₮0. Лимит расходов не должен обходиться подменой строки.)

• Отказ — это обычный результат работы инструмента, а не выброшенная ошибка, поэтому агент может прочитать причину и объяснить её человеку.

• Те же самые предикаты регистрируются и внутри самого WDK, так что кошелёк отказывает тоже — см. ниже.

Два уровня, один набор предикатов

wwall решает, вызывать ли transfer. Это аргумент о данном процессе. Собственный механизм политик WDK решает, исполнит ли кошелёк перевод, — это свойство аккаунта:

wdk.registerPolicy({
  id: 'wwall-guard', scope: 'project', wallet: 'polygon',
  rules: [{ operation: 'transfer', action: 'ALLOW',
            conditions: [ctx => evaluate(policy, intentFrom(ctx.args), context(), 'ignore-confirm')] }]
})

Одно правило ALLOW, ограниченное теми же evaluatePredicates, что и всё остальное. Сила — в том, что не записано: WDK — это запрет по умолчанию для управляемых аккаунтов, поэтому как только применяется любая политика, каждый метод из OPERATIONS оборачивается, и всё, что не имеет соответствующего ALLOW, выбрасывает PolicyViolationError. Это закрывает обходные пути вокруг лимита расходов, которые вообще не касаются transfer:

wwall не делает ничего из этого. В этом и суть: это были пути, которые его защита не видела. test/wdk-policy.ts запускает настоящий WDK против мёртвого RPC и проверяет, что каждый из них выбрасывает PolicyViolationError до любого сетевого вызова — в то время как разрешённый перевод падает уже на сети, что и доказывает: защита сработала до того, как средства покинули кошелёк, а не после.

Условие спрашивает: «разрешено ли это в принципе» (режим ignore-confirm). Разделение «исполнено против удержано» принадлежит уровню выше: к моменту, когда удержанный платёж доходит до transfer, человек уже одобрил его, и этот уровень не должен отказывать ему во второй раз.

Условие, которое выбрасывает ошибку на ALLOW, считается как «не совпало», а при запрете по умолчанию это означает отказ — значит, ошибка в этом уровне превращается в отказ, а не в молчаливый пропуск.

Быстрый старт из чистого клона

git clone <this repo> && cd wwall
npm install
cp .env.example .env        # then edit it — see below
npm run build
npm test                    # 295 tests, no network, no money
npm run try                 # walk the guard through a dozen proposals, fake wallet

.env требует ровно одну строку. Всё остальное имеет значения по умолчанию:

WARDEN_SEED="…twelve words…"
# WARDEN_ARMED=1            # leave unset until you mean to move real funds

Сеть, RPC и токен выплат по умолчанию — Polygon и USD₮0; политика, журнал и ключ аудита лежат в ~/.wwall/. Смотрите .env.example — там каждая переменная и что она меняет.

Проверьте кошелёк, не тратя ничего:

npm run check:wallet

Это читает symbol() и decimals() прямо из контракта токена и сверяет их с вашей конфигурацией. Неверный decimals — это не просто сообщение об ошибке, это выплата, ошибающаяся на множитель 10ⁿ.

Предохранитель

WARDEN_ARMED по умолчанию выключен. Пока он не равен ровно 1, платёж, разрешённый политикой, регистрируется, но не отправляется — предложение возвращается как rejected с code: "not_armed". Включайте его осознанно.

Установка через Desktop Extension (рекомендуется)

wwall поставляется как MCP Bundle — один файл .mcpb, который Claude Desktop устанавливает в один клик, с формой для настроек вместо ручного редактирования JSON.

npm install && npm run build
npm run bundle          # → build/wwall.mcpb

Затем в Claude Desktop: Settings → Extensions → Install Extension… и выберите build/wwall.mcpb.

Форма спрашивает об одном: seed-фраза. В манифесте она помечена как "sensitive": true, поэтому Claude Desktop маскирует её и хранит в связке ключей ОС, а не в конфигурационном файле, который вы потом случайно вставите в баг-репорт.

Всё остальное имеет значения по умолчанию и не спрашивается:

~/.wwall — это намеренно не рабочая директория: расширение запускается с непредсказуемой текущей директорией, поэтому журнал, привязанный к cwd, дал бы CLI и MCP-серверу разные истории — и дневной лимит, посчитанный из неверного журнала, перестал бы быть лимитом. Обе половины теперь читают один и тот же файл, поэтому wwall pending из любой директории показывает то же, что видит расширение.

При первом запуске wwall создаёт стартовый ~/.wwall/policy.json с пустым списком разрешённых, так что каждый платёж отклоняется, пока вы не укажете получателя:

REJECTED — nothing was sent.
ALLOWLIST: list is empty, no recipient is allowed

Откройте wwall ui, чтобы добавить его. Расширение, которое могло бы платить тому, о ком оно никогда не слышало, не было бы защитой; список разрешённых не должен угадывать за вас.

Здесь нет второго переключателя. Установленное расширение — это и есть предохранитель, и единственное, что стоит между агентом и вашими деньгами, — это политика. В этом весь смысл продукта; глобальный тумблер поверх неё был бы ещё одним местом, куда смотреть, когда платёж отклонён, и ещё одним видом отказа, засоряющим журнал.

WARDEN_ARMED существует только для CLI и ручной конфигурации, где он полезен как заморозка: одна строка в .env останавливает кошелёк, не трогая политику.

Любые значения по умолчанию можно переопределить старым способом — каждая переменная WARDEN_* из .env.example работает и при запуске из CLI, и из расширения.

Сборка бандла требует CLI для упаковки, который уже есть в dev-зависимостях:

npx mcpb validate manifest.json   # check the manifest against the schema
npx mcpb pack build/mcpb build/wwall.mcpb

Формат назывался .dxt и поставлялся как @anthropic-ai/dxt; этот пакет устарел и теперь указывает на @anthropic-ai/mcpb. Спецификация — в MANIFEST.md; этот бандл нацелен на manifest_version 0.4.

Подключение к Claude Desktop вручную

Ручной способ по-прежнему работает и его стоит сохранить: он помещает все настройки в один файл, который можно прочитать с одного взгляда, — а это иногда именно то, что нужно, когда проверяешь, что настроен делать предохранитель.

claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/):

{
  "mcpServers": {
    "wwall": {
      "command": "node",
      "args": ["/absolute/path/to/wwall/dist/src/bin/wwall-mcp.js"],
      "env": {
        "WARDEN_SEED": "…twelve words…",
        "WARDEN_CHAIN": "polygon",
        "WARDEN_RPC_URL": "https://polygon-bor-rpc.publicnode.com",
        "WARDEN_TOKEN_ADDRESS": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
        "WARDEN_TOKEN_SYMBOL": "USDT0",
        "WARDEN_TOKEN_DECIMALS": "6",
        "WARDEN_POLICY": "/absolute/path/to/wwall/policy.json",
        "WARDEN_LEDGER": "/absolute/path/to/wwall/ledger.jsonl"
      }
    }
  }
}

Перезапустите Claude Desktop — и появятся три инструмента. Без клиента сервер говорит на обычном JSON-RPC через stdio:

printf '%s\n%s\n%s\n' \
 '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"x","version":"0"}}}' \
 '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
 '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
 | node dist/src/bin/wwall-mcp.js

Или запустите MCP Inspector: npx @modelcontextprotocol/inspector node dist/src/bin/wwall-mcp.js

Инструменты

Суммы — десятичные строки везде: "12.50", никогда не 12.5. JSON-число на денежном пути — это float, а float — это ошибка округления, ждущая достаточно большого числа.

Человеческая половина

Агент может перевести платёж в состояние pending_confirmation. Вывести его оттуда может только человек:

wwall pending                     # what is waiting, and which rule held it
wwall confirm <id> --by alex      # approve and send
wwall reject  <id> --note "…"     # refuse; nothing is ever sent
wwall ui                          # policy builder in the browser

Обе половины читают и пишут один и тот же ledger.jsonl, поэтому wwall pending показывает ровно то же, что и get_pending у агента.

wwall confirm заново оценивает политику перед отправкой. Вердикт был вынесен, когда агент предлагал платёж — возможно, часы и несколько платежей назад; лимиты расходов с тех пор сдвинулись. Команда перепроверяет в режиме «ignore-confirm» — спрашивая только разрешено ли это по-прежнему, потому что человек за клавиатурой и есть подтверждение.

Политика

policy.json — это дерево предикатов. Девять операций:

CONFIRM_THRESHOLD — вот почему политика вычисляется дважды для каждого предложения: один раз со всеми порогами, считающимися выполненными (допустимо ли это вообще?), и один раз строго (может ли это пройти без внимания человека?). Именно это позволяет порогу работать внутри AND, OR или NOT, а не только на верхнем уровне — плоский флаг «требуется одобрение» на такое не способен.

В зачёт лимита идут только подтверждённые отправки. Платёж, отправленный, но ещё не подтверждённый, невидим для SPEND_CAP и VELOCITY; см. Известные ограничения.

Конструктор без кода

wwall ui          # → http://127.0.0.1:4478/

Плоский список карточек правил плюс один переключатель «все/любое», живой предпросмотр policy.json и тестовая форма, показывающая вердикт по мере ввода. Кнопка Save записывает policy.json через локальный сервер.

На странице нет копии логики защиты. Вердикт приходит от POST /api/evaluate, который вызывает тот же evaluatePredicates, что и MCP-сервер и CLI, — вторая реализация на браузерном JavaScript разошлась бы с этой и незаметно начала бы давать другие ответы. Тест проверяет, что страница не содержит клиентской арифметики сумм.

Конструктор намеренно не умеет рисовать вложенную композицию (NOT, группы внутри групп). Политика, которая её использует, открывается в режиме только для чтения с пометкой, указывающей на policy.json. Полная композиция остаётся доступной при редактировании файла.

Журнал аудита

Каждая запись — вердикты, попытки отправки, результаты, решения человека — добавляется в ledger.jsonl, подписывается локальным ключом Ed25519 и связывается с предыдущей записью.

npm run verify:audit

records   3  (3 signed, 3 verified)
pinned to MCowBQYDK2VwAyEAKcjUin18… from audit-key.json

✓ every record is signed and the chain is unbroken

Подписи доказывают, что запись не была отредактирована. Они не доказывают, что она не была удалена — удаление строки оставляет все остальные подписи действительными. Именно для этого нужен prev. Вместе они ловят редактирование, удаление из середины и перестановку.

Строка pinned to важна: без ключа аудита для проверки журнал, переписанный целиком с ключом атакующего, проверяется безупречно. Проверка имеет смысл только против ключа, которому вы доверяете.

Сценарии

36 сценариев прогоняются через настоящий MCP-сервер по настоящему транспорту — а не прямым вызовом оценщика, потому что интересные сбои живут в предварительных проверках, в обороте журнала и на границе инструмента.

npm run report:scenarios            # print
npm run report:scenarios -- --write # splice the table into this README

Результаты сценариев

Интеграция с WDK

Каждый вызов WDK в проекте, в одном файле:

MCP SDK: new McpServer в src/mcp-server.ts:97, три вызова registerTool в 113, 169 и 209, и StdioServerTransport в src/bin/wwall-mcp.ts:52.

Сигнатуры были прочитаны из собственных .d.ts-файлов установленных пакетов, а не из памяти — и tsc --strict проверяет типы по ним, что и является доказательством.

Пакеты

Никаких зависимостей для денежных расчётов, подписи, HTTP или UI: BigInt с фиксированной точкой, node:crypto Ed25519, node:http и один вручную написанный HTML-файл.

Структура

Известные ограничения

Сказано прямо, потому что инструмент безопасности, скрывающий свои ограничения, хуже того, у которого их нет.

• В зачёт лимита идут только подтверждённые переводы. Пакет, отправленный быстрее, чем он подтверждается, может превысить дневной лимит. LedgerEvalContext.pendingInWindow() существует, чтобы отчёт мог показать сумму, находящуюся в обработке, которую не видит ни один лимит.

• Усечение хвоста невозможно обнаружить. Хеш-цепочка идёт в обратном направлении, поэтому удаление последних N записей оставляет корректный префикс. Чтобы это поймать, нужен внешний якорь — счётчик записей, хранящийся в другом месте, или дайджест вершины, опубликованный где-то вне файла.

• Сид остаётся сидом. Политика WDK управляет аккаунтами, полученными через этот экземпляр WDK. Любой, у кого есть та же сид-фраза в другом процессе — другой скрипт, кошелёк-приложение, утёкший .env — переводит средства, и политика не мешает. Чтобы это предотвратить, нужен ключ, который не может покинуть пределы, а не политика: подписант в анклаве, смарт-аккаунт с ончейн-лимитами или со-подписант. wwall ограничивает агента; он не ограничивает держателя ключа.

• USD₮ на Polygon — это USDT0. Старый USDT Polygon с PoS-мостом был мигрирован на месте в нативный USD₮0, омниканальный токен Tether, обеспеченный 1:1 в Ethereum-сейфе. Проверено в цепочке: name()="USDT0", symbol()="USDT0", decimals()=6. Не используйте адрес BNB Chain 0x55d398… — это Binance-Peg, не выпущенный Tether, и у него 18 десятичных знаков, а не 6.

• policy.json — доверенный вход. Любой, кто может записать этот файл, может переписать защиту. Он загружается один раз при старте, и его sha256 записывается в каждый вердикт, поэтому изменение видно в журнале аудита постфактум — но оно не предотвращается.