chia-walletconnect – OpenClaw Skill

---

name: chia-walletconnect description: Telegram Web App for Chia wallet verification via WalletConnect and Sage. Enables cryptographic proof of wallet ownership through signature verification using MintGarden API. metadata: {"clawdbot":{"requires":{"bins":["node"]},"install":[]}}

Chia WalletConnect Skill

Verify Chia wallet ownership via Telegram using WalletConnect integration with Sage Wallet.

What It Does

This skill provides a Telegram Mini App (Web App) that enables users to:

1. Connect their Sage Wallet via WalletConnect v2
2. Sign a challenge message cryptographically
3. Verify wallet ownership via MintGarden's signature verification API
4. Return verification status to your Telegram bot

Use Cases:

• NFT-gated Telegram groups
• Airdrop eligibility verification
• Web3-style authentication
• DAO voting authentication
• Proof of token holdings

Architecture

/verify command → Web App button → WalletConnect → Sage signs → Verification

The user never leaves Telegram. The entire flow happens in-app via the Telegram Web App API.

Installation

# Install via ClawdHub
clawdhub install chia-walletconnect

# Install dependencies
cd skills/chia-walletconnect
npm install

# Make CLI executable
chmod +x cli.js

Deployment

Step 1: Deploy Web App

Deploy the webapp/ folder to a public HTTPS URL:

Vercel (Recommended):

cd skills/chia-walletconnect/webapp
vercel
# Copy the URL (e.g., https://chia-verify.vercel.app)

Netlify:

cd skills/chia-walletconnect/webapp
netlify deploy --prod

Your Server:

# Start Express server
npm start
# Expose via ngrok or reverse proxy

Step 2: Register with BotFather

1. Message @BotFather
2. Send /newapp or /editapp
3. Select your bot
4. Web App URL: Enter deployed URL
5. Short Name: verify

Step 3: Add to Bot

Using Clawdbot Message Tool

// Send /verify command handler
message({
  action: 'send',
  target: chatId,
  message: 'Click below to verify your Chia wallet:',
  buttons: [[{
    text: '🌱 Verify Wallet',
    web_app: { url: 'https://your-app.vercel.app' }
  }]]
});

Handling Verification Response

// In your bot's web_app_data handler
bot.on('web_app_data', async (msg) => {
  const data = JSON.parse(msg.web_app_data.data);
  const { address, message, signature, publicKey, userId } = data;
  
  // Verify signature
  const { verifySignature } = require('./skills/chia-walletconnect/lib/verify');
  const result = await verifySignature(address, message, signature, publicKey);
  
  if (result.verified) {
    // Wallet verified! Grant access, record verification, etc.
    message({
      action: 'send',
      target: msg.chat.id,
      message: `✅ Wallet verified!\n\nAddress: ${address}`
    });
    
    // Store verification
    // await db.saveVerification(userId, address);
  } else {
    message({
      action: 'send',
      target: msg.chat.id,
      message: `❌ Verification failed: ${result.error}`
    });
  }
});

CLI Usage

The skill includes a CLI for testing:

# Generate challenge message
node cli.js challenge xch1abc... telegram_user_123

# Verify signature manually
node cli.js verify xch1abc... "message" "signature" "pubkey"

# Validate address format
node cli.js validate xch1abc...

# Start development server
node cli.js server

API Reference

MintGarden Signature Verification

Endpoint: POST https://api.mintgarden.io/address/verify_signature

{
  "address": "xch1abc...",
  "message": "Verify ownership of Chia wallet:...",
  "signature": "hex_signature",
  "pubkey": "hex_public_key"
}

Response:

{
  "verified": true
}

CHIP-0002 Methods (WalletConnect)

Method	Purpose
chip0002_getPublicKeys	Fetch public keys from wallet
chip0002_signMessage	Request message signature
chia_getCurrentAddress	Get current receive address

Verification Flow

1. User sends /verify to bot
2. Bot responds with Web App button
3. User taps button → Mini App opens in Telegram
4. Mini App initializes WalletConnect
5. User connects Sage Wallet
6. Challenge message generated (includes nonce + timestamp)
7. User signs message in Sage Wallet
8. Signature sent back to bot via Telegram.WebApp.sendData()
9. Bot verifies signature with MintGarden API
10. Bot confirms verification success/failure

