BigBlocks.dev
BigBlocks Docs

YoursWalletConnector

Connect to Yours Wallet browser extension for Bitcoin SV transactions and identity management.

YoursWalletConnector

Connect to Yours Wallet browser extension for Bitcoin SV transactions and identity management. Provides a complete UI for wallet detection, connection management, and error handling.

View YoursWalletConnector examples →

Installation

npm install bigblocks

Usage

import { YoursWalletConnector } from 'bigblocks';

export default function WalletConnect() {
  return (
    <YoursWalletConnector
      onSuccess={(result) => {
        console.log('Connected to Yours Wallet:', result.publicKey);
      }}
      onError={(error) => {
        console.error('Connection failed:', error);
      }}
    />
  );
}

Props

PropTypeDefaultDescription
onSuccess(result: WalletResult) => void-Success callback with wallet data
onError(error: string) => void-Error callback with error message
classNamestring-Additional CSS classes

WalletResult Interface

interface WalletResult {
  publicKey: string;          // Wallet public key
  idKey?: string;             // Optional identity key
  encryptedBackup?: string;   // Optional encrypted backup data
}

Features

  • Extension Detection: Automatically detects Yours Wallet installation
  • Installation Prompts: Guides users to install extension if missing
  • Connection Management: Handles wallet connection flow
  • Error Handling: Comprehensive error messages and recovery options
  • Loading States: Visual feedback during connection process
  • Security: Secure authentication with cryptographic signatures

Examples

Basic Connection

<YoursWalletConnector
  onSuccess={(result) => {
    console.log('Wallet connected!');
    console.log('Public Key:', result.publicKey);
    if (result.idKey) {
      console.log('Identity Key:', result.idKey);
    }
  }}
/>

With Error Handling

<YoursWalletConnector
  onSuccess={(result) => {
    // Store wallet connection
    setWalletConnected(true);
    setPublicKey(result.publicKey);
    
    // Navigate to dashboard
    router.push('/dashboard');
  }}
  onError={(error) => {
    switch (error) {
      case 'EXTENSION_NOT_FOUND':
        toast.error('Please install Yours Wallet extension');
        break;
      case 'WALLET_LOCKED':
        toast.error('Please unlock your Yours Wallet');
        break;
      case 'CONNECTION_REFUSED':
        toast.error('Connection was refused');
        break;
      default:
        toast.error(`Connection failed: ${error}`);
    }
  }}
/>

Custom Styling

<YoursWalletConnector
  className="w-full max-w-md mx-auto"
  onSuccess={(result) => {
    console.log('Connected successfully');
  }}
/>

In Authentication Flow

function WalletAuthPage() {
  const [isConnecting, setIsConnecting] = useState(false);
  const [walletData, setWalletData] = useState(null);

  return (
    <div className="auth-container">
      <h1>Connect Your Wallet</h1>
      <p>Connect your Yours Wallet to get started</p>
      
      <YoursWalletConnector
        onSuccess={(result) => {
          setWalletData(result);
          setIsConnecting(false);
          
          // Create session or redirect
          createWalletSession(result);
        }}
        onError={(error) => {
          setIsConnecting(false);
          setError(error);
        }}
      />
      
      {walletData && (
        <div className="success-message">
          ✅ Wallet connected successfully!
        </div>
      )}
    </div>
  );
}

With Backup Integration

import { YoursWalletConnector, BackupManager } from 'bigblocks';

function WalletSetup() {
  const [backupCreated, setBackupCreated] = useState(false);

  return (
    <div className="space-y-6">
      <YoursWalletConnector
        onSuccess={async (result) => {
          console.log('Wallet connected:', result.publicKey);
          
          // Check if backup exists
          if (result.encryptedBackup) {
            console.log('Backup found, restoring...');
            await restoreFromBackup(result.encryptedBackup);
          } else {
            console.log('No backup found, creating new identity...');
          }
        }}
      />
      
      {backupCreated && (
        <BackupManager
          onBackupCreated={(backup) => {
            console.log('Backup created and saved');
          }}
        />
      )}
    </div>
  );
}

Required Context

The component requires the following providers:

import { 
  BitcoinAuthProvider, 
  BitcoinQueryProvider 
} from 'bigblocks';

