QConnect UI

A comprehensive React library designed to simplify the integration of Qubic wallets into your decentralized applications. This library offers a complete set of React components, hooks, and utilities that handle wallet connections, transaction signing, and account management with minimal configuration required.

Features

This library provides a complete solution for integrating Qubic wallets into React applications with the following capabilities:

• Simple Integration: Easy-to-use React components and hooks for seamless wallet integration
• WalletConnect Protocol: Built-in support for the WalletConnect protocol for secure connections
• Transaction Signing: Secure capabilities for signing transactions and messages
• Balance Management: Real-time balance fetching and display functionality
• Customizable Interface: Fully customizable components using CSS classes and styling options
• Mobile Compatibility: Works seamlessly with mobile wallets and responsive design
• TypeScript Ready: Complete TypeScript support with comprehensive type definitions
• Performance Focused: Optimized state management with efficient re-rendering

Installation

# Using npm
npm install qconnect-ui

# Using yarn
yarn add qconnect-ui

# Using bun
bun add qconnect-ui

Peer Dependencies

Make sure you have the required peer dependencies installed:

npm install react react-dom

Getting Started

Setting up the Wallet Provider

First, wrap your application with the QubicWalletProvider component:

import { QubicWalletProvider } from "qconnect-ui";

function App() {
  return (
    <QubicWalletProvider
      projectId="your-project-id"
      metadata={{
        name: "My Qubic DApp",
        description: "A decentralized application on Qubic",
        url: "https://my-dapp.com",
        icons: ["https://my-dapp.com/icon.png"],
      }}
    >
      <YourDApp />
    </QubicWalletProvider>
  );
}

Adding Connection Components

Use the wallet connection components in your interface:

import { WalletConnectionModal, WalletInfo } from "qconnect-ui";

function Header() {
  return (
    <header>
      <WalletConnectionModal />
      <WalletInfo />
    </header>
  );
}

Using Vault File Connection

For vault file connections, you can use the VaultWalletButton:

import { VaultWalletButton } from "qconnect-ui";

function VaultConnector() {
  const [vaultConfig, setVaultConfig] = useState({
    filePath: "/path/to/vault/file",
    password: "your-vault-password",
  });

  return (
    <VaultWalletButton
      vaultConfig={vaultConfig}
      onConnect={() => console.log("Vault connected!")}
      onError={(error) => console.error("Vault connection failed:", error)}
    />
  );
}

Implementing Transaction Signing

import { useTransactionSigner } from "qconnect-ui";

function SendTransaction() {
  const { signTransaction, isSigning } = useTransactionSigner();

  const handleSend = async () => {
    try {
      const signedTx = await signTransaction({
        to: "DESTINATION_ADDRESS_HERE",
        amount: "1000",
      });

      console.log("Transaction signed:", signedTx);
    } catch (error) {
      console.error("Signing failed:", error);
    }
  };

  return (
    <button onClick={handleSend} disabled={isSigning}>
      {isSigning ? "Signing..." : "Send 1000 QUBIC"}
    </button>
  );
}

API Reference

Provider

QubicWalletProvider Component

This is the main provider component that manages the wallet state and provides context to all child components.

interface QubicWalletProviderProps {
  children: React.ReactNode;
  projectId: string; // Your WalletConnect project ID
  metadata?: {
    name: string;
    description: string;
    url: string;
    icons: string[];
  };
  relayUrl?: string;
  requiredChains?: number[];
  optionalChains?: number[];
  onError?: (error: Error) => void;
}

Hooks

useQubicWallet Hook

The primary hook that provides access to all wallet functionality and state management.

const {
  isConnected,
  isConnecting,
  accounts,
  currentAccount,
  connect,
  disconnect,
  signTransaction,
  signMessage,
  getBalance,
  refreshAccounts,
  error,
} = useQubicWallet();

useWalletConnection Hook

A specialized hook for managing wallet connection state and operations.

const { isConnected, isConnecting, connect, disconnect, error } =
  useWalletConnection();

useWalletAccount Hook

A hook for accessing and managing wallet account information and operations.

const { accounts, currentAccount, switchAccount, hasMultipleAccounts } =
  useWalletAccount();

useWalletBalance(address?, autoRefresh?, refreshInterval?)

Hook for managing balance operations.

