.sol Resolution

Technical documentation for GotSOL's SNS .sol domain resolution feature, replacing wallet addresses with readable names.

Overview

This feature automatically resolves and displays Solana Name Service (SNS) domains for connected wallets in the site header, replacing truncated wallet addresses with human-readable domain names (e.g., alice.sol instead of 7xKXtg...2iX9).

Implementation

Core Components

1. useSNSDomain Hook (src/hooks/use-sns-domain.ts)

Purpose: React hook for resolving SNS domains from wallet addresses using the official Bonfida SPL Name Service SDK.

Key Features:

• Official Bonfida SDK integration (@bonfida/spl-name-service)

• Reverse lookup: wallet address → domain name

• Forward lookup: domain name → wallet address

• Production-grade caching and error handling

API:

const {
  data: snsDomain,
  isLoading,
  error,
} = useSNSDomain({
  address: walletAddress, // Wallet public key as string
  enabled: !!walletAddress, // Enable/disable queries
});

2. Site Header Integration (src/components/dashboard/dashboard-sidebar/site-header.tsx)

Display Logic:

<span className="font-mono text-mint/80">
  {snsDomain || `${walletAddress?.slice(0, 6)}...${walletAddress?.slice(-4)}`}
</span>

Behavior:

• Shows SNS domain if available

• Falls back to truncated wallet address

• Updates automatically when domain data loads

Technical Architecture

SDK Integration

Dependencies:

• @bonfida/spl-name-service: Official Bonfida SNS SDK for domain resolution

Core Functions:

• reverseLookup(): Address-to-domain resolution

• getDomainKey(): Domain name to key derivation

• NameRegistryState.retrieve(): Registry data fetching

Data Flow

1. Wallet Connection: User connects wallet → public key available

2. Hook Query: useSNSDomain queries SNS reverse registry for domains owned by address

3. Registry Lookup: SDK queries Bonfida program accounts for reverse name records

4. Domain Resolution: Extracts domain name from registry data

5. Ownership Verification: Verifies domain resolves back to wallet address using verifyDomainOwnership

6. UI Update: Header displays verified domain name or fallback address

Caching Strategy

React Query Configuration:

{
  staleTime: 30 * 60 * 1000,        // 30 minutes cache
  refetchInterval: 30 * 60 * 1000,  // Background refetch every 30 minutes
  refetchOnMount: true,             // Refetch on component mount
  refetchOnWindowFocus: false,      // No window focus refetch
  retry: 1,                         // Simple single retry on failure
}

Cache Behavior:

• Fresh Data: Cached for 30 minutes, considered fresh

• Background Updates: Automatic refetch every 30 minutes

• Mount Refetch: Updates when component mounts (page navigation)

• Query Key: ['sns-domain', address] - invalidates on wallet change

Usage Examples

Basic Usage

import { useSNSDomain } from '@/hooks/use-sns-domain';

function WalletDisplay({ address }) {
  const { data: snsDomain, isLoading } = useSNSDomain({
    address,
    enabled: !!address,
  });

  if (isLoading) return <div>Loading...</div>;

  return <div>{snsDomain || `${address?.slice(0, 6)}...${address?.slice(-4)}`}</div>;
}

Domain Verification

import { verifyDomainOwnership } from '@/hooks/use-sns-domain';

const isOwner = await verifyDomainOwnership(
  connection,
  'alice.sol', // Domain name
  walletAddress // Expected owner
);

Address Resolution

import { resolveDomainToAddress } from '@/hooks/use-sns-domain';

const ownerAddress = await resolveDomainToAddress(connection, 'alice.sol');

Performance Characteristics

API Efficiency

• Single Query: Reverse lookup requires one program account query

• Minimal Data: Only fetches necessary registry data

• Cached Results: 30-minute cache reduces API calls

• Background Updates: Non-blocking 30-minute refresh cycle

Error Handling

• Network Failures: Single retry, graceful fallback to address

• Invalid Domains: Returns null, displays truncated address

• SDK Errors: Comprehensive error catching with fallbacks

Limitations & Trade-offs

Update Latency

• New Domains: Appear after 30 minutes (background refetch cycle)

• Domain Changes: Updates within 30-minute window

• No Real-time: No WebSocket or event-driven updates

Scope Limitations

• Single Domain: Returns first found domain (no "primary" selection)

• Reverse Only: Only supports address-to-domain lookup

• Bonfida Only: Uses official Bonfida registry exclusively

Performance Trade-offs

• Cache Duration: 30 minutes balances freshness vs API usage

• Background Polling: Continuous updates without user interaction

• Mount Refetch: Ensures data freshness on navigation

Deployment Considerations

Environment Requirements

• Solana RPC connection (mainnet/devnet)

• Bonfida SPL Name Service SDK

• React Query for caching

Monitoring

• Track SNS API call success rates

• Monitor domain resolution latency

• Alert on SDK integration issues

Future Enhancements

• Real-time domain change detection via transaction monitoring

• "Primary domain" selection logic

• Domain favorites/preferences

• Cross-chain domain support

Security & Privacy

Data Handling

• No sensitive data stored in cache

• Public SNS registry data only

• Client-side resolution (no server-side wallet data)

Trust Model

• Relies on Bonfida SNS program integrity

• Official SDK ensures correct data parsing

• Bidirectional verification: Reverse lookup + forward verification

• Fallback to wallet addresses on verification failures

Testing Strategy

Unit Tests

• SDK integration verification

• Cache behavior validation

• Error handling scenarios

Integration Tests

• End-to-end domain resolution

• Wallet switching scenarios

• Network failure recovery

E2E Tests

• Domain purchase → UI update flow

• Multi-domain wallet handling

• Cross-browser compatibility