wwall

AI 에이전트와 지갑 사이에 위치하는 정책 가드.

Aleph Hackathon 2026 · WDK 트랙 · 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()에 도달할 수 없다.

다른 모든 것은 이 사실을 유지하기 위해 배치되어 있습니다:

• 서버는 정확히 세 개의 도구 — propose_payment, get_balance, get_pending — 만 등록합니다. send, transfer, sign 또는 raw-transaction 도구는 없으며, 테스트가 도구 목록을 이름과 패턴으로 검증합니다.

• 지갑은 지연(lazily) 열리며, 이미 허용된 경로에서만 열립니다. 거부된 제안은 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')] }]
})

다른 모든 것이 사용하는 동일한 evaluatePredicates에 게이트된 하나의 ALLOW 규칙. 활용되는 지점은 작성되지 않은 것에 있습니다: WDK는 관리되는 계정에서 기본 거부(default-deny) 이므로, 어떤 정책이 적용되는 순간 OPERATIONS의 모든 메서드가 래핑되고 일치하는 ALLOW가 없는 모든 것은 PolicyViolationError를 던집니다. 이는 transfer를 전혀 건드리지 않는 지출 한도를 우회하는 경로를 차단합니다:

wwall은 이러한 작업을 수행하지 않습니다. 그것이 핵심입니다: 그것들은 wwall의 가드가 볼 수 없었던 것들이었습니다. test/wdk-policy.test.ts는 죽은 RPC에 대해 실제 WDK 인스턴스를 구동하고 각각이 네트워크 호출 전에 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에는 정확히 한 줄만 필요합니다. 나머지는 모두 기본값이 있습니다:

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로 반환됩니다. 의도적으로 활성화하세요.

데스크톱 확장으로 설치 (권장)

wwall은 MCP 번들로 제공됩니다 — 단일 .mcpb 파일로 Claude Desktop이 한 번의 클릭으로 설치하며, 수동으로 JSON을 편집하는 대신 설정을 위한 양식이 있습니다.

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

그런 다음 Claude Desktop에서: 설정 → 확장 프로그램 → 확장 프로그램 설치… 를 선택하고 build/wwall.mcpb를 선택하세요.

양식은 한 가지만 요구합니다: 시드 문구. 매니페스트에서 "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를 열어 수신자를 추가하세요. 알려주지 않은 사람에게 지불할 수 있는 확장 프로그램은 가드가 아니며, 허용 목록은 당신을 대신해 추측할 수 있는 것이 아닙니다.

의도적으로 두 번째 스위치는 없습니다. 설치된 확장 프로그램은 무장되어 있으며, 에이전트와 당신의 돈 사이에 서 있는 유일한 것은 정책입니다 — 이것이 제품의 전체 주장이며, 그 위에 마스터 토글이 있으면 그 주장이 약화됩니다. 허용 목록에 수신자를 추가하는 것이 의도적인 행동입니다. 전역 on/off는 지불이 거부될 때 확인할 두 번째 장소일 뿐이며, 감사 로그를 어지럽히는 두 번째 종류의 거부일 뿐입니다.

WARDEN_ARMED는 여전히 CLI와 수동 작성 구성에 존재하며, 동결 기능으로 유용합니다: .env의 한 줄이 정책을 건드리지 않고 지갑을 중지시킵니다.

모든 기본값은 여전히 이전 방식으로 재정의할 수 있습니다 — .env.example의 모든 WARDEN_* 변수는 wwall이 CLI로 시작되었든 확장 프로그램으로 시작되었든 작동합니다.

번들을 빌드하려면 패키징 CLI가 필요한데, 이는 이미 개발 의존성입니다:

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을 다시 시작하면 세 개의 도구가 나타납니다. 클라이언트가 없으면 서버는 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

도구

금액은 모든 곳에서 소수 문자열입니다 — "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은 술어 트리입니다. 아홉 개의 opcode:

CONFIRM_THRESHOLD가 정책이 제안당 두 번 평가되는 이유입니다. 한 번은 모든 임계값이 충족된 것으로 간주하고(이게 아예 허용되는가?), 한 번은 엄격하게 평가합니다(무인으로 진행될 수 있는가?). 이것이 임계값이 최상위 수준이 아닌 AND, OR, NOT 내부에서도 작동할 수 있게 하는 이유입니다. 단순히 "승인 필요" 플래그 하나로는 불가능한 일입니다.

한도 계산에는 확인된 송금만 포함됩니다. 아직 확인되지 않은 결제는 SPEND_CAP과 VELOCITY에 보이지 않습니다. 알려진 제한 사항을 참고하세요.

코드 없는 빌더

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

규칙 카드의 단순 목록과 일치-전체/일치-일부 스위치, 실시간 policy.json 미리보기, 그리고 입력 시 평가 결과를 보여주는 테스트 폼으로 구성됩니다. 저장 버튼은 로컬 서버를 통해 policy.json을 작성합니다.

이 페이지에는 가드 로직의 복사본이 포함되어 있지 않습니다. 평가 결과는 MCP 서버와 CLI가 사용하는 동일한 evaluatePredicates를 호출하는 POST /api/evaluate에서 옵니다. 브라우저 자바스크립트로 동일한 로직을 구현하면 이 구현과 차이가 생겨 조용히 다른 결과를 내기 시작할 것입니다. 빌더에는 클라이언트 측 금액 산술이 포함되지 않는다는 테스트가 있습니다.

빌더는 의도적으로 중첩 구성(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

시나리오 결과

MCP SDK: src/mcp-server.ts:97의 new McpServer, 113, 169, 209의 세 번의 registerTool 호출, 그리고 src/bin/wwall-mcp.ts:52의 StdioServerTransport.

시그니처는 메모리가 아닌 설치된 패키지 자체의 .d.ts 파일에서 읽었으며, tsc --strict가 이를 기준으로 타입 검사를 수행하는 것이 그 증거입니다.

패키지

자금 계산, 서명, HTTP 또는 UI에 대한 의존성이 없습니다: BigInt 고정 소수점, node:crypto Ed25519, node:http, 그리고 손으로 작성한 단일 HTML 파일만 사용합니다.

구조

알려진 한계

솔직하게 명시합니다. 한계를 숨기는 보안 도구는 한계가 없는 도구보다 더 나쁘기 때문입니다.

• 한도에 집계되는 것은 확인된 전송뿐입니다. 확인 속도보다 빠르게 일괄 전송되면 일일 한도를 초과할 수 있습니다. 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이 기록되므로 변경 사항은 사후에 감사 로그에서 확인할 수 있습니다 — 그러나 예방되지는 않습니다.