const { balance, isLoading, error, refresh } = useWalletBalance(
  address?, // Optional: specific address, defaults to current account
  false,    // Optional: auto-refresh enabled
  30000     // Optional: refresh interval in ms
);

useTransactionSigner()

Hook for transaction signing operations.

const { signTransaction, isSigning, error } = useTransactionSigner();

useMessageSigner()

Hook for message signing operations.

const { signMessage, isSigning, error } = useMessageSigner();

Components

WalletConnectButton Component

A pre-built button component that handles wallet connection and disconnection with appropriate loading states.

interface WalletConnectButtonProps {
  className?: string;
  children?: React.ReactNode;
  onConnect?: () => void;
  onDisconnect?: () => void;
  loadingText?: string;
  connectText?: string;
  disconnectText?: string;
}

WalletConnectionModal

A modal component that allows users to choose between WalletConnect and Vault file connection methods.

interface WalletConnectionModalProps {
  children?: React.ReactNode;
  walletConfig?: WalletConfig;
  onWalletSelect?: (config: WalletConfig) => void;
  className?: string;
}

VaultWalletButton

A button component for connecting via vault file.

interface VaultWalletButtonProps {
  vaultConfig?: VaultConfig;
  onConnect?: () => void;
  onError?: (error: Error) => void;
  className?: string;
  children?: React.ReactNode;
  connectText?: string;
  loadingText?: string;
}

WalletInfo Component

A component that displays current wallet information including account details and balance.

interface WalletInfoProps {
  className?: string;
  showBalance?: boolean;
  showAddress?: boolean;
  formatAddress?: (address: string) => string;
}

TransactionSigner Component

A component that provides a complete transaction signing interface with confirmation flow and security checks.

interface TransactionSignerProps {
  className?: string;
  transaction: TransactionRequest;
  onSign?: (signedTransaction: SignedTransaction) => void;
  onCancel?: () => void;
}

AccountSelector

A dropdown component for switching between multiple accounts.

interface AccountSelectorProps {
  className?: string;
}

Utility Functions

Address Utilities

import { formatAddress, validateAddress } from "qconnect-ui";

// Format address for display
const formatted = formatAddress("A".repeat(60)); // "AAAAAA...AAAA"

// Validate address format
const isValid = validateAddress("A".repeat(60)); // true

Balance Utilities

import { formatBalance } from "qconnect-ui";

// Format balance with symbol
const formatted = formatBalance("1000000", 2, "QUBIC"); // "1,000,000.00 QUBIC"

Transaction Utilities

import { createTransactionRequest } from "qconnect-ui";

// Create validated transaction request
const txRequest = createTransactionRequest(
  "DESTINATION_ADDRESS",
  "1000",
  "optional data"
);

Unit Conversion

import {
  convertQubicUnits,
  formatQubicAmount,
  parseQubicAmount,
} from "qconnect-ui";

// Convert between units
const amount = convertQubicUnits(1000000, "QUBIC", "MILLI_QUBIC"); // 1000

// Format with unit
const formatted = formatQubicAmount(1000000, "MILLI_QUBIC"); // "1000 MILLI_QUBIC"

// Parse amount string
const parsed = parseQubicAmount("1000 MILLI_QUBIC"); // 1000000

Usage Examples

Complete DApp Example

import React, { useState } from "react";
import {
  QubicWalletProvider,
  WalletConnectionModal,
  WalletInfo,
  useTransactionSigner,
  formatBalance,
} from "qconnect-ui";

const PROJECT_ID = "your-walletconnect-project-id";

function TransactionComponent() {
  const { signTransaction, isSigning } = useTransactionSigner();

  const handleSendTip = async () => {
    try {
      const signedTx = await signTransaction({
        to: "TIP_DESTINATION_ADDRESS",
        amount: "100",
      });

      // Send signedTx to your backend or blockchain
      console.log("Signed transaction:", signedTx);
    } catch (error) {
      console.error("Transaction failed:", error);
    }
  };

  return (
    <div>
      <h2>Send Tip</h2>
      <button onClick={handleSendTip} disabled={isSigning}>
        {isSigning ? "Signing..." : "Send 100 QUBIC Tip"}
      </button>
    </div>
  );
}

