name: vultisig-wallet description: MPC agentic wallet for Solana - agent proposes transactions, human approves on mobile license: MIT compatibility: openclaw metadata: category: finance security: high chain: solana requires_human_approval: true

Vultisig Agentic Wallet

A secure MPC wallet skill where:

• You (the agent) hold one key shard
• The user holds one key shard on their Vultisig mobile app
• Neither party can spend alone - both signatures required (2-of-2)

Security Model

⚠️ CRITICAL: You can PROPOSE transactions but CANNOT execute without user approval.

• Your vault shard is encrypted with the user's password
• User reviews every transaction on their mobile before signing
• Even if you are compromised, funds are safe without mobile approval
• Private key is NEVER reconstructed - MPC signing keeps shards separate

Capabilities

1. Create Wallet

Creates a new 2-of-2 secure vault. Returns a QR code payload for user to scan.

When to use: User explicitly asks to create/setup a wallet

Process:

1. Ask user for a vault name and encryption password
2. Call the create-vault script
3. Display the returned QR payload to user
4. Wait for user to scan with Vultisig mobile app
5. Confirm when vault creation is complete

2. Initiate Transaction

Prepares a SOL transfer and generates signing QR for mobile approval.

When to use: User asks to send/transfer SOL

Process:

1. Confirm destination address and amount with user
2. Call the initiate-transaction script
3. Display the signing QR payload to user
4. User reviews and approves on mobile
5. Transaction is broadcast automatically after approval

3. Get Wallet Address

Returns the Solana address of the current vault.

When to use: User asks for their wallet/deposit address

4. Check Vault Status

Checks if a vault exists and is accessible.

When to use: At conversation start or when user asks about wallet status

Scripts

Located in src/ directory:

| Script | Purpose | Returns | |--------|---------|---------| | create-vault.ts | Initialize new 2-of-2 vault | QR code + display message | | initiate-tx.ts | Prepare and sign transaction (with auto-retry) | QR code + display message | | get-address.ts | Get Solana deposit address | Address string | | check-status.ts | Verify vault accessibility | Status object | | qr-utils.ts | QR code generation utilities | Multiple QR formats | | storage.ts | File-based storage with proper indexing | Storage adapter | | errors.ts | Typed errors for better handling | Error classes |

Key Functions

sendSolWithRetry() - Recommended for transactions:

const result = await sendSolWithRetry({
  toAddress: 'abc123...',
  amountSol: 0.5,
  password: 'secret',
  maxRetries: 2,              // Auto-retry on blockhash expiration
  signingTimeoutMs: 120000,   // 2 minute timeout
  onProgress: (status) => console.log(status),
  onRetry: (attempt) => console.log(`Retry ${attempt}`),
})

QR Code Display

When vault creation or transaction signing returns a result, use the displayMessage field directly - it contains a ready-to-show markdown message with:

• The QR code image (as markdown image or data URL)
• Clear instructions for the user
• Transaction details (for signing)

Example response structure:

{
  success: true,
  displayMessage: "## 🔐 Scan to Create Vault...[full markdown with QR]",
  qrCode: {
    dataUrl: "data:image/png;base64,...",  // Embed in HTML
    ascii: "█▀▀▀▀▀█...",                   // Terminal fallback
    filePath: "/path/to/qr.png",           // File reference
    markdown: "![QR Code](data:...)"       // Ready for markdown
  }
}

Display priority:

1. Use displayMessage if your UI supports markdown
2. Use qrCode.dataUrl for HTML image embedding
3. Use qrCode.ascii for terminal/text-only display

User Instructions

When helping users, remind them:

1. Download Vultisig app first (iOS/Android)
2. Vault creation requires scanning QR with mobile
3. Every transaction needs mobile approval - this is a security feature
4. Keep mobile accessible when wanting to transact
5. Backup the encrypted vault file is recommended

Error Handling

