StellarConnect 🌟

A multi-wallet connection library for Stellar dApps. Drop-in React hooks, a ready-to-use <WalletButton />, and a clean adapter interface for adding new wallets.

Features

• Multi-wallet adapters — Freighter supported out of the box; extend with any wallet via the WalletAdapter interface
• <WalletButton /> — one component handles connect, disconnect, address display, and balance
• <WalletModal /> — wallet selection modal with installed/not-installed state
• <NetworkBadge /> — coloured badge showing current network (Mainnet/Testnet/Futurenet)
• useWallet — full wallet context: address, status, connect, disconnect, sign
• useBalance — live XLM + asset balances from Horizon with auto-refresh
• useNetwork — current network with isTestnet, isMainnet helpers
• useStellarTx — build, sign, and submit payment transactions in one hook
• Auto-reconnect — restores last session on page reload
• TypeScript-first — full type coverage

Installation

npm install stellar-connect

Quick Start

Wrap your app in <StellarConnectProvider> and drop in <WalletButton />:

import { StellarConnectProvider, WalletButton } from 'stellar-connect';

export default function App() {
  return (
    <StellarConnectProvider>
      <WalletButton />
    </StellarConnectProvider>
  );
}

Hooks

useWallet

const {
  address,       // string | null
  status,        // 'idle' | 'connecting' | 'connected' | 'error'
  network,       // 'TESTNET' | 'MAINNET' | ...
  connect,       // (adapterId?: string) => Promise<void>
  disconnect,    // () => void
  signTransaction, // (xdr, network?) => Promise<string>
  signMessage,   // (message) => Promise<string>
} = useWallet();

useBalance

const { xlmBalance, allBalances, isLoading, error, refresh } = useBalance(
  address,
  'TESTNET',
  30_000, // auto-refresh every 30s
);

useNetwork

const { network, isTestnet, isMainnet, isNetwork } = useNetwork();

useStellarTx

const { sendPayment, signAndSubmit, status, txResult, error, reset } = useStellarTx();

// Send a payment
await sendPayment({
  destination: 'G...',
  amount: '10',
  memo: 'thanks',
});

// Or sign and submit a pre-built XDR
await signAndSubmit(xdrString);

Components

<WalletButton />

<WalletButton label="Connect Wallet" className="my-btn" />

<WalletModal />

<WalletModal open={isOpen} onClose={() => setOpen(false)} />

<NetworkBadge />

<NetworkBadge /> // renders "TESTNET" / "MAINNET" badge

Custom Adapters

Implement WalletAdapter to add any Stellar wallet:

import type { WalletAdapter } from 'stellar-connect';

export const myWalletAdapter: WalletAdapter = {
  id: 'my-wallet',
  name: 'My Wallet',
  icon: 'https://...',
  downloadUrl: 'https://...',
  async isInstalled() { ... },
  async connect() { ... },
  async getAddress() { ... },
  async getNetwork() { ... },
  async signTransaction(xdr, network) { ... },
  async signMessage(message) { ... },
  watch(onChange) { ...; return () => {}; },
  async descriptor() { ... },
};

Then register it:

<StellarConnectProvider adapters={[freighterAdapter, myWalletAdapter]}>
  ...
</StellarConnectProvider>

Utility Functions

import { truncateAddress, txExplorerUrl, isValidStellarAddress } from 'stellar-connect';

truncateAddress('GABC...XYZ')          // 'GABC…XYZ'
txExplorerUrl(hash, 'TESTNET')         // Stellar Expert link
isValidStellarAddress('G...')          // boolean

Project Structure

src/
├── adapters/
│   ├── base.ts          # WalletAdapter interface
│   └── freighter.ts     # Freighter implementation
├── context/
│   └── WalletContext.tsx # StellarConnectProvider
├── hooks/
│   ├── useWallet.ts
│   ├── useBalance.ts
│   ├── useNetwork.ts
│   └── useStellarTx.ts
├── components/
│   ├── WalletButton.tsx
│   ├── WalletModal.tsx
│   └── NetworkBadge.tsx
├── utils/
│   ├── address.ts
│   └── network.ts
├── types.ts
└── index.ts

License

MIT