Time: ~5-10 seconds for full flow (user-dependent)

Configuration

Environment Variables

Create .env in skill folder:

PORT=3000
WALLETCONNECT_PROJECT_ID=your-project-id
MINTGARDEN_API_URL=https://api.mintgarden.io

Get WalletConnect Project ID

1. Visit WalletConnect Cloud
2. Create a new project
3. Copy your Project ID
4. Update in webapp/app.js

Default Project ID:
The skill includes 6d377259062295c0f6312b4f3e7a5d9b (Dracattus reference). For production, use your own.

Security

What's Protected

• ✅ Challenge nonces prevent replay attacks
• ✅ Timestamps expire after 5 minutes
• ✅ MintGarden cryptographic verification
• ✅ No private keys ever requested
• ✅ HTTPS enforced by Telegram

Best Practices

1. Store verifications securely — Use encrypted database
2. Rate limit — Prevent spam verification attempts
3. Link to Telegram user ID — Prevent address spoofing
4. Implement cooldown — 1 verification per user per day
5. Log attempts — Audit trail for security

Production Checklist

• Deploy to HTTPS URL (required by Telegram)
• Use your own WalletConnect Project ID
• Enable CORS only for your domain
• Add rate limiting on webhook endpoints
• Store verifications in persistent database
• Implement retry logic for network errors
• Set up monitoring/alerts

Files

chia-walletconnect/
├── webapp/
│   ├── index.html        # Telegram Web App UI
│   ├── app.js            # WalletConnect logic
│   └── styles.css        # Styling
├── lib/
│   ├── challenge.js      # Challenge generation
│   └── verify.js         # MintGarden API client
├── server/
│   └── index.js          # Express webhook server
├── cli.js                # CLI interface
├── package.json          # Dependencies
├── SKILL.md              # This file
└── README.md             # Full documentation

Troubleshooting

Web App Doesn't Load

• Verify HTTPS deployment (Telegram requires SSL)
• Check URL is publicly accessible
• Test URL directly in browser
• Review browser console for errors

WalletConnect Connection Fails

• Ensure Sage Wallet is latest version
• Try manual URI paste instead of QR
• Check WalletConnect Project ID is valid
• Verify Sage supports WalletConnect v2

Signature Verification Fails

• Ensure message format matches exactly
• Confirm public key corresponds to address
• Check MintGarden API is operational
• Verify signature encoding (hex)

"No Public Key" Error

• Some wallets don't expose pubkey via WalletConnect
• Public key is optional for verification
• Signature verification works without it

Examples

Simple Verification Bot

// Clawdbot skill handler

const { verifySignature } = require('./lib/verify');

// /verify command
if (message.text === '/verify') {
  await message({
    action: 'send',
    target: message.chat.id,
    message: 'Verify your Chia wallet:',
    buttons: [[{
      text: '🌱 Connect Wallet',
      web_app: { url: process.env.WEB_APP_URL }
    }]]
  });
}

// Handle web app data
bot.on('web_app_data', async (msg) => {
  const { address, message: challengeMsg, signature, publicKey } = 
    JSON.parse(msg.web_app_data.data);
  
  const result = await verifySignature(address, challengeMsg, signature, publicKey);
  
  if (result.verified) {
    // Grant access
    await grantAccess(msg.from.id, address);
    await message({
      action: 'send',
      target: msg.chat.id,
      message: `✅ Verified! Welcome, ${address.substring(0, 12)}...`
    });
  } else {
    await message({
      action: 'send',
      target: msg.chat.id,
      message: `❌ Verification failed`
    });
  }
});

NFT Gating

// Check if user owns specific NFT collection

const { verifySignature } = require('./skills/chia-walletconnect/lib/verify');
const mintGarden = require('./skills/mintgarden'); // Assume mintgarden skill exists

bot.on('web_app_data', async (msg) => {
  const { address, message, signature, publicKey } = 
    JSON.parse(msg.web_app_data.data);
  
  // Verify signature first
  const verifyResult = await verifySignature(address, message, signature, publicKey);
  
  if (!verifyResult.verified) {
    return bot.sendMessage(msg.chat.id, '❌ Invalid signature');
  }
  
  // Check NFT ownership
  const nfts = await mintGarden.getNFTsByAddress(address);
  const hasRequiredNFT = nfts.some(nft => 
    nft.collection_id === 'col1required...'
  );
  
  if (hasRequiredNFT) {
    // Grant access to private group
    await inviteToGroup(msg.from.id);
    bot.sendMessage(msg.chat.id, '✅ Access granted! Check your invites.');
  } else {
    bot.sendMessage(msg.chat.id, '❌ You need a Wojak NFT to join!');
  }
});

