> For the complete documentation index, see [llms.txt](https://gotsol.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gotsol.gitbook.io/docs/developers/sns-domain-resolution.md).

# .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**:

```typescript
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**:

```tsx
<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**:

```typescript
{
  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

```tsx
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

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

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

### Address Resolution

```tsx
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