API Reference - Core (Solana)

Complete API documentation for @alien_org/solana-sso-sdk-core.

AlienSolanaSsoClient

Main client class for Alien Solana SSO authentication with on-chain attestations.

Constructor


new AlienSolanaSsoClient(config: AlienSolanaSsoClientConfig)

Parameters:

config.ssoBaseUrl (string, required): Base URL of the SSO service
config.providerAddress (string, required): Your provider address
config.pollingInterval (number, optional): Polling interval in milliseconds (default: 5000)
config.credentialSignerProgramId (string, optional): Credential Signer program ID (default: 9cstDz8WWRAFaq1vVpTjfHz6tjgh6SJaqYFeZWi1pFHG)
config.sessionRegistryProgramId (string, optional): Session Registry program ID (default: DeHa6pyZ2CFSbQQiNMm7FgoCXqmkX6tXG77C4Qycpta6)
config.sasProgramId (string, optional): SAS program ID (default: 22zoJMtdu4tQc2PzL74ZUT7FrwgB1Udec8DdW4yw4BdG)
config.credentialAuthority (string, optional): Credential authority public key (default: 11111111111111111111111111111111)
config.credentialName (string, optional): Credential name (default: default_credential)
config.schemaName (string, optional): Schema name (default: default_schema)
config.schemaVersion (number, optional): Schema version (default: 1)

Example:


const client = new AlienSolanaSsoClient({
  ssoBaseUrl: 'https://sso.alien-api.com',
  providerAddress: 'your-provider-address',
  pollingInterval: 5000
});

Methods

generateDeeplink()

Initiates attestation creation flow by generating a deep link and polling code. Use this when the wallet doesn’t have an attestation yet.


async generateDeeplink(solanaAddress: string): Promise<SolanaLinkResponse>

Parameters:

solanaAddress (string): User’s Solana wallet public key (base58 string)

Returns: Promise<SolanaLinkResponse>


{
  deep_link: string;      // Deep link for QR code or mobile redirect
  polling_code: string;   // Code for polling authentication status
  expired_at: number;     // Unix timestamp when polling code expires
}

Example:


const userPublicKey = wallet.publicKey.toBase58();
const { deep_link, polling_code, expired_at } = await client.generateDeeplink(userPublicKey);
 
console.log('Deep link:', deep_link);
console.log('Polling code:', polling_code);

Throws:

Network errors if request fails.
Validation errors if the response doesn’t match schema.

pollAuth()

Polls for attestation creation completion status.


async pollAuth(pollingCode: string): Promise<SolanaPollResponse>

Parameters:

pollingCode (string): The polling code from generateDeeplink()

Returns: Promise<SolanaPollResponse>


{
  status: 'pending' | 'authorized' | 'rejected' | 'expired';
  transaction?: string;           // Base64-encoded pre-built transaction
  oracle_signature?: number[];    // Signature bytes for verification
  oracle_public_key?: string;     // Oracle public key (base58)
  timestamp?: number;             // Unix timestamp
  expiry?: number;                // Expiry timestamp
  session_address?: string;       // Session identifier
}

Status Values:

pending: User hasn’t completed attestation creation yet
authorized: User approved attestation creation, transaction data is available
rejected: User denied attestation creation
expired: Polling code expired

Example:


const response = await client.pollAuth(polling_code);
 
if (response.status === 'authorized') {
  console.log('Session address:', response.session_address);
  console.log('Oracle signature:', response.oracle_signature);
  console.log('Timestamp:', response.timestamp);
}

Throws:

Network errors if request fails.
Validation errors if the response doesn’t match schema.

getAttestation()

Checks if a Solana wallet has an attestation on-chain and retrieves the session address. This is the primary method to verify if a user is authenticated.


async getAttestation(solanaAddress: string): Promise<string | null>

Parameters:

solanaAddress (string): User’s Solana wallet public key (base58 string)

Returns: Promise<string | null> - Session address or null if not found

Example:


const sessionAddress = await client.getAttestation(wallet.publicKey.toBase58());
 
if (sessionAddress) {
  console.log('User is authenticated! Session:', sessionAddress);
  // User already has attestation, skip attestation creation flow
} else {
  console.log('No attestation found, need to create one');
  // Start attestation creation flow with generateDeeplink()
}

Throws:

Network errors if request fails

buildCreateAttestationTransaction()

Builds Solana transaction to create on-chain attestation.