Performance

Stage	Time
WalletConnect Init	~1-2s
Connection Approval	User action
Sign Request	~2-5s
MintGarden Verify	~0.5-1s
Total	~5-10s

Dependencies

• @walletconnect/sign-client — WalletConnect v2
• @walletconnect/utils — WalletConnect helpers
• @walletconnect/types — TypeScript types
• express — Web server
• node-fetch — HTTP client
• cors — CORS middleware
• dotenv — Environment config

Version

1.0.0

License

MIT — Koba42 Corp

Links

• MintGarden API: https://api.mintgarden.io/docs
• WalletConnect: https://docs.walletconnect.com/
• Telegram Web Apps: https://core.telegram.org/bots/webapps
• Sage Wallet: https://www.sagewallet.io/
• CHIP-0002: https://github.com/Chia-Network/chips/blob/main/CHIPs/chip-0002.md

---

Built with 🌱 by Koba42 Corp

🌱 Chia WalletConnect - Telegram Signature Verification

Verify Chia wallet ownership via Telegram using WalletConnect and Sage Wallet.

A Telegram Web App (Mini App) that enables seamless wallet signature verification for Chia blockchain addresses through WalletConnect integration with Sage Wallet, powered by MintGarden's signature verification API.

---

✨ Features

• 🔗 WalletConnect v2 Integration — Industry-standard wallet connection protocol
• 📱 Telegram Mini App — Native in-app experience
• 🔐 Signature Verification — Cryptographic proof of wallet ownership
• ✅ MintGarden API — Trusted signature validation
• 🎯 CHIP-0002 Support — Sage Wallet compatibility
• 💚 Mobile-First — Optimized for Telegram mobile clients
• 🚀 Zero Manual Copy/Paste — Seamless user experience

---

🏗️ Architecture

┌─────────────────┐
│  Telegram Bot   │
│ (Clawdbot)      │
└────────┬────────┘
         │ /verify command
         │ Opens Web App →
         ▼
┌─────────────────────────────┐
│   Telegram Mini App         │
│   (Hosted Web Frontend)     │
│                             │
│  ┌──────────────────────┐  │
│  │  WalletConnect v2    │  │
│  │  Sign Client         │  │
│  └──────────┬───────────┘  │
│             │               │
│             │ Connect & Sign
│             ▼               │
│      ┌──────────────┐      │
│      │ Sage Wallet  │      │
│      │   (Mobile)   │      │
│      └──────┬───────┘      │
│             │               │
│             │ Returns signature
│             ▼               │
│  ┌──────────────────────┐  │
│  │  Send to Bot via     │  │
│  │  Telegram.sendData() │  │
│  └──────────────────────┘  │
└─────────────────────────────┘
              │
              │ web_app_data
              ▼
┌─────────────────────────┐
│  Bot Webhook Handler    │
│  (Verifies signature)   │
└────────┬────────────────┘
         │
         │ POST /verify_signature
         ▼
┌─────────────────────────┐
│  MintGarden API         │
│  (Signature validation) │
└─────────────────────────┘

---

🚀 Quick Start

Installation

# Install skill via ClawdHub
clawdhub install chia-walletconnect

# Install dependencies
cd skills/chia-walletconnect
npm install

# Make CLI executable
chmod +x cli.js

Local Development

# Start the development server
npm start
# Server runs on http://localhost:3000

# Test in browser
open http://localhost:3000

CLI Usage

# Generate a challenge
node cli.js challenge xch1abc... telegram_user_123

# Verify a signature
node cli.js verify xch1abc... "message" "signature" "pubkey"

# Validate address format
node cli.js validate xch1abc...

# Start web server
node cli.js server

---

📱 Telegram Bot Integration

Step 1: Deploy Web App

Deploy the webapp/ folder to a public HTTPS URL:

Option A: Vercel

# Install Vercel CLI
npm i -g vercel

# Deploy
cd webapp
vercel

# Copy the deployment URL (e.g., https://your-app.vercel.app)