function App() {
  return (
    <BitcoinAuthProvider>
      <BitcoinQueryProvider>
        <YoursWalletConnector
          onSuccess={handleWalletConnection}
          onError={handleConnectionError}
        />
      </BitcoinQueryProvider>
    </BitcoinAuthProvider>
  );
}

Browser Extension Requirements

Yours Wallet Extension

The component requires the Yours Wallet browser extension:

  1. Chrome Web Store: Search for "Yours Wallet"
  2. Firefox Add-ons: Available on Mozilla Add-ons
  3. Minimum Version: v1.0.0 or higher

Extension Permissions

The following permissions are requested:

  • Active Tab: Access to current webpage
  • Storage: Local wallet data storage
  • Web Requests: Bitcoin network requests
  • Cryptography: Transaction signing

API Integration

Required Backend Endpoints

The component expects these API endpoints for full functionality:

1. Verify Wallet Connection

POST /api/auth/yours-wallet/verify

Request:
{
  publicKey: string;
  signature: string;
  message: string;
  timestamp: number;
}

Response:
{
  success: boolean;
  walletId: string;
  verified: boolean;
  session?: {
    token: string;
    expiresAt: number;
  };
}

2. Store Wallet Session

POST /api/auth/yours-wallet/session

Request:
{
  publicKey: string;
  walletId: string;
  signature: string;
  metadata?: {
    userAgent: string;
    extensionVersion: string;
  };
}

Response:
{
  sessionId: string;
  token: string;
  expiresAt: number;
}

3. Get Wallet Info

GET /api/wallets/yours-wallet/info?publicKey=<key>

Response:
{
  address: string;
  balance: {
    confirmed: number;
    unconfirmed: number;
    total: number;
  };
  hasBackup: boolean;
  lastActivity: number;
}

Authentication Headers

For authenticated requests after connection:

headers: {
  'X-Auth-Token': '<BSM signature>',
  'X-Wallet-Type': 'yours',
  'X-Public-Key': '<wallet public key>',
  'Content-Type': 'application/json'
}

Error Handling

The component handles various error scenarios:

Common Errors

Error CodeDescriptionUser Action
EXTENSION_NOT_FOUNDYours Wallet not installedInstall extension
WALLET_LOCKEDWallet is lockedUnlock wallet
CONNECTION_REFUSEDUser denied connectionTry again
NETWORK_ERRORNetwork connectivity issuesCheck connection
INVALID_SIGNATURESignature verification failedReconnect wallet
SESSION_EXPIREDWallet session expiredReconnect

Error Recovery

<YoursWalletConnector
  onError={(error) => {
    switch (error) {
      case 'EXTENSION_NOT_FOUND':
        // Show installation guide
        setShowInstallGuide(true);
        break;
        
      case 'WALLET_LOCKED':
        // Prompt to unlock
        toast.error('Please unlock your Yours Wallet and try again');
        break;
        
      case 'CONNECTION_REFUSED':
        // Allow retry
        setConnectionAttempts(prev => prev + 1);
        if (connectionAttempts < 3) {
          toast.error('Connection refused. Please try again.');
        }
        break;
        
      default:
        // Generic error handling
        console.error('Wallet connection error:', error);
        toast.error('Connection failed. Please try again.');
    }
  }}
/>

Security Considerations

  • Private Key Safety: Private keys never leave the wallet extension
  • Signature Verification: All connections verified cryptographically
  • Session Management: Secure session tokens with expiration
  • Permission Model: Users explicitly approve connections
  • Network Security: HTTPS required for all communications

Browser Compatibility

BrowserSupportedExtension Store
Chrome✅Chrome Web Store
Firefox✅Firefox Add-ons
Safari❌Not available
Edge✅Edge Add-ons

Troubleshooting

Extension Not Detected

  1. Verify extension is installed and enabled
  2. Refresh the page
  3. Check browser console for errors
  4. Try disabling/re-enabling extension

Connection Failures

  1. Ensure wallet is unlocked
  2. Check network connectivity
  3. Verify website is not blocked
  4. Clear browser cache and cookies

Performance Issues

  1. Close unnecessary browser tabs
  2. Disable conflicting extensions
  3. Update to latest extension version
  4. Restart browser if needed

WalletOverview

Previous Page