async buildCreateAttestationTransaction(params: BuildAttestationParams): Promise<Transaction>

Parameters:


interface BuildAttestationParams {
  connection: Connection;          // Solana RPC connection
  payerPublicKey: PublicKey;       // User's wallet public key
  sessionAddress: string;          // Session address from poll response
  oracleSignature: Uint8Array;     // Oracle signature from poll response
  oraclePublicKey: PublicKey;      // Oracle public key from poll response
  timestamp: number;               // Timestamp from poll response
  expiry: number;                  // Expiry from poll response
}

Returns: Promise<Transaction> - Unsigned Solana transaction ready to be signed and sent

Process:

Fetches on-chain program state to get credential and schema addresses
Derives all necessary PDAs
Creates Ed25519 signature verification instruction
Creates attestation instruction
Returns combined transaction

Example:


import { Connection, PublicKey } from '@solana/web3.js';
 
const connection = new Connection('https://api.mainnet-beta.solana.com');
 
const transaction = await client.buildCreateAttestationTransaction({
  connection,
  payerPublicKey: wallet.publicKey,
  sessionAddress: pollResponse.session_address!,
  oracleSignature: new Uint8Array(pollResponse.oracle_signature!),
  oraclePublicKey: new PublicKey(pollResponse.oracle_public_key!),
  timestamp: pollResponse.timestamp!,
  expiry: pollResponse.expiry!,
});
 
// Sign and send transaction
const signedTx = await wallet.signTransaction(transaction);
const signature = await connection.sendRawTransaction(signedTx.serialize());

Throws:

Error if program state account not found
Error if credential or schema not found
Network errors if RPC request fails

PDA Derivation Utilities

Functions for deriving Program Derived Addresses (PDAs).

deriveProgramStatePda()


function deriveProgramStatePda(programId: PublicKey): [PublicKey, number]

Derives the program state PDA.

Returns: [PublicKey, number] - PDA address and bump seed

deriveCredentialSignerPda()


function deriveCredentialSignerPda(programId: PublicKey): [PublicKey, number]

Derives the credential signer PDA.

deriveSessionRegistryPda()


function deriveSessionRegistryPda(programId: PublicKey): [PublicKey, number]

Derives the session registry PDA.

deriveSessionEntryPda()


function deriveSessionEntryPda(
  sessionAddress: string,
  programId: PublicKey
): [PublicKey, number]

Derives the session entry PDA for a specific session.

Parameters:

sessionAddress (string): Session identifier
programId (PublicKey): Session Registry program ID

deriveSolanaEntryPda()


function deriveSolanaEntryPda(
  userPublicKey: PublicKey,
  programId: PublicKey
): [PublicKey, number]

Derives the Solana entry PDA that maps a Solana address to a session.

Parameters:

userPublicKey (PublicKey): User’s Solana wallet public key
programId (PublicKey): Session Registry program ID

deriveAttestationPda()


function deriveAttestationPda(
  credentialAddress: PublicKey,
  schemaAddress: PublicKey,
  userPublicKey: PublicKey,
  sasProgramId: PublicKey
): [PublicKey, number]

Derives the attestation PDA.

Parameters:

credentialAddress (PublicKey): Credential PDA
schemaAddress (PublicKey): Schema PDA
userPublicKey (PublicKey): User’s wallet public key
sasProgramId (PublicKey): SAS program ID

deriveCredentialPda()


function deriveCredentialPda(
  authorityPublicKey: PublicKey,
  credentialName: string,
  programId: PublicKey
): [PublicKey, number]

Derives the credential PDA.

Parameters:

authorityPublicKey (PublicKey): Credential authority public key
credentialName (string): Credential name
programId (PublicKey): Credential Signer program ID

deriveSchemaPda()


function deriveSchemaPda(
  authorityPublicKey: PublicKey,
  schemaName: string,
  schemaVersion: number,
  programId: PublicKey
): [PublicKey, number]

Derives the schema PDA.

Parameters:

authorityPublicKey (PublicKey): Schema authority public key
schemaName (string): Schema name
schemaVersion (number): Schema version
programId (PublicKey): Credential Signer program ID

Types

AlienSolanaSsoClientConfig


interface AlienSolanaSsoClientConfig {
  ssoBaseUrl: string;
  providerAddress: string;
  pollingInterval?: number;
  credentialSignerProgramId?: string;
  sessionRegistryProgramId?: string;
  sasProgramId?: string;
  credentialAuthority?: string;
  credentialName?: string;
  schemaName?: string;
  schemaVersion?: number;
}

