@zubari/sdk

Multi-chain self-custodial wallet SDK for the Web3 creator economy. Manage Bitcoin, Ethereum, TON, TRON, Solana, and Lightning (Spark) from a single BIP-39 seed phrase.

Features

• Multi-Chain Support: Ethereum, Bitcoin, TON, TRON, Solana, and Lightning (Spark)
• Single Seed Phrase: Derive addresses for all chains from one BIP-39 mnemonic
• Self-Custodial: Your keys, your crypto - encrypted locally with AES-256-GCM
• Creator Economy Protocols: NFTs, Tips, Subscriptions, and Payouts
• TypeScript First: Full type safety with comprehensive type definitions
• React Hooks: Ready-to-use hooks for React applications
• Tether WDK Integration: Powered by Tether's Wallet Development Kit

Installation

# npm
npm install @zubari/sdk

# yarn
yarn add @zubari/sdk

# pnpm
pnpm add @zubari/sdk

Quick Start

Create a New Wallet

import { WalletManager } from '@zubari/sdk';

// Initialize wallet manager
const wallet = new WalletManager({
  network: 'testnet', // or 'mainnet'
});

// Create a new wallet with password protection
const { seed, address } = await wallet.createWallet('your-secure-password');

console.log('Seed phrase (SAVE THIS!):', seed);
console.log('Ethereum address:', address);

// Derive addresses for all supported chains
const addresses = await wallet.deriveAllAddressesWithWdk();

console.log('Multi-chain addresses:', addresses);
// {
//   ethereum: '0x...',
//   bitcoin: 'tb1q...',
//   ton: 'UQ...',
//   tron: 'T...',
//   solana: '...',
//   spark: 'sp1...'
// }

Import Existing Wallet

import { WalletManager } from '@zubari/sdk';

const wallet = new WalletManager({ network: 'testnet' });

// Import from seed phrase
const { address } = await wallet.importWallet(
  'your twelve word seed phrase goes here ...',
  'your-secure-password'
);

// Unlock and derive all addresses
await wallet.unlock('your-secure-password');
const addresses = await wallet.deriveAllAddressesWithWdk();

React Hook Usage

import { useWalletManager } from '@zubari/sdk/react';

function WalletComponent() {
  const {
    state,
    createWallet,
    unlock,
    lock,
    deriveAllAddresses,
  } = useWalletManager({ network: 'testnet' });

  const handleCreate = async () => {
    const { seed, address } = await createWallet('password123');
    console.log('Created wallet:', address);
  };

  return (
    <div>
      <p>Status: {state.isLocked ? 'Locked' : 'Unlocked'}</p>
      <p>Address: {state.address}</p>
      <button onClick={handleCreate}>Create Wallet</button>
    </div>
  );
}

API Reference

WalletManager

The main class for wallet operations.

import { WalletManager } from '@zubari/sdk';

const wallet = new WalletManager({
  network: 'testnet' | 'mainnet',
  rpcUrl?: string,          // Custom RPC URL
  enabledChains?: string[], // Chains to enable
  apiUrl?: string,          // Backend API URL (optional)
});

Methods

| Method | Description | Returns | |--------|-------------|---------| | createWallet(password) | Create new wallet with encrypted seed | { seed, address } | | importWallet(seed, password) | Import existing seed phrase | { address } | | unlock(password) | Unlock wallet | { address } | | lock() | Lock wallet (clear seed from memory) | void | | deleteWallet() | Delete wallet from storage | Promise<void> | | deriveAllAddressesWithWdk() | Derive real addresses using WDK | MultiChainAddresses | | deriveAllAddressesAsync() | Derive with fallback strategies | MultiChainAddresses | | fetchBalance() | Get ETH balance | string | | getState() | Get wallet state | WalletState |

ZubariWallet

High-level wallet class with multi-chain transaction support.

import { ZubariWallet } from '@zubari/sdk';

const zubariWallet = new ZubariWallet({
  seed: 'your seed phrase',
  network: 'testnet',
});

// Send ETH
const tx = await zubariWallet.sendEth({
  to: '0x...',
  amount: '0.1',
});

