Wallet Setup

Wallet Setup

The widget requires Solana wallet providers to function. Set up the wallet context at your application root:

import {
  ConnectionProvider,
  WalletProvider,
} from "@solana/wallet-adapter-react";
import { PhantomWalletAdapter } from "@solana/wallet-adapter-wallets";
import { clusterApiUrl } from "@solana/web3.js";
import "@solana/wallet-adapter-react-ui/styles.css";

const wallets = [new PhantomWalletAdapter()];
const endpoint = clusterApiUrl("devnet");

function App() {
  return (
    <ConnectionProvider endpoint={endpoint}>
      <WalletProvider wallets={wallets} autoConnect>
        {/* Your app with Widget */}
      </WalletProvider>
    </ConnectionProvider>
  );
}

Bitcoin Wallet Connectors

The widget supports multiple Bitcoin wallets through connector classes. You can customize which wallets are available to users by providing a bitcoinWallets array in the config.

Custom Wallet Selection

Specify which wallets to support for your use case:

import {
  UniSatConnector,
  XverseConnector,
  PhantomConnector,
  useDeriveWalletConnector,
} from "@zeus-network/bitcoin-kit-widget/bitcoin-wallet-adapter";

function MyComponent() {
  const deriveWallet = useDeriveWalletConnector(BitcoinNetwork.Testnet);

  const bitcoinWallets = [
    new UniSatConnector(),
    new XverseConnector(),
    new PhantomConnector(),
    ...(deriveWallet ? [deriveWallet] : []), // Add derive wallet if available
  ];

  return (
    <Widget.Popover
      config={{
        bitcoinNetwork: BitcoinNetwork.Testnet,
        solanaNetwork: SolanaNetwork.Devnet,
        bitcoinWallets, // Custom wallet list
      }}
    >
      {/* ... */}
    </Widget.Popover>
  );
}

Available Connectors

import {
  // Production wallets
  PhantomConnector, // Mainnet only
  UniSatConnector, // Mainnet/Testnet
  OKXConnector, // Mainnet/Testnet
  XverseConnector, // Mainnet/Testnet/Regtest

  // Development wallets
  MusesConnector, // Regtest only
  useDeriveWalletConnector, // Hook for derive wallet
} from "@zeus-network/bitcoin-kit-widget/bitcoin-wallet-adapter";

Network-Specific Wallet Setup

Different wallets support different networks. Here are recommended configurations:

Mainnet Configuration

const bitcoinWallets = [
  new PhantomConnector(),
  new UniSatConnector(),
  new OKXConnector(),
  new XverseConnector(),
];

const config = {
  bitcoinNetwork: BitcoinNetwork.Mainnet,
  solanaNetwork: SolanaNetwork.Mainnet,
  bitcoinWallets,
};

Development Configuration

function DevelopmentSetup() {
  const deriveWallet = useDeriveWalletConnector(BitcoinNetwork.Regtest);

  const bitcoinWallets = [
    new XverseConnector(), // Supports Regtest
    new MusesConnector(), // Development-focused
    ...(deriveWallet ? [deriveWallet] : []),
  ];

  return (
    <Widget.Popover
      config={{
        bitcoinNetwork: BitcoinNetwork.Regtest,
        solanaNetwork: SolanaNetwork.Devnet,
        bitcoinWallets,
      }}
    >
      {/* ... */}
    </Widget.Popover>
  );
}

Wallet Detection

The widget automatically detects which wallets are installed and ready:

import { UniSatConnector } from "@zeus-network/bitcoin-kit-widget/bitcoin-wallet-adapter";

const unisatWallet = new UniSatConnector();

// Check if wallet is available
if (unisatWallet.isReady()) {
  console.log("UniSat wallet is installed and ready");
} else {
  console.log("UniSat wallet not found - user will see install prompt");
}

Derive Wallet

The Derive Wallet is a unique feature that creates a Bitcoin wallet derived from your connected Solana wallet. This eliminates the need to install Bitcoin wallet extensions during development and testing.

How It Works

1. Derives Bitcoin Private Key: Uses your Solana wallet’s signature to deterministically generate a Bitcoin private key
2. Creates Bitcoin Addresses: Generates P2PKH, P2WPKH, and P2TR (Taproot) addresses from the derived key
3. Signs Transactions: Can sign PSBTs (Partially Signed Bitcoin Transactions) for Zeus Widget operations
4. Development Focus: Only works on Testnet and Regtest networks for security

Key Benefits

• ✅ No Installation Required: Uses your existing Solana wallet
• ✅ Deterministic: Same Solana wallet always generates the same Bitcoin wallet
• ✅ Full Integration: Works seamlessly with all Zeus Widget features
• ✅ Development Friendly: Perfect for testing and prototyping
• ✅ Secure: Private keys are derived locally and never transmitted

Usage

import { useDeriveWalletConnector } from "@zeus-network/bitcoin-kit-widget/bitcoin-wallet-adapter";

function MyComponent() {
  const deriveWallet = useDeriveWalletConnector(BitcoinNetwork.Regtest);

  // deriveWallet will be null if Solana wallet is not connected
  if (!deriveWallet) {
    return <div>Please connect your Solana wallet first</div>;
  }

  return (
    <Widget.Popover
      config={{
        bitcoinNetwork: BitcoinNetwork.Regtest,
        solanaNetwork: SolanaNetwork.Devnet,
        bitcoinWallets: [deriveWallet],
      }}
    >
      <Widget.Popover.Trigger asChild>
        <button>Open Widget with Derive Wallet</button>
      </Widget.Popover.Trigger>

      <Widget.Portal>
        <Widget.Popover.Content />
      </Widget.Portal>
    </Widget.Popover>
  );
}

Technical Details

• Supported Networks: Regtest only (not Mainnet for security)
• Address Types: Primarily uses P2TR (Taproot) addresses
• Signing: Supports PSBT signing with tweaked keys
• Apollo Integration: Compatible with playground.bitcoin-kit.dev and https://app.apolloportal.io/claim for claiming test funds

Limitations

• Development Only: Not available on Bitcoin Mainnet, only for development purpose
• Solana Dependency: Requires active Solana wallet connection
• Network Restrictions: Cannot switch Bitcoin networks dynamically