@wuwei-labs/srsly 1.0.0-beta.1 → 2.0.0-beta.11

package/README.md

@@ -1,33 +1,711 @@
-# TypeScript SDK Example
+# SRSLY SDK
 
-[![npm version](https://img.shields.io/npm/v/ts-sdk-example.svg)](https://www.npmjs.com/package/ts-sdk-example)
+[![npm version](https://img.shields.io/npm/v/@wuwei-labs/srsly.svg)](https://www.npmjs.com/package/@wuwei-labs/srsly)
+[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Solana](https://img.shields.io/badge/Solana-000?style=flat&logo=solana&logoColor=9945FF)](https://solana.com/)
 
-The TypeScript SDK example has been written for the _The right way to build a TypeScript SDK_ blog.
+A TypeScript SDK for interacting with the SRSLY (Space Rental from SLY) Solana program - a decentralized rental system for Star Atlas fleets with network-specific configuration support.
 
 ## Installation
 
-```shell
-npm install ts-sdk-example
+### NPM
+
+```bash
+npm install @wuwei-labs/srsly
+```
+
+### PNPM
+
+```bash
+pnpm add @wuwei-labs/srsly
+```
+
+### Yarn
+
+```bash
+yarn add @wuwei-labs/srsly
+```
+
+## Quick Start
+
+```typescript
+import { 
+  createContract, 
+  acceptRental,
+  setConfig,
+  setNetwork, 
+  ATLAS_TO_STARDUST
+} from '@wuwei-labs/srsly';
+
+// Option 1: Set global configuration (recommended for most apps)
+setConfig({ network: 'mainnet' });
+// or use the convenience function: setNetwork('mainnet');
+
+// Now all operations use mainnet by default
+const contractInstruction = await createContract({
+  owner: wallet,
+  fleet: fleetAddress,
+  ownerProfile: profileAddress,
+  rate: 1000000, // Rate in ATLAS tokens
+  durationMin: 86400, // 1 day in seconds
+  durationMax: 604800, // 1 week in seconds
+  paymentsFreq: 'daily'
+}); // Uses mainnet from global config
+
+// Accept a rental with automatic ATLAS to stardust conversion
+const acceptInstruction = await acceptRental({
+  borrower: borrowerWallet,
+  borrowerProfile: borrowerProfileAddress,
+  borrowerFaction: 'mud', // or 1, 2, 3
+  fleet: fleetAddress,
+  contract: contractAddress,
+  rate: 100, // ATLAS tokens per duration
+  duration: 86400 // 1 day in seconds
+  // amount is automatically calculated: rate * duration * ATLAS_TO_STARDUST
+}); // Uses mainnet from global config
+
+// Option 2: Override global config for specific instructions
+const devnetInstruction = await createContract(params).set({ network: 'devnet' });
+```
+
+## Core Features
+
+### Contract Management
+
+Create and manage rental contracts for Star Atlas fleets:
+
+```typescript
+import { createContract, closeContract } from '@wuwei-labs/srsly';
+
+// Create a new rental contract with network configuration
+const createIx = await createContract({
+  owner: wallet,
+  fleet: fleetAddress,
+  ownerProfile: profileAddress,
+  rate: 5000000, // Rate in ATLAS tokens
+  durationMin: 86400, // Minimum 1 day
+  durationMax: 2592000, // Maximum 30 days
+  paymentsFreq: 'daily',
+  ownerKeyIndex: 0
+}).set({ network: 'mainnet' }); // Use mainnet configuration
+
+// Close an existing contract using devnet defaults (direct await)
+const closeIx = await closeContract({
+  owner: wallet,
+  fleet: fleetAddress,
+  contract: contractAddress,
+  faction: 'mud' // or faction number: 1, 2, 3
+});
+```
+
+### Rental Operations
+
+Handle rental lifecycle operations with automatic token conversion:
+
+```typescript
+import { 
+  acceptRental, 
+  cancelRental, 
+  closeRental, 
+  resetRental,
+  ATLAS_TO_STARDUST
+} from '@wuwei-labs/srsly';
+
+// Accept a rental offer on devnet (rate-based with automatic conversion)
+const acceptIx = await acceptRental({
+  borrower: borrowerWallet,
+  borrowerProfile: borrowerProfileAddress,
+  borrowerFaction: 'oni', // or faction number: 1=mud, 2=oni, 3=ustur
+  fleet: fleetAddress,
+  contract: contractAddress,
+  rate: 100, // ATLAS tokens (not per second, just ATLAS)
+  duration: 86400 // 1 day in seconds
+  // amount = rate * duration * ATLAS_TO_STARDUST automatically calculated
+}).set({ network: 'devnet' });
+
+// Cancel an active rental using devnet defaults (direct await)
+const cancelIx = await cancelRental({
+  borrower: borrowerWallet,
+  contract: contractAddress,
+  rentalState: rentalStateAddress
+});
+
+// Close a completed rental on mainnet
+const closeIx = await closeRental({
+  borrower: borrowerWallet,
+  contract: contractAddress,
+  rentalState: rentalStateAddress,
+  ownerTokenAccount: ownerTokenAccountAddress
+}).set({ network: 'mainnet' });
+
+// Reset rental state with custom configuration
+const resetIx = await resetRental({
+  fleet: fleetAddress,
+  contract: contractAddress,
+  rentalState: rentalStateAddress,
+  faction: 'mud',
+  ownerProfile: ownerProfileAddress
+}).set({ 
+  network: 'mainnet',
+  sageProgramAddress: 'custom...',
+  gameId: 'custom...'
+});
+```
+
+### Account State Management
+
+Fetch and decode account states using network-specific functions:
+
+```typescript
+import { getCachedNetworkModule } from '@wuwei-labs/srsly';
+
+// Get network-specific account functions (defaults to devnet)
+const accountsModule = await getCachedNetworkModule('accounts');
+const { fetchContractState, fetchRentalState } = accountsModule;
+
+// Or specify network explicitly
+const mainnetAccountsModule = await getCachedNetworkModule('accounts', 'mainnet');
+
+// Fetch contract state
+const contractState = await fetchContractState(rpc, contractPublicKey);
+console.log('Contract rate:', contractState.rate.toString());
+console.log('Duration range:', contractState.durationMin.toString(), '-', contractState.durationMax.toString());
+
+// Fetch rental state
+const rentalState = await fetchRentalState(rpc, rentalPublicKey);
+console.log('Rental status:', rentalState.status);
+console.log('Start time:', new Date(rentalState.startTime.toNumber() * 1000));
+```
+
+### Token Conversion
+
+The SDK includes automatic ATLAS to stardust conversion for rental operations:
+
+```typescript
+import { ATLAS_TO_STARDUST } from '@wuwei-labs/srsly';
+
+// ATLAS_TO_STARDUST = 100_000_000 (1 ATLAS = 100 million stardust)
+console.log('Conversion rate:', ATLAS_TO_STARDUST);
+
+// When using acceptRental with rate and duration:
+// Final amount = rate * duration * ATLAS_TO_STARDUST
+// Example: 100 ATLAS * 86400 seconds * 100_000_000 = 864,000,000,000,000 stardust
+```
+
+## Program Information
+
+- **Program ID**: `SRSLY1fq9TJqCk1gNSE7VZL2bztvTn9wm4VR8u8jMKT`
+- **Network**: Solana Mainnet or Atlasnet
+- **Built with**: Anchor Framework
+
+## Payment Structure
+
+The SRSLY program implements a comprehensive payment system with escrow deposits, periodic payments, fees, and refunds. Understanding this structure is crucial for integrating rental functionality.
+
+### Overview
+
+```text
+Rental Lifecycle:
+1. Escrow Deposit (Full Payment Upfront)
+2. Periodic Payments (Based on Payment Frequency)
+3. Fee Collection (Platform + Referral Fees)
+4. Owner Payments (After Fee Deduction)
+5. Refunds (For Early Cancellation)
+```
+
+### 1. Escrow Deposit
+
+When a borrower accepts a rental, they deposit the **full rental amount upfront** into an escrow account:
+
+```typescript
+// Example: 1000 ATLAS for 10 days = 10,000 ATLAS total
+const acceptIx = await acceptRental({
+  borrower: wallet,
+  borrowerProfile: profileAddress,
+  borrowerFaction: 'mud',
+  fleet: fleetAddress,
+  contract: contractAddress,
+  rate: 1000, // ATLAS tokens per day
+  duration: 864000, // 10 days in seconds
+  referralTokenAccount: referrerAddress // Optional referral
+});
+// Total escrowed: 1000 * 10 * 100,000,000 = 1,000,000,000,000 stardust
+```
+
+**Key Points:**
+
+- Full payment calculated as: `rate × duration × ATLAS_TO_STARDUST`
+- Funds are held in a rental-specific escrow account
+- Escrow is controlled by the rental state PDA
+- No payments to owner until periodic execution
+- **Minimum enforcement**: 24 hours from start time (if no payments) or last payment time
+
+### 2. Periodic Payments
+
+The system creates an automated thread that executes payments based on the contract's payment frequency:
+
+```typescript
+// Contract with daily payments
+const contractIx = await createContract({
+  owner: wallet,
+  fleet: fleetAddress,
+  ownerProfile: profileAddress,
+  rate: 1000,
+  durationMin: 86400, // 1 day minimum
+  durationMax: 2592000, // 30 days maximum  
+  paymentsFreq: 'daily' // Payments every 24 hours
+});
+```
+
+**Payment Schedule:**
+
+- **Daily**: Payments execute daily at 00:00 UTC (not every 24 hours from creation)
+- **Weekly**: Payments execute weekly at specific day/time
+- **Monthly**: Payments execute monthly at specific day/time
+
+**Pro-rata Calculation:**
+
+Each payment is calculated based on elapsed time since the last payment:
+
+```text
+payment_amount = (elapsed_time / frequency_seconds) × rate × ATLAS_TO_STARDUST
+```
+
+### 3. Fee Structure
+
+Each payment is subject to a **10% platform fee** with optional **10% referral sharing**:
+
+```typescript
+// Constants from the program
+const SERVICE_FEE_BPS = 1000;    // 10% platform fee
+const REFERRAL_BPS = 1000;       // 10% of total fee to referral
+const BASE_BPS = 10000;          // 100% in basis points
+```
+
+**Fee Calculation:**
+
+```typescript
+// For each payment amount
+const totalFee = paymentAmount * SERVICE_FEE_BPS / BASE_BPS; // 10% of payment
+const referralFee = totalFee * REFERRAL_BPS / BASE_BPS;     // 10% of total fee
+const platformFee = totalFee - referralFee;                 // 90% of total fee
+const ownerPayment = paymentAmount - totalFee;              // 90% of payment
+```
+
+**Example Payment Breakdown:**
+
+```text
+Payment Amount: 1000 ATLAS
+├── Total Fee (10%): 100 ATLAS
+│   ├── Referral Fee (10% of total fee): 10 ATLAS → Referrer
+│   └── Platform Fee (90% of total fee): 90 ATLAS → Platform
+└── Owner Payment (90%): 900 ATLAS → Fleet Owner
+```
+
+### 4. Payment Distribution
+
+Each periodic payment is distributed in this order:
+
+1. **Referral Payment** (if referrer exists and ≠ system_program::ID)
+   - Amount: `total_fee × REFERRAL_BPS ÷ BASE_BPS`
+   - Destination: Referrer's token account
+
+2. **Platform Fee Payment**
+   - Amount: `total_fee - referral_payment`
+   - Destination: Platform fee account
+
+3. **Owner Payment**
+   - Amount: `payment_amount - total_fee`
+   - Destination: Fleet owner's token account
+
+**Code Example:**
+
+```typescript
+// Accept rental with referral
+const acceptIx = await acceptRental({
+  borrower: wallet,
+  borrowerProfile: profileAddress,
+  borrowerFaction: 'mud',
+  fleet: fleetAddress,
+  contract: contractAddress,
+  rate: 1000,
+  duration: 86400,
+  referralTokenAccount: referrerTokenAccount // 10% of fees
+});
+```
+
+### 5. Refund Mechanism
+
+Refunds occur when rentals are cancelled early or when contracts are closed. **Important: All rentals enforce a minimum 24-hour active period from either the start time (if no payments made) or the last payment time.**
+
+**Early Cancellation:**
+
+```typescript
+const cancelIx = await cancelRental({
+  borrower: wallet,
+  contract: contractAddress,
+  rentalState: rentalStateAddress
+});
+```
+
+**Refund Scenarios:**
+
+- **Before First Payment**: Rental remains active for 24 hours from start time, pro-rata refund for remaining time
+- **After Payment(s) Made**: Rental remains active for 24 hours from last payment time, pro-rata refund for remaining time
+- **Contract Closure**: Any remaining escrow returned to borrower
+
+### 6. Payment Timeline Example
+
+**Scenario**: 10-day rental with daily payments, 1000 ATLAS/day rate
+
+```text
+Day 0: Rental Accepted
+├── Escrow: 10,000 ATLAS deposited
+├── Thread: Created for daily execution at 00:00 UTC
+├── Fleet: Transferred to borrower
+└── Minimum 24-hour commitment begins (from start time)
+
+00:00 UTC Next Day: First Payment
+├── Amount: 1,000 ATLAS from escrow
+├── Total Fee (10%): 100 ATLAS
+│   ├── Referrer: 10 ATLAS (10% of total fee)
+│   └── Platform: 90 ATLAS (90% of total fee)
+├── Owner: 900 ATLAS (90% of payment)
+├── Escrow: 9,000 ATLAS remaining
+└── New 24-hour minimum period begins (from payment time)
+
+Daily at 00:00 UTC: Subsequent Payments
+├── Same distribution pattern
+├── Escrow decreases by 1,000 ATLAS each day
+└── Each payment resets 24-hour minimum period
+
+Final Day at 00:00 UTC: Final Payment & Cleanup
+├── Final payment processed
+├── Thread: Automatically closed
+├── Rental State: Closed, lamports to borrower
+└── Fleet: Returned to owner or contract
+
+Early Cancellation Examples:
+
+Scenario A - Cancel before first payment (Day 0 at 6 PM):
+├── Cancelled 6 hours after start
+├── Rental extends until 24 hours from start time (Day 1 at start time)
+├── Pro-rata refund calculated from Day 1 extended end onwards
+└── Borrower receives refund for Days 1-10
+
+Scenario B - Cancel after payments made (Day 3 at 6 PM):
+├── Cancelled 18 hours after Day 3 payment (00:00 UTC)
+├── Rental extends until 24 hours from last payment (Day 4 at 00:00 UTC)
+├── Pro-rata refund calculated from Day 4 onwards
+└── Borrower receives refund for Days 4-10
+```
+
+### 7. Edge Cases
+
+**Insufficient Escrow Balance:**
+
+- Payment amount is limited to available escrow balance
+- Remaining balance distributed proportionally
+
+**Early Termination:**
+
+- **Cancellation Notice**: Must have more than one payment period remaining to cancel
+- **Minimum Period Enforcement**:
+  - Before first payment: Active for 24 hours from start time
+  - After payment(s): Active for 24 hours from last payment time
+- **Pro-rata Refund**: Refund calculated from the enforced minimum end time
+- Fleet returned to owner when minimum period expires
+- Payment thread continues until minimum period ends
+
+**Contract Closure:**
+
+- Final payment processed if rental active
+- All remaining resources cleaned up
+- Fleet rental capability removed
+
+## Payment Frequencies
+
+The SDK supports multiple payment frequencies:
+
+- `daily` - Daily payments at 00:00 UTC
+- `weekly` - Weekly payments at specific day/time  
+- `monthly` - Monthly payments at specific day/time
+
+## Error Handling
+
+The SDK includes comprehensive error types:
+
+```typescript
+import { SrslyError } from '@wuwei-labs/srsly';
+
+try {
+  const instruction = await createContract({...});
+} catch (error) {
+  if (error instanceof SrslyError) {
+    console.error('SRSLY Error:', error.message);
+    console.error('Error code:', error.code);
+  }
+}
+```
+
+## Network Configuration
+
+The SDK supports both Solana mainnet and devnet with network-specific program configurations. You can set global configuration for convenience or override per instruction for flexibility.
+
+### Global Configuration (Recommended)
+
+Set default configuration once for all SDK operations:
+
+```typescript
+import { setConfig, setNetwork, getConfig, createContract } from '@wuwei-labs/srsly';
+
+// Option 1: Full configuration
+setConfig({ 
+  network: 'mainnet',
+  gameId: 'custom-game-id...' 
+});
+
+// Option 2: Network-only (convenience function)
+setNetwork('mainnet');
+
+// Check current configuration
+console.log(getConfig()); // { network: 'mainnet' }
+
+// All operations now use mainnet by default
+const ix1 = await createContract(params);
+const ix2 = await acceptRental(params);
+```
+
+### Per-Instruction Configuration
+
+Override global configuration for specific instructions using the fluent `.set()` interface:
+
+```typescript
+import { createContract, acceptRental } from '@wuwei-labs/srsly';
+
+// Assume global config is set to mainnet
+setConfig({ network: 'mainnet' });
+
+// Use global mainnet config
+const mainnetIx = await createContract(params);
+
+// Override to use devnet for this specific instruction
+const devnetIx = await createContract(params).set({ network: 'devnet' });
+
+// Override specific constants while keeping global network
+const customIx = await createContract(params).set({ 
+  sageProgramAddress: 'custom...',
+  gameId: 'custom...'
+  // network: 'mainnet' inherited from global config
+});
+```
+
+### Configuration Options
+
+All SDK functions support these usage patterns:
+
+**Direct await (uses global config or devnet fallback):**
+
+```typescript
+// Uses global configuration if set, otherwise devnet
+await createContract(params);
+await acceptRental(params);
+```
+
+**Global configuration functions:**
+
+- `setConfig({ network: 'mainnet', gameId: '...' })` - Set full global config
+- `setNetwork('mainnet')` - Set global network only (convenience)
+- `getConfig()` - Get current global configuration
+- `clearConfig()` - Reset to devnet defaults
+
+**Per-instruction overrides with `.set()` method:**
+
+- `.set({ network: 'mainnet' })` - Override global network
+- `.set({ sageProgramAddress: '...' })` - Override specific constants only
+- `.set({ network: 'mainnet', sageProgramAddress: '...' })` - Multiple overrides
+
+**Chainable configurations:**
+
+```typescript
+// Chain multiple configurations (later ones override earlier ones)
+await createContract(params)
+  .set({ network: 'devnet' })
+  .set({ sageProgramAddress: 'override...' });
+
+// Examples with global config
+setConfig({ network: 'mainnet' });
+await createContract(params); // Uses mainnet
+await acceptRental(params).set({ network: 'devnet' }); // Override to devnet
+await closeContract(params).set({ gameId: 'custom...' }); // Custom gameId, mainnet network
+```
+
+### Available Configuration Options
+
+```typescript
+interface ConfigOptions {
+  network?: 'mainnet' | 'devnet';              // Set/override network
+  sageProgramAddress?: string;                 // Set/override SAGE program address
+  profileFactionProgramAddress?: string;       // Set/override Profile Faction program address  
+  gameId?: string;                            // Set/override SAGE game ID
+}
+```
+
+### Network-Specific Constants
+
+The SDK automatically resolves network-specific constants:
+
+```typescript
+import { 
+  getSageProgramAddress, 
+  getProfileFactionProgramAddress, 
+  getSageGameId 
+} from '@wuwei-labs/srsly';
+
+// Get constants for devnet (default)
+const sageProgram = await getSageProgramAddress();
+const gameId = await getSageGameId();
+
+// Get constants for specific network
+const mainnetSageProgram = await getSageProgramAddress({ network: 'mainnet' });
+const mainnetGameId = await getSageGameId({ network: 'mainnet' });
 ```
 
-## Usage
+## IDL and Types
+
+### Network-Specific IDLs
+
+The SDK provides network-specific IDLs since program configurations differ between networks:
+
+```typescript
+// Mainnet IDL
+import mainnetIdl from '@wuwei-labs/srsly/idl/mainnet';
 
-You can use the `addGreetToMsg` function to get a function that you can call to add that particular greeting to every message, you call that function with.
+// Devnet IDL  
+import devnetIdl from '@wuwei-labs/srsly/idl/devnet';
 
-```ts
-import { addGreetToMsg } from "ts-sdk-example";
+// Use with Anchor
+import { Program } from '@coral-xyz/anchor';
+const program = new Program(mainnetIdl, provider);
+```
+
+### Network-Specific Types
 
-const greetHello = addGreetToMsg("Hello! ");
-const message = "TS SDK";
-const greetMsg = greetHello(message);
+Import TypeScript types that match your target network:
 
-console.log(greetMsg);
+```typescript
+import type { 
+  ContractState,
+  RentalState,
+  PaymentFrequency,
+  ClockData,
+  ThreadResponse,
+  ConfigOptions
+} from '@wuwei-labs/srsly';
 
-// Hello! TS SDK
+// Import network-specific Anchor types
+import type { Srsly as SrslyMainnet } from '@wuwei-labs/srsly/types/mainnet';
+import type { Srsly as SrslyDevnet } from '@wuwei-labs/srsly/types/devnet';
 ```
 
-See the function code [here](./src/utils/greet.ts) to check its implementation.
+## Constants and Utilities
+
+### Available Constants
+
+```typescript
+import { 
+  ATLAS_TO_STARDUST,
+  STARBASE_SEED,
+  STARBASE_PLAYER_SEED,
+  SAGE_PLAYER_PROFILE_SEED,
+  PROFILE_FACTION_SEED,
+  FACTION_MAPPING,
+  FACTION_SPECIFIC_CSS
+} from '@wuwei-labs/srsly';
+
+// Token conversion
+console.log(ATLAS_TO_STARDUST); // 100_000_000
+
+// Faction mappings
+console.log(FACTION_MAPPING[1]); // 'mud'
+console.log(FACTION_MAPPING[2]); // 'oni'  
+console.log(FACTION_MAPPING[3]); // 'ustur'
+```
+
+### Profile Derivation
+
+```typescript
+import { 
+  deriveProfileFaction,
+  deriveSagePlayerProfile,
+  deriveStarbase,
+  deriveStarbasePlayer,
+  deriveGameAccounts
+} from '@wuwei-labs/srsly';
+
+// Derive individual accounts with network configuration
+const profileFaction = await deriveProfileFaction(profile, { network: 'mainnet' });
+const starbase = await deriveStarbase('mud', gameId, { network: 'mainnet' });
+
+// Derive all game accounts at once
+const gameAccounts = await deriveGameAccounts(
+  profile, 
+  'mud', 
+  gameId, 
+  0, // starbaseSeqId
+  { network: 'mainnet' }
+);
+```
+
+## Webpack Compatibility
+
+The SRSLY SDK is fully compatible with webpack bundlers. The package includes both CommonJS and ESM builds:
+
+- **CommonJS**: `./dist/cjs/index.cjs` (default for Node.js and webpack)
+- **ESM**: `./dist/esm/index.js` (for modern ES modules)
+- **Types**: `./dist/types/index.d.ts` (TypeScript definitions)
+
+### Webpack Configuration
+
+For optimal webpack compatibility, the SDK includes:
+
+- `sideEffects: false` for better tree-shaking
+- Proper CommonJS exports with `.cjs` extensions for webpack bundling
+- ES module interoperability
+- Correct module resolution for mixed ESM/CommonJS environments
+
+No special webpack configuration is required. The SDK will work out-of-the-box with most webpack setups.
+
+**Note**: As of version 2.0.0-beta.9, the CommonJS build uses `.cjs` file extensions to ensure proper module resolution in environments where the package.json contains `"type": "module"`.
+
+### Testing Webpack Compatibility
+
+```bash
+# Test local CommonJS exports (fast)
+npm run test:webpack
+
+# Test actual npm package installation (comprehensive)
+npm run test:npm-install
+
+# Test actual pnpm package installation with webpack bundling
+npm run test:pnpm-install
+
+# Test both package managers
+npm run test:package-managers
+```
+
+These commands test different aspects:
+- `test:webpack`: Tests local CommonJS exports that webpack uses
+- `test:npm-install`: Installs the actual published package via npm and tests functionality
+- `test:pnpm-install`: Installs via pnpm and includes a real webpack bundling test
+- `test:package-managers`: Runs both npm and pnpm tests
+
+## Documentation
+
+- **TypeDoc Documentation**: [API Reference](https://wuwei-labs.github.io/srsly/)
 
-## See also
+## Related Projects
 
-TypeDocs - [here](https://hsnice16.github.io/ts-sdk-example/)
+- **Star Atlas**: The metaverse gaming ecosystem
+- **Solana**: The blockchain platform powering SRSLY
+- **Anchor**: The framework used to build the SRSLY program