// Send Bitcoin
const btcTx = await zubariWallet.sendBitcoin({
  to: 'tb1q...',
  amount: '0.001',
});

WdkService

Native Tether WDK integration for address derivation.

import { WdkService } from '@zubari/sdk/services';

const wdk = new WdkService({ network: 'testnet' });

// Generate seed phrase
const seed = await wdk.generateSeedPhrase();

// Initialize and derive addresses
await wdk.initialize(seed);
const addresses = await wdk.deriveAllAddresses();

Protocols

Creator economy protocols for monetization.

import {
  ZubariNFTProtocol,
  ZubariTipsProtocol,
  ZubariSubscriptionProtocol,
  ZubariPayoutsProtocol,
} from '@zubari/sdk/protocols';

// NFT Protocol - Lazy minting with EIP-712 signatures
const nft = new ZubariNFTProtocol(wallet, config);
const voucher = await nft.createLazyMintVoucher(metadata);
const mintedNFT = await nft.redeemVoucher(voucher);

// Tips Protocol - Send tips to creators
const tips = new ZubariTipsProtocol(wallet, config);
await tips.sendTip({ to: '0x...', amount: '1.0', token: 'ETH' });

// Subscription Protocol
const subs = new ZubariSubscriptionProtocol(wallet, config);
await subs.subscribe(planId);

// Payouts Protocol
const payouts = new ZubariPayoutsProtocol(wallet, config);
await payouts.claimEarnings();

Storage

Secure storage adapters for different platforms.

import {
  createSecureStorage,
  WebEncryptedStorageAdapter,
  MemoryStorageAdapter,
} from '@zubari/sdk/storage';

// Auto-detect platform (Web, React Native, Node.js)
const storage = createSecureStorage();

// Or use specific adapter
const webStorage = new WebEncryptedStorageAdapter('app-prefix');
await webStorage.initialize('encryption-password');

Utilities

import {
  formatAddress,
  formatBalance,
  isValidAddress,
  normalizeAddress,
} from '@zubari/sdk';

formatAddress('0x1234...5678');     // '0x1234...5678'
formatBalance(1000000000000000000n); // '1.0000'
isValidAddress('0x...');            // true/false
normalizeAddress('0xABC...');       // '0xabc...'

Supported Chains

| Chain | Derivation Path | Address Format | Testnet | |-------|-----------------|----------------|---------| | Ethereum | m/44'/60'/0'/0/0 | 0x... | Sepolia | | Bitcoin | m/84'/0'/0'/0/0 | bc1q.../tb1q... | Testnet | | TON | m/44'/607'/0' | UQ.../EQ... | Testnet | | TRON | m/44'/195'/0'/0/0 | T... | Shasta | | Solana | m/44'/501'/0'/0' | Base58 | Devnet | | Spark | m/44'/998'/0'/0/0 | sp1... | Testnet |

Security

• AES-256-GCM encryption for seed storage
• PBKDF2 key derivation (100,000 iterations)
• Seeds cleared from memory on lock
• Platform-native secure storage (Keychain/Keystore)
• No private keys transmitted over network

Requirements

• Node.js >= 18.0.0
• React >= 18.0.0 (for React hooks, optional)

TypeScript Support

Full TypeScript support with exported types:

import type {
  WalletState,
  WalletManagerConfig,
  NetworkType,
  MultiChainAddresses,
  NFTMetadata,
  LazyMintVoucher,
  TipData,
  SubscriptionPlan,
  SwapQuote,
} from '@zubari/sdk';

Subpath Exports

Import specific modules for better tree-shaking:

// Core wallet only
import { WalletManager } from '@zubari/sdk/wallet';

// Protocols only
import { ZubariNFTProtocol } from '@zubari/sdk/protocols';

// Services only
import { WdkService } from '@zubari/sdk/services';

// Storage only
import { createSecureStorage } from '@zubari/sdk/storage';

// React hooks only
import { useWalletManager } from '@zubari/sdk/react';

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

MIT - see LICENSE for details.

Links

• GitHub Repository
• Documentation
• Tether WDK