@a3e9-microservices/wallet-auth

Reusable Solana wallet authentication and SBT NFT integration package for A3E9 microservices.

Features

• 🔐 Wallet connection (Phantom, Solflare)
• ✅ Signature verification
• 🎫 SBT NFT lookup and validation
• 💾 Session management
• 📦 TypeScript support
• 🔄 Reusable across frontend and backend

Installation

npm install @a3e9-microservices/wallet-auth

Usage

Client-Side (Frontend)

import { connectWallet, disconnectWallet } from '@a3e9-microservices/wallet-auth/client';

// Connect to Phantom wallet
const connection = await connectWallet('phantom');
console.log('Connected:', connection.publicKey);

// Disconnect
await disconnectWallet('phantom');

Server-Side (Backend)

import { verifySignature, getTokenCustomization } from '@a3e9-microservices/wallet-auth/server';

// Verify wallet signature
const isValid = await verifySignature(publicKey, message, signature);

// Get token customization from SBT NFT
const customization = await getTokenCustomization(walletAddress);

API Reference

Client API

connectWallet(walletType: 'phantom' | 'solflare'): Promise<WalletConnection>

Connect to a Solana wallet.

disconnectWallet(walletType: 'phantom' | 'solflare'): Promise<void>

Disconnect from wallet.

signMessage(walletType: 'phantom' | 'solflare', message: string): Promise<Uint8Array>

Sign a message with the connected wallet.

isWalletInstalled(walletType: 'phantom' | 'solflare'): boolean

Check if a wallet is installed.

saveWalletConnection(publicKey: string, walletType: 'phantom' | 'solflare'): void

Save wallet connection to localStorage.

getSavedWalletConnection(): { publicKey: string; walletType: WalletType } | null

Get saved wallet connection from localStorage.

Server API

verifySignature(publicKey: string, message: string, signature: Uint8Array | string): Promise<boolean>

Verify a wallet signature.

createAuthChallenge(publicKey: string): string

Create an authentication challenge message.

authenticateWallet(publicKey: string, walletType: 'phantom' | 'solflare', message: string, signature: string): Promise<AuthResult>

Authenticate a wallet with signature verification.

findSBTForWallet(walletAddress: string, rpcUrl?: string): Promise<SBTLookupResult>

Find SBT NFT for a wallet address.

getTokenCustomization(walletAddress: string, rpcUrl?: string): Promise<TokenCustomization | null>

Get token customization from SBT NFT.

hasActiveSubscription(walletAddress: string, rpcUrl?: string): Promise<boolean>

Check if wallet has an active subscription.

Types

export type WalletType = 'phantom' | 'solflare';

export interface WalletConnection {
  publicKey: string;
  walletType: WalletType;
  connected: boolean;
}

export interface TokenCustomization {
  tokenAddress: string;
  theme: 'Default' | 'Galaxy' | 'Ocean' | 'Sunset';
  tokenInfo: {
    name: string;
    symbol: string;
    logo: string;
    description: string;
  };
  socialLinks: {
    twitter?: string;
    telegram?: string;
    discord?: string;
    website?: string;
  };
  subscription: {
    tier: 'growth' | 'established' | 'enterprise';
    active: boolean;
    expiresAt?: string;
  };
  createdAt: string;
  updatedAt: string;
}

Integration Examples

React Frontend

import { useState } from 'react';
import { connectWallet, saveWalletConnection } from '@a3e9-microservices/wallet-auth/client';

function WalletButton() {
  const [connected, setConnected] = useState(false);

  const handleConnect = async () => {
    try {
      const connection = await connectWallet('phantom');
      saveWalletConnection(connection.publicKey, connection.walletType);
      setConnected(true);
    } catch (error) {
      console.error('Connection failed:', error);
    }
  };

  return (
    <button onClick={handleConnect}>
      {connected ? 'Connected' : 'Connect Wallet'}
    </button>
  );
}

Express Backend

import express from 'express';
import { authenticateWallet, getTokenCustomization } from '@a3e9-microservices/wallet-auth/server';

const app = express();

app.post('/api/auth/login', async (req, res) => {
  const { publicKey, walletType, message, signature } = req.body;

  const authResult = await authenticateWallet(publicKey, walletType, message, signature);

  if (authResult.success) {
    // Check for existing customization
    const customization = await getTokenCustomization(publicKey);

    res.json({
      success: true,
      session: authResult.session,
      customization,
      isFirstTime: !customization,
    });
  } else {
    res.status(401).json({ error: authResult.error });
  }
});

Environment Variables

SOLANA_RPC_URL=https://api.mainnet-beta.solana.com

License

MIT

Author

A3E9