feat: add Bitcoin plugin with Taproot and Ark

[tiero]

🤖 Bitcoin for AI Agents

This PR enables Eliza agents to handle Bitcoin transactions autonomously through @arklabs/wallet-sdk integration. Agents can now receive payments for services, pay other agents, and manage their Bitcoin wallets with both on-chain and Layer 2 (Ark protocol) support.

🚨 WARNING

Caution: Until an external audit is completed, it is strongly recommended not to use this integration on the main Bitcoin network with more than a negligible amount of BTC.

🔑 Configuration

The plugin requires the following environment variables:

# Required
BITCOIN_PRIVATE_KEY=           # Your Bitcoin private key in WIF format
BITCOIN_NETWORK=              # Network type: bitcoin, testnet, regtest, signet, or mutinynet

# Optional - for Ark L2 support
ARK_SERVER_URL=              # Ark protocol server URL
ARK_SERVER_PUBLIC_KEY=       # Ark server public key for L2 operations

🚀 Available Actions

1. SHOW_BITCOIN_ADDRESSES

// Get both on-chain and off-chain addresses
const addresses = await runtime.triggerAction("SHOW_BITCOIN_ADDRESSES");
// Returns: { onchain: "bc1...", offchain: "ark1..." }

2. BALANCE

// Check wallet balance with USD conversion
const balance = await runtime.triggerAction("BALANCE");
// Returns formatted balance with on-chain/off-chain breakdown and USD values

3. COINS

// List available UTXOs (both on-chain and virtual)
const coins = await runtime.triggerAction("COINS");
// Returns detailed UTXO information

4. SEND_BITCOIN

// Send Bitcoin with various denomination options
await runtime.triggerAction("SEND_BITCOIN", {
  recipient: "bc1...",
  amount: "0.001",           // BTC amount
  amountUSD: "100",         // USD amount (alternative)
  amountSats: "100000"      // Satoshi amount (alternative)
});

🔍 Key Benefits for Agents

1. Autonomous Financial Operations

   • Agents can receive payments for API calls, content generation, or other services
   • Automated payment processing for inter-agent service exchanges
   • Self-managed wallet with balance monitoring

2. Flexible Payment Options

   • Support for both on-chain and Layer 2 transactions
   • USD-denominated transactions with automatic conversion
   • Real-time price awareness for fee estimation

3. Enhanced Security

   • Private key management through environment variables
   • Support for Taproot addresses (P2TR)
   • Optional Layer 2 integration for lower fees and faster transactions

📋 Implementation Status

• Core Bitcoin functionality
• Ark protocol L2 integration
• USD denomination support
• BIP21 URI support
• Silent Payments support (coming soon)
• External security audit
• Complete documentation

🧪 Testing

cd packages/plugin-bitcoin
pnpm test

📚 Example Usage

Here's how to integrate the Bitcoin plugin into your agent:

import { bitcoinPlugin } from "@elizaos/plugin-bitcoin";

const character = {
  // ... other character config
  plugins: [bitcoinPlugin],
};

Basic Transaction Flow

// 1. Check balance
const balance = await runtime.triggerAction("balance");
console.log("Current balance:", balance);

// 2. List available UTXOs
const coins = await runtime.triggerAction("coins");
console.log("Available coins:", coins);

// 3. Send payment
await runtime.triggerAction("SEND_BITCOIN", {
  recipient: "bc1...",
  amountUSD: "50", // Send $50 worth of BTC
});

[github-actions]

Hi @tiero! Welcome to the ai16z community. Thanks for submitting your first pull request; your efforts are helping us accelerate towards AGI. We'll review it shortly. You are now a ai16z contributor!