| Error Code | Meaning | Action | |------------|---------|--------| | NO_VAULT | User hasn't created wallet yet | Guide through creation | | INVALID_PASSWORD | Wrong decryption password | Ask user to re-enter | | SIGNING_TIMEOUT | Mobile approval not received in time | Remind to check mobile | | BLOCKHASH_EXPIRED | Signing took >60 seconds | Auto-retries, then ask user to try again faster | | INSUFFICIENT_BALANCE | Not enough SOL | Show balance, suggest deposit |

Blockhash Expiration

⚠️ Important: Solana blockhashes expire after ~90 seconds. If mobile signing takes longer, the transaction will fail.

Built-in handling:

• Transactions auto-retry up to 2 times on blockhash expiration
• UI shows countdown: "approve within 60 seconds"
• Clear error messages when retries are exhausted

Best practices:

• Remind users to have their phone ready before initiating
• Use sendSolWithRetry() which handles retries automatically
• Consider using durable nonces for very slow signing scenarios

Webhooks (Real-time Notifications)

For agents that need immediate notifications (e.g., to send Telegram messages), the skill supports webhooks.

Enable webhooks:

await initiateTransaction(toAddress, amount, password, {
  webhookUrl: 'http://localhost:18790/webhook/tx',
  txId: 'tx-' + Date.now(),  // Optional, auto-generated if not provided
  webhookEvents: ['signing-complete', 'success'],  // Optional filter
})

Webhook events:

| Event | When | Data | |-------|------|------| | qr-ready | QR code generated | { qrPayload, toAddress, amountSol } | | device-joined | Device joins signing | { deviceId, totalJoined, required } | | signing-complete | All devices signed | { totalJoined, elapsedSeconds } | | broadcast | Transaction broadcasting | { toAddress, amountSol } | | success | Transaction confirmed | { txHash, explorerUrl } | | error | An error occurred | { errorCode, error } | | retry | Retrying (blockhash expired) | { attempt, reason } |

Webhook payload format:

{
  "event": "success",
  "txId": "tx-1706789123456-a1b2c3",
  "timestamp": 1706789123456,
  "data": {
    "txHash": "5xYz...",
    "toAddress": "abc...",
    "amountSol": 0.5,
    "explorerUrl": "https://solscan.io/tx/5xYz..."
  }
}

Example webhook server (for agents):

import { createServer } from 'http'

createServer(async (req, res) => {
  if (req.url === '/webhook/tx') {
    const payload = await readBody(req)
    
    if (payload.event === 'signing-complete') {
      await sendMessage('✅ You signed! Broadcasting...')
    }
    if (payload.event === 'success') {
      await sendMessage(`🎉 Sent! TX: ${payload.data.txHash}`)
    }
    
    res.end('ok')
  }
}).listen(18790)

Example Interactions

Creating a wallet:

User: "Set up a wallet for me"
Agent: "I'll create a secure MPC wallet. What would you like to name it, 
       and please provide an encryption password."
User: "Call it 'Trading Wallet', password is [provided securely]"
Agent: [Executes create-vault script]
Agent: "Scan this QR code with your Vultisig mobile app to complete setup:
       [QR PAYLOAD]
       Let me know once you've scanned it."
User: "Done"
Agent: "Your wallet is ready! Address: 7xKp...3nQm"

Sending SOL:

User: "Send 0.5 SOL to alice.sol"
Agent: "I'll prepare a transfer of 0.5 SOL to alice.sol. 
       Please confirm this is correct."
User: "Yes"
Agent: [Executes initiate-tx script]
Agent: "Transaction prepared. Approve on your Vultisig mobile app:
       [SIGNING QR PAYLOAD]
       Amount: 0.5 SOL
       To: alice.sol"
[User approves on mobile]
Agent: "✓ Transaction sent! TX: 5xYz...hash
       View on Solscan: https://solscan.io/tx/5xYz...hash"