wwall

AIエージェントとウォレットの間に立つポリシーガード。

Aleph Hackathon 2026 · WDK track · Tether

エージェントにウォレットを与えることは、あなたのお金を渡すことです。wwall はその間に立ちはだかる MCP サーバーです。エージェントは支払いを提案できますが、それが実行されるか、事前に人間の承認が必要か、あるいは完全に拒否されるかは、ローカルで人間が作成したポリシーが決定します。すべての決定は、署名付きの追記専用台帳 (append-only ledger) に記録されます。

エージェントが触れるのは @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
                                   └─────────────┘

唯一の不変条件

evaluatePredicates() を最初に通過しない限り、いかなるツール呼び出しも wallet.send() に到達できません。

これを守るために、他のすべては次のように設計されています。

• サーバーが登録するツールは正確に3つだけです — propose_payment、get_balance、get_pending。send、transfer、sign、raw-transaction のツールは存在せず、テストはツール一覧を名前とパターンの両方で検証します。

• ウォレットは遅延的に開かれ、すでに許可された経路でのみ開かれます。拒否された提案では WDK インスタンスは一切構築されません — その提案に応答するために必要なトークン設定は、まさにこの理由から別途渡されます。

• 支払いトークンは設定によって固定されます。別のトークンを指定したエージェントは、ルールが実行される前に拒否されます。(これがないと、SPEND_CAP{token:"USDT0"} は token:"MONOPOLY" に適用されず、ポリシーはそれを許可し、ウォレットは実際の USD₮0 を動かしてしまいます。支払い上限は文字列で迂回できてはなりません。)

• 拒否は通常のツール結果であり、エラーを投げることはありません。そのためエージェントは理由を読んで、人間に説明できます。

• 同じ述語が WDK 自体にも登録されているため、ウォレット側も拒否します — 後述。

2つの層、1つの述語セット

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')] }]
})

1つの ALLOW ルールがあり、他のすべてが使うのと同じ evaluatePredicates でゲートされています。その力の源泉は、書かれていないものにあります。WDK は管理対象アカウントではデフォルト拒否 (default-deny) です。そのため、ポリシーが1つでも適用された瞬間、OPERATIONS 内のすべてのメソッドがラップされ、対応する ALLOW がないものはすべて PolicyViolationError を投げます。これにより、transfer をまったく経由しない支払い上限の迂回路が塞がれます。

wwall はこれらのいずれも行いません。それが要点です。これらは wwall のガードでは見えない経路だったからです。test/wdk-policy.test.ts は、実在の WDK インスタンスを到達不能な RPC に対して駆動し、それぞれがネットワーク呼び出しより前に PolicyViolationError を投げることを検証します。一方、許可された transfer はネットワーク上で失敗します。これは、ガードに阻止されたのではなく、ガードを通過したことを示しています。

