@alien_org/solana-sso-sdk-react

React hooks and components for Alien SSO Solana authentication. Built on top of @alien_org/solana-sso-sdk-core with Solana wallet adapter integration.

⚠️ Alpha Version Notice

This is an early alpha version. The SDK is under active development and may contain bugs or undergo breaking changes. Use with caution in production environments.

Installation

npm install @alien_org/solana-sso-sdk-react @solana/web3.js @solana/wallet-adapter-react

Features

• ✅ Solana wallet integration - Works with any Solana wallet adapter
• ✅ On-chain attestation - Automatic transaction building and signing
• ✅ Grace period handling - Manages RPC indexing delays
• ✅ Pre-built components - Sign-in button and modal
• ✅ React 19 support with modern hooks
• ✅ TypeScript-first with full type safety
• ✅ Persistent sessions - localStorage-backed authentication state

Documentation

📚 Full documentation at dev.alien.org/docs

• Solana React Integration Guide - Complete integration walkthrough
• API Reference - Detailed API documentation
• Demo dApp - Example Solana React application

Core SDK

For vanilla JavaScript/TypeScript usage or custom implementations, see @alien_org/solana-sso-sdk-core.

Authentication Flow

The SDK handles the complete Solana authentication flow automatically:

1. User connects wallet via Solana wallet adapter
2. User clicks Sign In button
3. Modal opens with QR code and deep link
4. User scans QR or opens deep link in Alien App
5. SDK polls for authentication completion
6. On success, builds attestation transaction
7. User signs transaction via wallet
8. Transaction sent and confirmed on Solana
9. Grace period handles RPC indexing delay
10. Auth state updates with session address

Grace Period Mechanism

The SDK implements a 60-second grace period after attestation creation to handle RPC indexing delays:

• After successful attestation, session address is cached for 60 seconds
• During grace period, verifyAttestation() returns cached value immediately
• Background verification runs after grace period expires
• Automatic retry on verification failures

Storage Keys

• alien-sso_solana_authed_address - Authenticated Solana wallet address
• alien-sso_session_address - Session address
• alien-sso_attestation_created_at - Timestamp of attestation creation

Custom Styling

The SDK includes default styles, but you can customize them:

import '@alien_org/solana-sso-sdk-react/dist/style.css'; // Optional: Import default styles

// Override with your own CSS
.alien-solana-sso-button {
  background: your-color;
  /* ... */
}

TypeScript Support

Includes full TypeScript declarations:

import type {
  AlienSolanaSsoClientConfig,
  SolanaAuthState,
  SolanaLinkResponse,
  SolanaPollResponse
} from '@alien_org/solana-sso-sdk-react';

Peer Dependencies

• react ^19.1.1
• react-dom ^19.1.1
• @solana/web3.js - Solana blockchain interaction
• @solana/wallet-adapter-react - Solana wallet adapter

Getting a Provider Address

Register your application at the Developer Portal to get your provider credentials.

Browser Support

• Modern browsers with ES2020+ support
• Chrome, Firefox, Safari, Edge (latest versions)

License

MIT

Links

• Documentation
• GitHub Repository
• NPM Package
• Core SDK