function App() {
  const [walletConfig, setWalletConfig] = useState({
    type: "walletconnect" as const,
    walletConnect: {
      projectId: PROJECT_ID,
    },
  });

  const handleWalletSelect = (config) => {
    setWalletConfig(config);
  };

  return (
    <QubicWalletProvider
      projectId={PROJECT_ID}
      metadata={{
        name: "Qubic Tip Bot",
        description: "Send tips on Qubic network",
        url: "https://tip-bot.com",
        icons: ["https://tip-bot.com/icon.png"],
      }}
      onError={(error) => console.error("Wallet error:", error)}
    >
      <div className="app">
        <header className="app-header">
          <h1>Qubic Tip Bot</h1>
          <WalletConnectionModal onWalletSelect={handleWalletSelect} />
          <WalletInfo />
        </header>

        <main className="app-main">
          <TransactionComponent />
        </main>
      </div>
    </QubicWalletProvider>
  );
}

export default App;

Custom Styling

/* Customize wallet button */
.wallet-connect-button {
  background: #007bff;
  color: white;
  border: none;
  padding: 12px 24px;
  border-radius: 8px;
  cursor: pointer;
  font-size: 16px;
  transition: background-color 0.2s;
}

.wallet-connect-button:hover {
  background: #0056b3;
}

.wallet-connect-button:disabled {
  background: #6c757d;
  cursor: not-allowed;
}

/* Wallet info styling */
.wallet-info {
  display: flex;
  gap: 16px;
  align-items: center;
  padding: 12px;
  background: #f8f9fa;
  border-radius: 8px;
  margin-top: 12px;
}

.wallet-address,
.wallet-balance {
  font-size: 14px;
}

.wallet-address-label,
.wallet-balance-label {
  font-weight: bold;
  margin-right: 8px;
}

/* Error styling */
.wallet-error {
  color: #dc3545;
  background: #f8d7da;
  border: 1px solid #f5c6cb;
  padding: 8px 12px;
  border-radius: 4px;
  margin-top: 8px;
}

/* Vault wallet styling */
.vault-wallet-container {
  position: relative;
}

.vault-wallet-button {
  background: #10b981;
  color: white;
  border: none;
  padding: 12px 24px;
  border-radius: 8px;
  cursor: pointer;
  font-size: 16px;
  transition: background-color 0.2s;
}

.vault-wallet-button:hover:not(:disabled) {
  background: #059669;
}

.vault-wallet-button:disabled {
  background: #6b7280;
  cursor: not-allowed;
}

.vault-error {
  color: #dc2626;
  background: #fef2f2;
  border: 1px solid #fecaca;
  padding: 8px 12px;
  border-radius: 4px;
  margin-top: 8px;
}

/* Modal styling */
.wallet-connection-modal {
  /* Custom modal styles if needed */
}

Error Handling

The library includes comprehensive error handling with specific error types for different scenarios:

import {
  WalletError,
  WalletConnectionError,
  TransactionSignError,
} from "qconnect-ui";

// In your error handler
const handleError = (error: Error) => {
  if (error instanceof WalletConnectionError) {
    // Handle connection errors
    showNotification("Failed to connect wallet");
  } else if (error instanceof TransactionSignError) {
    // Handle transaction signing errors
    showNotification("Failed to sign transaction");
  } else {
    // Handle other errors
    showNotification("An unexpected error occurred");
  }
};

Advanced Configuration

Custom WalletConnect Configuration

<QubicWalletProvider
  projectId="your-project-id"
  relayUrl="wss://custom-relay.walletconnect.org"
  requiredChains={[1]} // Qubic mainnet
  optionalChains={[2]} // Optional testnet
>
  <YourApp />
</QubicWalletProvider>

Multiple Account Management

import { useWalletAccount, AccountSelector } from "qconnect-ui";

function AccountManager() {
  const { accounts, currentAccount, switchAccount } = useWalletAccount();

  return (
    <div>
      <AccountSelector />
      <div>
        <h3>Current Account</h3>
        <p>Address: {currentAccount?.address}</p>
        <p>Balance: {currentAccount?.balance} QUBIC</p>
      </div>
    </div>
  );
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © Navia Tech

Support

For support, please open an issue on GitHub or contact our support team.

Built for the Qubic ecosystem

Getting Started

After installation, you can start using the library immediately in your React application by following the Quick Start guide above.

For development and building the library:

# Install dependencies
npm install

# Build the library
npm run build

# Run type checking
npm run type-check