Facility Game Frontend SDK

A TypeScript SDK for interacting with the Facility Game Solana program, designed specifically for frontend applications.

🚀 Features

• Type-safe interfaces for all program instructions and accounts
• PDA derivation utilities for finding program addresses
• Account parsing with automatic deserialization
• Player-focused instruction builders for easy transaction construction
• Constants and enums for game parameters
• Error handling with typed error codes
• No admin operations - designed specifically for frontend/player use

📦 Installation

npm install @facility-game/frontend-sdk

🛠️ Architecture

The SDK is organized into several modules:

Core Components

• FacilityGameSDK: Main SDK class with connection management
• PDAUtils: Utilities for deriving Program Derived Addresses
• AccountParser: Parse on-chain account data into typed objects
• Instruction Builders: Type-safe instruction construction

File Structure

frontend-sdk/
├── src/
│   ├── index.ts              # Main SDK export
│   ├── constants/            # Game constants and enums
│   ├── types/               # TypeScript type definitions
│   ├── utils/               # Utility functions
│   └── instructions/        # Instruction builders
├── examples/                # Usage examples
└── tests/                  # Unit tests

🎮 Basic Usage

Initialize SDK

import { createFacilityGameSDK } from '@facility-game/frontend-sdk';

// Create SDK instance
const sdk = createFacilityGameSDK(
  '4PhqnoTMPqaioAYpA8FBmYoekDAfAZ379jWEPkg41ZFH', // Program ID
  'devnet' // Cluster
);

Player Operations

// Check if user is registered
const isRegistered = await sdk.isUserInitialized(userPublicKey);

// Get user profile
const userState = await sdk.getUserState(userPublicKey);
if (userState) {
  console.log('Referral code:', userState.referralCode);
  console.log('Grow power:', userState.growPower.toString());
  console.log('Claimable rewards:', userState.unclaimedRewards.toString());
}

// Check farm status
const farmSpace = await sdk.getFarmSpace(userPublicKey);
if (farmSpace) {
  console.log('Farm level:', farmSpace.farmLevel);
  console.log('Capacity:', farmSpace.totalCapacity);
}

Web3 Integration

// Service class for React/Next.js
import { FacilityGameService } from '@facility-game/frontend-sdk';

const gameService = new FacilityGameService('devnet');

// Get complete dashboard data
const dashboard = await gameService.getUserDashboard(userPublicKey);

// Build transactions
const joinTx = await gameService.buildJoinTransaction(userPublicKey, 'WEED2024');
const farmTx = await gameService.buildPurchaseFarmTransaction(userPublicKey);

🔧 Utility Functions

PDA Derivation

// Get all PDAs for a user
const pdas = sdk.pdaUtils.getUserPDAs(userPublicKey);
console.log('User state PDA:', pdas.userState[0].toBase58());
console.log('Farm space PDA:', pdas.farmSpace[0].toBase58());

// Get system PDAs
const systemPdas = sdk.pdaUtils.getSystemPDAs();
console.log('Config PDA:', systemPdas.config[0].toBase58());

Account Parsing

// Parse raw account data
const accountInfo = await connection.getAccountInfo(address);
const parsedAccount = sdk.accountParser.parseAccount(accountInfo.data);

Helper Functions

import { toSolLamports, fromSolLamports, formatPublicKey } from '@facility-game/frontend-sdk';

// Convert SOL to lamports
const lamports = toSolLamports(0.5); // 500_000_000

// Convert lamports to SOL
const sol = fromSolLamports(500_000_000); // 0.5

// Format public key for display
const formatted = formatPublicKey(publicKey); // "AZLd...pc1w"

📝 Types

The SDK provides comprehensive TypeScript types for all game entities:

Account Types

• Config: System configuration
• UserState: User account data
• FarmSpace: Farm infrastructure
• SeedPack: VRF-based seed pack
• GlobalStats: Network statistics
• And more...

Instruction Types

• InitializeSystemParams
• PurchaseFarmParams
• PlantSeedsParams
• ClaimRewardsParams
• And more...

🎲 VRF Multi-Call Support

The SDK fully supports Switchboard On-Demand VRF multi-call operations:

VRF Service Class

import { VRFSeedPackService } from '@facility-game/frontend-sdk';

const vrfService = new VRFSeedPackService(
  connection,
  programId,
  switchboardProgramId,
  switchboardQueue
);

// Complete flow with proper multi-call handling
const { purchaseTx, openTx, vrfKeypair } = await vrfService.purchaseAndOpenSeedPack(
  wallet.publicKey,
  packId
);

// Transaction 1: Create VRF + Commit + Purchase (3 instructions)
await wallet.sendTransaction(purchaseTx, connection, {
  signers: [vrfKeypair]
});

// Wait for oracle (~2 seconds)
await vrfService.waitForVRF(wallet.publicKey, packId);

// Transaction 2: Reveal + Open (2 instructions)
await wallet.sendTransaction(openTx, connection);

Manual VRF Flow

// Purchase transaction (must be atomic)
const purchaseTx = new Transaction()
  .add(createVrfIx)      // Switchboard
  .add(commitIx)         // Switchboard
  .add(purchasePackIx);  // Game

// Open transaction (must be atomic)
const openTx = new Transaction()
  .add(revealIx)         // Switchboard
  .add(openPackIx);      // Game

🎯 SDK Features

• ✅ Player-focused operations - No admin functions
• ✅ VRF multi-call support - Proper transaction batching
• ✅ Type-safe interfaces - Full TypeScript support
• ✅ PDA utilities - Automatic address derivation
• ✅ Account parsing - Deserialize on-chain data
• ✅ Service classes - High-level abstractions
• ✅ React integration - Ready for wallet adapters

🤝 Contributing

This SDK is designed to be extended. To add new functionality:

1. Add types to src/types/
2. See release steps in docs/frontend-sdk-release.md when publishing updates.
3. Create instruction builder in src/instructions/
4. Export from main index
5. Add examples to examples/

📄 License

MIT