Option B: Netlify

# Install Netlify CLI
npm i -g netlify-cli

# Deploy
cd webapp
netlify deploy --prod

# Copy the deployment URL

Option C: Your Own Server

# Run the server on your VPS
npm start

# Use ngrok for testing
ngrok http 3000

Step 2: Register with BotFather

1. Open Telegram and message @BotFather
2. Send /newapp or /editapp
3. Select your bot
4. Web App URL: Enter your deployed URL (e.g., https://your-app.vercel.app)
5. Short Name: verify (or any unique identifier)

Step 3: Add Bot Command

Create a /verify command in your bot:

// In your Clawdbot skill or bot handler

bot.onText(/\/verify/, async (msg) => {
  const chatId = msg.chat.id;
  
  // Send inline button to launch Web App
  bot.sendMessage(chatId, 'Click below to verify your Chia wallet:', {
    reply_markup: {
      inline_keyboard: [[
        {
          text: '🌱 Verify Wallet',
          web_app: { url: 'https://your-app.vercel.app' }
        }
      ]]
    }
  });
});

Step 4: Handle Web App Data

Listen for signature data returned from the Web App:

// Handle web_app_data callback
bot.on('web_app_data', async (msg) => {
  const chatId = msg.chat.id;
  const data = JSON.parse(msg.web_app_data.data);
  
  const { address, message, signature, publicKey, userId } = data;
  
  console.log(`🔐 Received signature from ${address}`);
  
  // Verify signature with MintGarden API
  const { verifySignature } = require('./lib/verify');
  const result = await verifySignature(address, message, signature, publicKey);
  
  if (result.verified) {
    bot.sendMessage(chatId, `✅ Wallet verified!\n\nAddress: ${address}`);
    
    // Store verification in your database
    // await saveVerification(userId, address);
    
  } else {
    bot.sendMessage(chatId, `❌ Verification failed: ${result.error}`);
  }
});

---

🔧 Configuration

Environment Variables

Create a .env file:

# Server configuration
PORT=3000
NODE_ENV=production

# WalletConnect Project ID
# Get yours at https://cloud.walletconnect.com
WALLETCONNECT_PROJECT_ID=6d377259062295c0f6312b4f3e7a5d9b

# Optional: MintGarden API
MINTGARDEN_API_URL=https://api.mintgarden.io

# Optional: Your backend API
BACKEND_API_URL=https://your-backend.com/api

WalletConnect Project ID

The included Project ID (6d377259062295c0f6312b4f3e7a5d9b) is from the Dracattus reference implementation. For production:

1. Visit WalletConnect Cloud
2. Create a new project
3. Copy your Project ID
4. Update in webapp/app.js:

const WALLETCONNECT_PROJECT_ID = 'your-project-id-here';

---

🛠️ API Reference

MintGarden Signature Verification

Endpoint: POST https://api.mintgarden.io/address/verify_signature

Request:

{
  "address": "xch1abc...",
  "message": "Verify ownership of...",
  "signature": "signature_hex",
  "pubkey": "public_key_hex"
}

Response:

{
  "verified": true
}

CHIP-0002 Methods

The skill uses these WalletConnect methods for Sage Wallet:

Method	Description
chip0002_getPublicKeys	Fetch wallet public keys
chip0002_signMessage	Sign a message with wallet
chia_getCurrentAddress	Get current receive address

---

📂 Project Structure

chia-walletconnect/
├── webapp/                   # Telegram Web App frontend
│   ├── index.html           # Main UI
│   ├── app.js               # WalletConnect logic
│   └── styles.css           # Styling
├── lib/                      # Core libraries
│   ├── challenge.js         # Challenge generation
│   ├── verify.js            # MintGarden API client
│   └── telegram.js          # Telegram Web App helpers
├── server/                   # Optional backend
│   └── index.js             # Express server for webhooks
├── cli.js                    # CLI interface
├── package.json             # Dependencies
├── SKILL.md                 # Clawdbot skill documentation
└── README.md                # This file

---

🧪 Testing

Test Locally

1. Start server:

   npm start
   

2. Open in browser:

   http://localhost:3000
   

3. Test WalletConnect:

   • Click "Connect Sage Wallet"
   • Copy the URI or scan QR code
   • Open Sage Wallet → paste URI
   • Approve connection
   • Sign the challenge message

Test with Telegram

1. Use ngrok for local testing:

   ngrok http 3000
   

2. Update BotFather Web App URL to ngrok URL

3. Send /verify in your bot

4. Click the inline button

5. Complete verification flow

---

🔐 Security Considerations

✅ What's Secure

• Challenge Nonces — Prevents replay attacks
• Timestamp Validation — Challenges expire after 5 minutes
• MintGarden Verification — Cryptographic signature validation
• HTTPS Required — Telegram enforces HTTPS for Web Apps
• No Private Keys — Never requests or stores private keys

⚠️ Important Notes

1. Store Verifications Securely

   • Use encrypted database
   • Don't log signatures/public keys
   • Implement rate limiting

2. Validate User Identity

   • Link Telegram user ID to verified address
   • Prevent address spoofing
   • Implement cooldown periods

3. Production Checklist

   • Use your own WalletConnect Project ID
   • Enable CORS only for your domain
   • Implement rate limiting on verification endpoint
   • Log verification attempts for auditing
   • Use environment variables for secrets
   • Deploy behind CDN for DDoS protection

---

💡 Use Cases

1. NFT Gated Chats

Verify users own a specific NFT before granting access to Telegram groups.

2. Airdrop Eligibility

Verify wallet ownership before distributing tokens.

3. Authentication

Use wallet as login credential (Web3-style auth).

4. Proof of Holdings

Verify users hold a minimum XCH balance or specific CATs.

5. DAO Voting

Authenticate voters based on token holdings.

---

🐛 Troubleshooting

Problem: WalletConnect URI Not Working

Solutions:

1. Check Sage Wallet supports WalletConnect v2
2. Try manual URI paste instead of QR scan
3. Ensure Sage is on the latest version
4. Check console for connection errors

Problem: Signature Verification Fails

Solutions:

1. Ensure correct message format (exact match)
2. Verify public key matches address
3. Check MintGarden API status
4. Confirm signature encoding (hex/base64)

Problem: Web App Doesn't Load

Solutions:

1. Verify HTTPS deployment (Telegram requires SSL)
2. Check CORS headers
3. Test URL directly in browser
4. Review Telegram Bot logs

Problem: "No Public Key Available"

Solutions:

1. Sage may not expose public key via WalletConnect
2. Try alternative method (signature still works)
3. Public key is optional for verification

---

🔄 Workflow Diagram

User              Telegram           Web App          Sage Wallet      MintGarden
 │                   │                  │                   │               │
 ├─ /verify ────────>│                  │                   │               │
 │                   ├─ Web App button >│                   │               │
 │                   │                  ├─ WC connect ─────>│               │
 │                   │                  │<── approve ───────┤               │
 │                   │                  ├─ sign request ───>│               │
 │                   │                  │<── signature ─────┤               │
 │                   │<─ sendData() ────┤                   │               │
 │                   ├──────────────────────── verify ──────────────────────>│
 │                   │<──────────────────────── verified ────────────────────┤
 │<─ ✅ Verified ────┤                  │                   │               │
 │                   │                  │                   │               │

---

📊 Performance

Metrics

Stage	Time
WalletConnect Init	~1-2s
Connection Approval	User-dependent
Signature Request	~2-5s
MintGarden Verification	~0.5-1s
Total (optimal)	~5-10s

Optimization Tips

1. Cache WalletConnect sessions — Reconnect faster on repeat use
2. Batch verifications — Verify multiple addresses at once
3. Implement retry logic — Handle transient network errors
4. Use CDN — Serve static assets faster

---

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Submit a pull request

---

📜 License

MIT License — Koba42 Corp

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software.

---

🔗 Links

• MintGarden API: https://api.mintgarden.io/docs
• WalletConnect: https://docs.walletconnect.com/
• Telegram Web Apps: https://core.telegram.org/bots/webapps
• Sage Wallet: https://www.sagewallet.io/
• CHIP-0002: https://github.com/Chia-Network/chips/blob/main/CHIPs/chip-0002.md

---

🌟 Credits

Built by: Koba42 Corp
Inspired by: Dracattus Web App WalletConnect implementation
Powered by: MintGarden API, WalletConnect, Sage Wallet, Telegram Bot API

---

<div align="center">

🌱 Verify with confidence. Own with proof. 🌱

</div>