内容
# W3Ledger MCP 服务器
> **适用于 AI 代理的自我验证账本 — 每个交易都经过加密签名和链式链接。**
W3Ledger（Rolledge）是一个 MCP（模型上下文协议）服务器，为 AI 代理提供检查代币余额、创建和领取礼品卡、创建和领取赞助卡以及处理双重签名购买的能力 — 所有这些都通过加密签名确保安全。
每个写入操作都需要 **双重签名**（发送者 + 接收者/分发者）。服务器端的 Lambda 函数验证所有签名并强制链条连续性。MCP 服务器是一个薄的 HTTP 客户端 — 它无法绕过安全。
---
## ⚡ 快速入门
### 通过 npx 安装（推荐）
无需安装 — 只需配置您的 AI 客户端：
**Claude Desktop**（`claude_desktop_config.json`）：
```json
{
"mcpServers": {
"w3ledger": {
"command": "npx",
"args": ["-y", "w3ledger-mcp-server"]
}
}
}
```
**Cursor**（`.cursor/mcp.json`）：
```json
{
"mcpServers": {
"w3ledger": {
"command": "npx",
"args": ["-y", "w3ledger-mcp-server"]
}
}
}
```
**VS Code**（`.vscode/mcp.json`）：
```json
{
"servers": {
"w3ledger": {
"type": "stdio",
"command": "npx",
"args": ["-y", "w3ledger-mcp-server"]
}
}
}
```
### 先决条件
- **Node.js** 18+
- 无需外部数据库或云凭证 — 服务器连接到 W3Ledger API
---
## 🛠️ 工具列表
### 🟢 读取（安全）
| 工具 | 描述 |
|:---|:---|
| `check_balance` | 检查公钥的 DAH、DAHYM、DAHLOR 和 W3SH 代币余额。包括忠诚度等级（Seed → Joist）和现金返还率。 |
### 🟡 写入（需要双重签名）
| 工具 | 描述 |
|:---|:---|
| `create_gift_card` | 通过扣除客户的 DAH 余额来创建礼品卡。需要客户签名 + 分发共同签名。 |
| `claim_gift_card` | 领取已发行的礼品卡并增加领取者的 DAH 余额。 |
| `create_sponsor_card` | 创建基于位置的赞助卡，附带 GPS 坐标。需要双重签名。 |
| `claim_sponsor_card` | 在赞助商位置附近领取已发行的赞助卡。 |
| `purchase_product` | 通过扣除发送者的余额并增加接收者（商家）的余额来购买产品。需要发送者 + 接收者双重签名。 |
### ❌ 排除（故意）
| 工具 | 原因 |
|:---|:---|
| `fund_account` | 使用服务器端分发密钥。对于 MCP 来说太危险 — 可能增加任意账户的余额。 |
---
## 🔐 安全模型
W3Ledger 实现了一个 **自我验证链** — 每个交易都经过加密链接到前一个交易：
```
┌──────────────────────────────────────────────────────────┐
│ AI 代理（Claude / Cursor / VS Code） │
│ "购买一个 VR 会话，费用为 35 DAH" │
└──────────────────┬───────────────────────────────────────┘
│ MCP 协议（stdio）
┌──────────────────▼───────────────────────────────────────┐
│ W3Ledger MCP 服务器（薄 HTTP 客户端） │
│ • 将工具调用转发到 API Gateway │
│ • 不验证签名（服务器验证） │
│ • 不直接访问数据库 │
│ • 相当于 curl 的安全性 │
└──────────────────┬───────────────────────────────────────┘
│ HTTPS
┌──────────────────▼───────────────────────────────────────┐
│ API Gateway → Lambda 函数（服务器端） │
│ │
│ ✅ 验证双方签名（发送者 + 接收者） │
│ ✅ 验证链条连续性（前余额链接） │
│ ✅ 验证前一个交易的签名 │
│ ✅ 检查余额充足性 │
│ ✅ 强制时间窗口（5 分钟） │
│ ✅ 原子 DynamoDB transactWrite（全有或全无） │
└──────────────────────────────────────────────────────────┘
```
### 支持的签名方案
| 方案 | 用例 |
|:---|:---|
| **EVM (secp256k1)** | 以太坊/MetaMask 钱包（`personal_sign`） |
| **Ed25519 (Curve25519)** | Solana、Cardano、Stellar、NEAR、Algorand、Aptos、Cosmos、TON 钱包 |
| **ML-DSA-65** | 抗量子签名（NIST 标准） |
| **SLH-DSA** | 无状态基于哈希的抗量子签名 |
---
## ⚙️ 配置
### 环境变量
| 变量 | 是否必填 | 默认值 | 描述 |
|:---|:---|:---|:---|
| `ROLLEDGE_API_URL` | 否 | W3Ledger API | Rolledge API Gateway 的基本 URL |
| `ROLLEDGE_API_KEY` | 否 | — | 可选的 API 密钥，用于身份验证访问 |
| `MCP_LOG_LEVEL` | 否 | `info` | 日志级别：`debug`、`info`、`warn`、`error` |
### 验证安装
列出所有可用的工具：
```bash
npx w3ledger-mcp-server --list-tools
```
---
## 💡 示例对话
```
你： "检查我的余额"
Claude： [调用 check_balance，附带你的公钥]
"你的 DAH 余额是 1,250.00
W3SH：520（Kindling 等级 — 10% 现金返还）
DAHLOR：0 | DAHYM：0"
你： "给我的朋友发送一张 100 DAH 礼品卡，用于购买咖啡"
Claude： [调用 create_gift_card — 需要你的签名]
"请使用你的钱包签署此交易..."
[双重签名后]
"礼品卡 GC-x8k2 已创建！价值：100 DAH
你的新余额：1,150.00 DAH"
你： "购买一个 VR 会话，费用为 35 DAH"
Claude： [调用 purchase_product — 需要发送者 + 接收者签名]
"交易已确认！订单 #VR-2026-001
已花费：35 DAH | 新余额：1,115.00 DAH
🏅 现金返还：赚取 3.50 W3SH（Kindling 等级，10%）"
```
---
## 🏆 W3SH 忠诚度等级
购买会自动根据您的等级赚取 W3SH 现金返还：
| 等级 | W3SH 要求 | 现金返还率 |
|:---|:---|:---|
| 🌱 **Seed** | 0 | 0% |
| 🌿 **Twig** | 100 | 5% |
| 🔥 **Kindling** | 500 | 10% |
| 🪵 **Log** | 2,000 | 15% |
| 🏗️ **Joist** | 10,000 | 20% |
---
## 🔗 链接
- **网站**：[w3ship.com](https://w3ship.com)
- **GitHub**：[github.com/baskcart/rolledge](https://github.com/baskcart/rolledge)
- **W3SH 代币**：[Uniswap CCA Auction](https://app.uniswap.org)
---
## 📄 许可证
MIT — 请参阅 [LICENSE](./LICENSE)