この条件は「そもそも許可されているか」を問います (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 に必要なのは正確に1行だけです。それ以外はすべてデフォルトがあります。

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 になるまで、ポリシーが許可した支払いも報告されるだけで送信されません — 提案は code: "not_armed" の rejected として返ってきます。意図的に武装させてください。

Desktop Extension でインストールする（推奨）

wwall は MCP Bundle として配布されます。1つの .mcpb ファイルを Claude Desktop がワンクリックでインストールし、手書きの JSON の代わりに設定用のフォームが用意されます。

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

次に Claude Desktop で: Settings → Extensions → Install Extension… を開き、build/wwall.mcpb を選択します。

フォームが尋ねるのは1つだけです: シードフレーズです。 これはマニフェストで "sensitive": true と宣言されているため、Claude Desktop はそれをマスクし、後でバグレポートに貼り付けるかもしれない設定ファイルではなく、OS のキーチェーンに保管します。

その他はすべてデフォルトがあり、尋ねられません。

~/.wwall は意図的に作業ディレクトリにしていません。拡張機能は予測不能な cwd で起動されるため、cwd 相対の台帳では CLI と MCP サーバーが異なる支払い履歴を持つことになります。そして、間違った台帳から計算された日次上限は上限とは呼べません。現在は両者が同じ台帳を読み書きするため、どのディレクトリからでも wwall pending を実行すれば、拡張機能が書き込んだ内容が見えます。

初回実行時、wwall は空の許可リストを持つスターター用の ~/.wwall/policy.json を書き出します。そのため、受取人を指定するまですべての支払いが拒否されます。

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

追加するには wwall ui を開きます。知らされていない相手に支払える拡張機能はガードとは言えません。許可リストはあなたの代わりに推測する類のものではありません。

意図的に2つ目のスイッチはありません。インストールされた拡張機能は武装済みであり、エージェントとあなたのお金の間に立つものはポリシーだけです。これはこのプロダクトの主張そのものであり、その上にマスタートグルを置けば、その主張は損なわれます。許可リストへの受取人の追加こそが意図的な行為です。グローバルなオン/オフは、支払いが拒否されたときに確認すべき場所をもう1つ増やすだけで、もう1種類の拒否を監査ログに散らかすだけです。

WARDEN_ARMED は CLI と手書きの設定のため依然として存在します。そこではフリーズとして有用です。.env の1行で、ポリシーに触れずにウォレットを停止できます。

デフォルトは従来どおりいつでも上書きできます。.env.example のすべての WARDEN_* 変数は、wwall が CLI から起動されたか拡張機能から起動されたかに関係なく機能します。

バンドルのビルドにはパッケージング CLI が必要ですが、これはすでに dev dependency に含まれています。

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 へ手動で組み込む

手動の方法も引き続き機能し、残しておく価値があります。すべての設定がひと目で確認できる1つのファイルに収まるため、ガードが何をするように設定されているかを確認する際に、まさに望む形になることがあります。

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 を再起動すると、3つのツールが表示されます。クライアントがない場合、サーバーは stdio 上でプレーンな JSON-RPC を話します。

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

ツール

金額はどこでも10進数の 文字列 です — "12.50" であって、決して 12.5 ではありません。金額経路における JSON 数値は浮動小数点数であり、浮動小数点数は十分に大きな数値を待っている丸めバグです。

人間側

エージェントは支払いを 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 は述語ツリーです。9つのオペコードがあります。

CONFIRM_THRESHOLD が、ポリシーが提案ごとに2回評価される理由です。1回目はすべてのしきい値が満たされているものとして扱い（そもそもこれは許可されるのか?）、2回目は厳密に評価します（無人で実行できるのか?）。これにより、しきい値はトップレベルだけでなく AND、OR、NOT の中でも機能するのです — 単純な「承認が必要」フラグではそれは実現できません。

上限にカウントされるのは確認済みの送金のみです。送信されたがまだ確認されていない支払いは SPEND_CAP と VELOCITY からは見えません。既知の制限 を参照してください。

ノーコードビルダー

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

ルールカードのフラットなリストと、全件一致/いずれか一致のスイッチ、ライブの policy.json プレビュー、入力に応じて判定結果を表示するテストフォーム。Save ボタンはローカルサーバー経由で policy.json を書き込みます。

このページにはガードロジックのコピーは一切含まれていません。判定結果は POST /api/evaluate から取得され、これは MCP サーバーと CLI が呼ぶのと同じ evaluatePredicates を呼び出します — ブラウザの JavaScript で2つ目の実装を作ると、これから乖離して静かに異なる答えを返し始めるでしょう。テストは、このページがクライアントサイドの金額演算を含まないことを検証します。

ビルダーは意図的にネストした構成（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 の役割です。この2つで、編集、中間からの削除、並べ替えを検出できます。

pinned to の行は重要です。照合する監査キーがなければ、攻撃者のキーで丸ごと書き換えられたログも完全に検証できてしまいます。検証が意味を持つのは、信頼するキーと照合した場合だけです。

シナリオ

36のシナリオが、実際のトランスポートを介して実際の MCP サーバーを通じて実行されます — 評価器を直接呼び出すのではありません。なぜなら、興味深い失敗は事前チェック、台帳のラウンドトリップ、ツール境界に存在するからです。

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

シナリオ結果

WDK 統合

プロジェクト内のすべての WDK 呼び出しを1つのファイルに集約:

MCP SDK: new McpServer は src/mcp-server.ts:97、3つの registerTool 呼び出しは 113、169、209、StdioServerTransport は src/bin/wwall-mcp.ts:52 にあります。

シグネチャは記憶からではなく、インストール済みパッケージ自身の .d.ts ファイルから読み取られています — そして tsc --strict がそれらに対して型チェックを行うこと自体が、その証明です。

パッケージ

金額計算、署名、HTTP、UIのための依存関係はありません: BigInt固定小数点数、node:crypto Ed25519、node:http、そして手書きのHTMLファイル1つのみです。

構成

既知の制限

率直に述べます。限界を隠すセキュリティツールは、限界を持たないツールよりも悪いからです。

• 上限にカウントされるのは確認済み送金のみです。 確認よりも速く送出されたバッチは、日次上限を超える可能性があります。LedgerEvalContext.pendingInWindow() は、どの上限からも見えない進行中の金額をレポートが表示できるようにするためのものです。

• 末尾の切り詰めは検出できません。 ハッシュチェーンは逆方向に連なるため、最後の N件のレコードを削除しても有効なプレフィックスが残ります。これを検出するには外部アンカーが必要です — 別の場所に保持されたレコード件数、またはファイルの外のどこかに公開された最新ダイジェストです。

• シードはあくまでシードです。 WDKポリシーが管理するのは、この WDKインスタンスを通じて取得されたアカウントだけです。同じシードフレーズを別のプロセスで保持している人 — 別のスクリプト、ウォレットアプリ、流出した .env — は、ポリシーの妨げを受けることなく資金を移動できます。これを防ぐために必要なのはポリシーではなく、外部に持ち出せない鍵です: エンクレーブ内の署名者、オンチェーン制限付きのスマートアカウント、または共同署名者です。wwallはエージェントを制約しますが、鍵の保持者を制約するものではありません。

• Polygon上のUSD₮はUSDT0です。 Polygonの旧PoSブリッジUSDTは、その場でTetherのオムニチェーントークンであるネイティブUSD₮0へ移行され、Ethereumのロックボックスに1:1で裏付けられています。オンチェーンで検証済み: name()="USDT0"、symbol()="USDT0"、decimals()=6。BNB Chainのアドレス 0x55d398… を流用しないでください — これはTether発行ではなくBinance-Pegであり、小数桁は6ではなく18です。

• policy.json は信頼済み入力です。 そのファイルを書き込める人なら誰でも、ガードを書き換えられます。これは起動時に一度だけ読み込まれ、そのsha256がすべての判定に記録されるため、変更は事後に監査ログで確認できます — ただし、防ぐことはできません。