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):

{
  "mcpServers": {
    "w3ledger": {
      "command": "npx",
      "args": ["-y", "w3ledger-mcp-server"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "w3ledger": {
      "command": "npx",
      "args": ["-y", "w3ledger-mcp-server"]
    }
  }
}

VS Code (.vscode/mcp.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:

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
• GitHub: github.com/baskcart/rolledge
• W3SH Token: Uniswap CCA Auction

---

📄 License

MIT — see LICENSE