SolanaLinkResponse


interface SolanaLinkResponse {
  deep_link: string;
  polling_code: string;
  expired_at: number;
}

SolanaPollResponse


interface SolanaPollResponse {
  status: 'pending' | 'authorized' | 'rejected' | 'expired';
  transaction?: string;
  oracle_signature?: number[];
  oracle_public_key?: string;
  timestamp?: number;
  expiry?: number;
  session_address?: string;
}

BuildAttestationParams


interface BuildAttestationParams {
  connection: Connection;
  payerPublicKey: PublicKey;
  sessionAddress: string;
  oracleSignature: Uint8Array;
  oraclePublicKey: PublicKey;
  timestamp: number;
  expiry: number;
}

Solana Programs

Credential Signer Program

Program ID: 9cstDz8WWRAFaq1vVpTjfHz6tjgh6SJaqYFeZWi1pFHG

Manages credential signing and schema definitions.

Session Registry Program

Program ID: DeHa6pyZ2CFSbQQiNMm7FgoCXqmkX6tXG77C4Qycpta6

Stores session entries and maps Solana addresses to sessions.

SAS (Solana Attestation Service)

Program ID: 22zoJMtdu4tQc2PzL74ZUT7FrwgB1Udec8DdW4yw4BdG

Creates and manages on-chain attestations linking credentials, schemas, and user addresses.

Error Handling

All async methods can throw errors. Always wrap in try-catch:


try {
  const { deep_link, polling_code } = await client.generateDeeplink(solanaAddress);
} catch (error) {
  console.error('Failed to generate deep link:', error);
}
 
try {
  const transaction = await client.buildCreateAttestationTransaction({
    connection,
    payerPublicKey: wallet.publicKey,
    sessionAddress: pollResponse.session_address!,
    oracleSignature: new Uint8Array(pollResponse.oracle_signature!),
    oraclePublicKey: new PublicKey(pollResponse.oracle_public_key!),
    timestamp: pollResponse.timestamp!,
    expiry: pollResponse.expiry!,
  });
} catch (error) {
  console.error('Transaction building failed:', error);
}

Complete Example


import { AlienSolanaSsoClient } from '@alien_org/solana-sso-sdk-core';
import { Connection, PublicKey, sendAndConfirmTransaction } from '@solana/web3.js';
 
const client = new AlienSolanaSsoClient({
  ssoBaseUrl: 'https://sso.alien-api.com',
  providerAddress: 'your-provider-address',
});
 
const connection = new Connection('https://api.mainnet-beta.solana.com');
 
async function authenticateUser(wallet: any) {
  const solanaAddress = wallet.publicKey.toBase58();
 
  // Check existing attestation
  const existingSession = await client.getAttestation(solanaAddress);
  if (existingSession) {
    console.log('Already authenticated:', existingSession);
    return;
  }
 
  // Generate deep link
  const { deep_link, polling_code } = await client.generateDeeplink(solanaAddress);
  displayQRCode(deep_link);
 
  // Poll for authorization
  const pollInterval = setInterval(async () => {
    const response = await client.pollAuth(polling_code);
 
    if (response.status === 'authorized') {
      clearInterval(pollInterval);
 
      // Build attestation transaction
      const transaction = await client.buildCreateAttestationTransaction({
        connection,
        payerPublicKey: wallet.publicKey,
        sessionAddress: response.session_address!,
        oracleSignature: new Uint8Array(response.oracle_signature!),
        oraclePublicKey: new PublicKey(response.oracle_public_key!),
        timestamp: response.timestamp!,
        expiry: response.expiry!,
      });
 
      // Sign and send
      const signedTx = await wallet.signTransaction(transaction);
      const signature = await sendAndConfirmTransaction(connection, signedTx, []);
 
      console.log('Attestation created! Signature:', signature);
 
      // Verify
      const sessionAddress = await client.getAttestation(solanaAddress);
      console.log('Verified session:', sessionAddress);
 
      hideQRCode();
    } else if (response.status === 'rejected' || response.status === 'expired') {
      clearInterval(pollInterval);
      console.error('Authentication failed:', response.status);
      hideQRCode();
    }
  }, 5000);
}

Next Steps

API Reference - React - Complete API documentation for React SDK.
Core Integration Guide - For vanilla JavaScript/TypeScript projects.
Demo App - Example implementation and source code.