@navia-labs/qconnect

A comprehensive WalletConnect library for Qubic blockchain integration with React/Next.js, similar to wagmi but specifically designed for Qubic.

Features

• 🚀 WalletConnect v2 Integration - Full support for Qubic WalletConnect protocol
• 🎨 Beautiful UI Components - Pre-built, customizable components using shadcn/ui
• 🔗 React Hooks - wagmi-style hooks for easy integration
• 📱 Mobile-First - Deep linking and QR code support for mobile wallets
• ⚡ TypeScript - Full type safety with comprehensive type definitions
• 🛡️ Error Handling - Robust error boundaries and toast notifications
• 🎯 Zero Config - Works out of the box with sensible defaults

Installation

npm install @navia-labs/qconnect
# or
yarn add @navia-labs/qconnect
# or
bun add @navia-labs/qconnect

Quick Start

1. Wrap your app with the provider

import { QubicWalletConnectProvider } from "@navia-labs/qconnect";

const config = {
  projectId: "your-project-id", // Get from https://cloud.walletconnect.com
  metadata: {
    name: "My Qubic DApp",
    description: "A dApp that uses QConnect",
    url: "https://my-dapp.com",
    icons: ["https://my-dapp.com/icon.png"],
  },
};

function App() {
  return (
    <QubicWalletConnectProvider config={config}>
      <YourDApp />
    </QubicWalletConnectProvider>
  );
}

2. Connect a wallet

import { ConnectButton, WalletModal } from "@navia-labs/qconnect";

function Header() {
  const [modalOpen, setModalOpen] = useState(false);

  return (
    <>
      <ConnectButton onClick={() => setModalOpen(true)}>
        Connect Wallet
      </ConnectButton>
      <WalletModal open={modalOpen} onOpenChange={setModalOpen} />
    </>
  );
}

3. Use hooks to interact with the wallet

import { useAccount, useSendQubic } from "@navia-labs/qconnect";

function SendQubic() {
  const { account, isConnected } = useAccount();
  const { sendQubic, isSending } = useSendQubic();

  const handleSend = async () => {
    if (!account) return;

    try {
      const result = await sendQubic({
        from: account.address,
        to: "RECIPIENT_ADDRESS",
        amount: 1000,
      });
      console.log("Transaction sent:", result);
    } catch (error) {
      console.error("Failed to send:", error);
    }
  };

  if (!isConnected) return <div>Please connect your wallet</div>;

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

Components

ConnectButton

A button that handles wallet connection/disconnection.

<ConnectButton
  onConnect={() => console.log("Connected!")}
  onDisconnect={() => console.log("Disconnected!")}
  className="my-custom-class"
/>

WalletModal

A modal that displays QR codes for wallet connection.

<WalletModal open={modalOpen} onOpenChange={setModalOpen} />

AccountInfo

Displays connected account information and assets.

<AccountInfo showAssets={true} />

TransactionModal

A modal for confirming and signing transactions.

<TransactionModal
  open={transactionModalOpen}
  onOpenChange={setTransactionModalOpen}
  transaction={{
    from: account.address,
    to: recipient,
    amount: 1000,
  }}
  onSuccess={(result) => console.log("Success:", result)}
  onError={(error) => console.error("Error:", error)}
/>

Hooks

useConnect

const { connect, connectors, isConnecting, error } = useConnect();

// Generate QR code for wallet connection
const handleConnect = async () => {
  const uri = await connect();
  // Use the URI to generate a QR code
};

useAccount

const { accounts, isConnected, address, account } = useAccount();

if (isConnected && account) {
  console.log("Connected account:", account.address);
  console.log("Balance:", account.amount);
}

useSendQubic

const { sendQubic, isSending, error } = useSendQubic();

const result = await sendQubic({
  from: "SENDER_ADDRESS",
  to: "RECIPIENT_ADDRESS",
  amount: 1000,
});

useSendTransaction

const { sendTransaction, isSending, error } = useSendTransaction();

const result = await sendTransaction({
  from: "SENDER_ADDRESS",
  to: "RECIPIENT_ADDRESS",
  amount: 1000,
  tick: 123456, // Optional: specific tick
});

useSignMessage

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

const result = await signMessage({
  from: "SIGNER_ADDRESS",
  message: "Hello, Qubic!",
});

useSignTransaction

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

const result = await signTransaction({
  from: "SIGNER_ADDRESS",
  to: "RECIPIENT_ADDRESS",
  amount: 1000,
});

useSendAsset

const { sendAsset, isSending, error } = useSendAsset();

const result = await sendAsset({
  from: "SENDER_ADDRESS",
  to: "RECIPIENT_ADDRESS",
  assetName: "MYTOKEN",
  issuer: "ISSUER_ADDRESS",
  amount: 100,
});

Error Handling

The library includes comprehensive error handling:

import { ErrorBoundary } from "@navia-labs/qconnect";

function App() {
  return (
    <ErrorBoundary>
      <YourAppComponents />
    </ErrorBoundary>
  );
}

Toast Notifications

Toast notifications are built-in for user feedback:

import { ToastContainer } from "@navia-labs/qconnect";

function App() {
  return (
    <>
      <YourApp />
      <ToastContainer />
    </>
  );
}

Configuration

QubicWalletConnectConfig

interface QubicWalletConnectConfig {
  projectId: string; // Required: Get from WalletConnect Cloud
  metadata: {
    name: string;
    description: string;
    url: string;
    icons: string[];
  };
  requiredNamespaces?: {
    qubic: {
      chains: string[];
      methods: string[];
      events: string[];
    };
  };
}

Supported Methods

The library supports all Qubic WalletConnect methods:

• qubic_requestAccounts - Get wallet accounts
• qubic_sendQubic - Send QUBIC tokens
• qubic_signTransaction - Sign a transaction
• qubic_sendTransaction - Send and broadcast a transaction
• qubic_sign - Sign a message
• qubic_sendAsset - Send custom assets

Supported Events

• accountsChanged - Fired when accounts change
• amountChanged - Fired when QUBIC balance changes
• assetAmountChanged - Fired when asset balances change

Styling

The library uses Tailwind CSS and CSS custom properties for theming. You can customize the appearance by overriding the CSS variables:

:root {
  --primary: 221.2 83.2% 53.3%;
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  /* ... other variables */
}

Examples

Check out the example/ directory for a complete working example that demonstrates all features.

License

MIT