# W3Ledger MCP Server

> **A self-verifying ledger for AI agents — every transaction is cryptographically signed and chain-linked.**

W3Ledger (Rolledge) is an MCP (Model Context Protocol) server that gives AI agents the ability to check token balances, create and claim gift cards, create and claim sponsor cards, and process dual-signed purchases — all secured by cryptographic signatures.

Every write operation requires **dual signatures** (sender + receiver/distribution). The server-side Lambda functions verify all signatures and enforce chain continuity. The MCP server is a thin HTTP client — it cannot bypass security.

---

## ⚡ Quick Start

### Install via npx (recommended)

No installation required — just configure your AI client:

**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"]
    }
  }
}
```

### Prerequisites

- **Node.js** 18+
- No external database or cloud credentials required — the server connects to the W3Ledger API

---

## 🛠️ Tools (6 total)

### 🟢 Read (Safe)

| Tool | Description |
|:---|:---|
| `check_balance` | Check DAH, DAHYM, DAHLOR, and W3SH token balances for a public key. Includes loyalty tier (Seed → Joist) with cashback rates. |

### 🟡 Write (Requires Dual Signatures)

| Tool | Description |
|:---|:---|
| `create_gift_card` | Create a gift card by debiting the customer's DAH balance. Requires customer signature + distribution co-signature. |
| `claim_gift_card` | Claim an ISSUED gift card and credit the claimer's DAH balance. |
| `create_sponsor_card` | Create a location-based sponsor card with GPS coordinates. Requires dual signatures. |
| `claim_sponsor_card` | Claim an ISSUED sponsor card near the sponsor's location. |
| `purchase_product` | Purchase a product by debiting sender and crediting receiver (merchant). Requires sender + receiver dual signatures. |

### ❌ Excluded (Intentionally)

| Tool | Reason |
|:---|:---|
| `fund_account` | Uses server-side distribution keys. Too dangerous for MCP — could credit arbitrary accounts. |

---

## 🔐 Security Model

W3Ledger implements a **self-verifying chain** — every transaction is cryptographically linked to the previous one:

```
┌──────────────────────────────────────────────────────────┐
│  AI Agent (Claude / Cursor / VS Code)                    │
│  "Purchase a VR session for 35 DAH"                      │
└──────────────────┬───────────────────────────────────────┘
                   │ MCP Protocol (stdio)
┌──────────────────▼───────────────────────────────────────┐
│  W3Ledger MCP Server (thin HTTP client)                  │
│  • Forwards tool calls to API Gateway                    │
│  • Does NOT verify signatures (server does)              │
│  • Does NOT access database directly                     │
│  • Equivalent security to curl                           │
└──────────────────┬───────────────────────────────────────┘
                   │ HTTPS
┌──────────────────▼───────────────────────────────────────┐
│  API Gateway → Lambda Functions (server-side)            │
│                                                          │
│  ✅ Validates both signatures (sender + receiver)        │
│  ✅ Verifies chain continuity (prev_balance linkage)     │
│  ✅ Verifies previous transaction's signature            │
│  ✅ Checks balance sufficiency                           │
│  ✅ Enforces timestamp window (5 min)                    │
│  ✅ Atomic DynamoDB transactWrite (all-or-nothing)       │
└──────────────────────────────────────────────────────────┘
```

### Supported Signature Schemes

| Scheme | Use Case |
|:---|:---|
| **EVM (secp256k1)** | Ethereum/MetaMask wallets (`personal_sign`) |
| **Ed25519 (Curve25519)** | Solana, Cardano, Stellar, NEAR, Algorand, Aptos, Cosmos, TON wallets |
| **ML-DSA-65** | Post-quantum signatures (NIST standard) |
| **SLH-DSA** | Stateless hash-based post-quantum signatures |

---

## ⚙️ Configuration

### Environment Variables

| Variable | Required | Default | Description |
|:---|:---|:---|:---|
| `ROLLEDGE_API_URL` | No | W3Ledger API | Base URL for the Rolledge API Gateway |
| `ROLLEDGE_API_KEY` | No | — | Optional API key for authenticated access |
| `MCP_LOG_LEVEL` | No | `info` | Logging level: `debug`, `info`, `warn`, `error` |

### Verify Installation

List all available tools:
```bash
npx w3ledger-mcp-server --list-tools
```

---

## 💡 Example Conversation

```
You:    "Check my balance"
Claude: [calls check_balance with your public key]
        "Your DAH balance is 1,250.00
         W3SH: 520 (Kindling tier — 10% cashback)
         DAHLOR: 0  |  DAHYM: 0"

You:    "Send a 100 DAH gift card to my friend for coffee"
Claude: [calls create_gift_card — requires your signature]
        "Please sign this transaction with your wallet..."
        [after dual signing]
        "Gift card GC-x8k2 created! Value: 100 DAH
         Your new balance: 1,150.00 DAH"

You:    "Buy a VR session for 35 DAH"
Claude: [calls purchase_product — requires sender + receiver signatures]
        "Transaction confirmed! Order #VR-2026-001
         Spent: 35 DAH  |  New balance: 1,115.00 DAH
         🏅 Cashback: 3.50 W3SH earned (Kindling tier, 10%)"
```

---

## 🏆 W3SH Loyalty Tiers

Purchases automatically earn W3SH cashback based on your tier:

| Tier | W3SH Required | Cashback Rate |
|:---|:---|:---|
| 🌱 **Seed** | 0 | 0% |
| 🌿 **Twig** | 100 | 5% |
| 🔥 **Kindling** | 500 | 10% |
| 🪵 **Log** | 2,000 | 15% |
| 🏗️ **Joist** | 10,000 | 20% |

---

## 🔗 Links

- **Website**: [w3ship.com](https://w3ship.com)
- **GitHub**: [github.com/baskcart/rolledge](https://github.com/baskcart/rolledge)
- **W3SH Token**: [Uniswap CCA Auction](https://app.uniswap.org)

---

## 📄 License

MIT — see [LICENSE](./LICENSE)