@wuwei-labs/srsly 2.0.0-beta.4 → 2.0.0-beta.6

package/README.md

@@ -4,7 +4,7 @@
 [![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/)
 
-A TypeScript SDK for interacting with the SRSLY (Space Rental from SLY) Solana program - a decentralized rental system for Star Atlas.
+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
 
@@ -31,14 +31,17 @@ yarn add @wuwei-labs/srsly
 ```typescript
 import { 
   createContract, 
-  acceptRental, 
-  setNetwork
+  acceptRental,
+  setConfig,
+  setNetwork, 
+  ATLAS_TO_STARDUST
 } from '@wuwei-labs/srsly';
 
-// Set global network (optional - defaults to devnet)
-setNetwork('mainnet');
+// Option 1: Set global configuration (recommended for most apps)
+setConfig({ network: 'mainnet' });
+// or use the convenience function: setNetwork('mainnet');
 
-// Create a rental contract using global network setting (direct await)
+// Now all operations use mainnet by default
 const contractInstruction = await createContract({
   owner: wallet,
   fleet: fleetAddress,
@@ -46,25 +49,35 @@ const contractInstruction = await createContract({
   rate: 1000000, // Rate in ATLAS tokens
   durationMin: 86400, // 1 day in seconds
   durationMax: 604800, // 1 week in seconds
-  paymentsFreq: 'daily',
-  ownerKeyIndex: 0
-});
+  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
 
-// Or override network for specific instruction
-const mainnetInstruction = await createContract(params).mainnet();
-const devnetInstruction = await createContract(params).devnet();
+// 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:
+Create and manage rental contracts for Star Atlas fleets:
 
 ```typescript
 import { createContract, closeContract } from '@wuwei-labs/srsly';
 
-// Create a new rental contract with network selection
+// Create a new rental contract with network configuration
 const createIx = await createContract({
   owner: wallet,
   fleet: fleetAddress,
@@ -74,60 +87,69 @@ const createIx = await createContract({
   durationMax: 2592000, // Maximum 30 days
   paymentsFreq: 'daily',
   ownerKeyIndex: 0
-}).mainnet(); // Use mainnet for this instruction
+}).set({ network: 'mainnet' }); // Use mainnet configuration
 
-// Close an existing contract using global network setting (direct await)
+// Close an existing contract using devnet defaults (direct await)
 const closeIx = await closeContract({
   owner: wallet,
   fleet: fleetAddress,
   contract: contractAddress,
-  faction: 'mud',
-  ownerProfile: profileAddress
+  faction: 'mud' // or faction number: 1, 2, 3
 });
 ```
 
 ### Rental Operations
 
-Handle rental lifecycle operations:
+Handle rental lifecycle operations with automatic token conversion:
 
 ```typescript
 import { 
   acceptRental, 
   cancelRental, 
   closeRental, 
-  resetRental 
+  resetRental,
+  ATLAS_TO_STARDUST
 } from '@wuwei-labs/srsly';
 
-// Accept a rental offer on devnet
+// 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,
-  borrowerFaction: 'oni',
-  duration: 86400,
-  amount: 1000000
-}).devnet();
+  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 current network setting (direct await)
+// Cancel an active rental using devnet defaults (direct await)
 const cancelIx = await cancelRental({
   borrower: borrowerWallet,
-  rental: rentalAddress
+  contract: contractAddress,
+  rentalState: rentalStateAddress
 });
 
 // Close a completed rental on mainnet
 const closeIx = await closeRental({
   borrower: borrowerWallet,
-  rental: rentalAddress
-}).mainnet();
+  contract: contractAddress,
+  rentalState: rentalStateAddress,
+  ownerTokenAccount: ownerTokenAccountAddress
+}).set({ network: 'mainnet' });
 
-// Reset rental state (admin only) with specific network
+// Reset rental state with custom configuration
 const resetIx = await resetRental({
   fleet: fleetAddress,
   contract: contractAddress,
   rentalState: rentalStateAddress,
   faction: 'mud',
   ownerProfile: ownerProfileAddress
-}).network('mainnet');
+}).set({ 
+  network: 'mainnet',
+  sageProgramAddress: 'custom...',
+  gameId: 'custom...'
+});
 ```
 
 ### Account State Management
@@ -135,15 +157,15 @@ const resetIx = await resetRental({
 Fetch and decode account states using network-specific functions:
 
 ```typescript
-import { getCachedNetworkModule, setNetwork } from '@wuwei-labs/srsly';
+import { getCachedNetworkModule } from '@wuwei-labs/srsly';
 
-// Set the network first
-setNetwork('mainnet');
-
-// Get network-specific account functions
+// 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());
@@ -155,19 +177,259 @@ 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
-- `weekly` - Weekly payments  
-- `monthly` - Monthly payments
+- `daily` - Daily payments at 00:00 UTC
+- `weekly` - Weekly payments at specific day/time  
+- `monthly` - Monthly payments at specific day/time
 
 ## Error Handling
 
@@ -188,67 +450,125 @@ try {
 
 ## Network Configuration
 
-The SDK supports both Solana mainnet and devnet with network-specific program configurations. You can configure networks globally or per instruction.
+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 Network Configuration
+### Global Configuration (Recommended)
 
-Set the default network for all SDK operations:
+Set default configuration once for all SDK operations:
 
 ```typescript
-import { setNetwork, getNetwork } from '@wuwei-labs/srsly';
+import { setConfig, setNetwork, getConfig, createContract } from '@wuwei-labs/srsly';
+
+// Option 1: Full configuration
+setConfig({ 
+  network: 'mainnet',
+  gameId: 'custom-game-id...' 
+});
 
-// Set global network (defaults to 'devnet')
+// Option 2: Network-only (convenience function)
 setNetwork('mainnet');
 
-// Check current network
-console.log(getNetwork()); // 'mainnet'
+// Check current configuration
+console.log(getConfig()); // { network: 'mainnet' }
 
-// All instructions will now use mainnet by default (direct await)
-const ix = await createContract(params);
+// All operations now use mainnet by default
+const ix1 = await createContract(params);
+const ix2 = await acceptRental(params);
 ```
 
-### Per-Instruction Network Selection
+### Per-Instruction Configuration
 
-Override the network for specific instructions using the fluent interface:
+Override global configuration for specific instructions using the fluent `.set()` interface:
 
 ```typescript
-import { createContract } from '@wuwei-labs/srsly';
+import { createContract, acceptRental } from '@wuwei-labs/srsly';
 
-// Use mainnet for this specific instruction
-const mainnetIx = await createContract(params).mainnet();
+// Assume global config is set to mainnet
+setConfig({ network: 'mainnet' });
 
-// Use devnet for this specific instruction  
-const devnetIx = await createContract(params).devnet();
+// Use global mainnet config
+const mainnetIx = await createContract(params);
 
-// Use a specific network
-const specificIx = await createContract(params).network('mainnet');
+// Override to use devnet for this specific instruction
+const devnetIx = await createContract(params).set({ network: 'devnet' });
 
-// Use global network setting (direct await - no .build() needed!)
-const globalIx = await createContract(params);
+// Override specific constants while keeping global network
+const customIx = await createContract(params).set({ 
+  sageProgramAddress: 'custom...',
+  gameId: 'custom...'
+  // network: 'mainnet' inherited from global config
+});
 ```
 
-### Network Selection Methods
+### Configuration Options
 
 All SDK functions support these usage patterns:
 
-**Direct await (uses global network):**
+**Direct await (uses global config or devnet fallback):**
+
 ```typescript
+// Uses global configuration if set, otherwise devnet
 await createContract(params);
 await acceptRental(params);
 ```
 
-**Network-specific methods:**
-- `.mainnet()` - Build with mainnet configuration
-- `.devnet()` - Build with devnet configuration  
-- `.network(network)` - Build with specified network
-- `.build()` - Build with current global network setting (explicit)
+**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
-// Examples across different functions
-await createContract(params).mainnet();
-await acceptRental(params).devnet();
-await closeContract(params).network('mainnet');
-await resetRental(params); // Direct await uses global network
+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' });
 ```
 
 ## IDL and Types
@@ -279,7 +599,8 @@ import type {
   RentalState,
   PaymentFrequency,
   ClockData,
-  ThreadResponse
+  ThreadResponse,
+  ConfigOptions
 } from '@wuwei-labs/srsly';
 
 // Import network-specific Anchor types
@@ -287,6 +608,55 @@ import type { Srsly as SrslyMainnet } from '@wuwei-labs/srsly/types/mainnet';
 import type { Srsly as SrslyDevnet } from '@wuwei-labs/srsly/types/devnet';
 ```
 
+## 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' }
+);
+```
+
 ## Documentation
 
 - **TypeDoc Documentation**: [API Reference](https://wuwei-labs.github.io/srsly/)
@@ -295,4 +665,4 @@ import type { Srsly as SrslyDevnet } from '@wuwei-labs/srsly/types/devnet';
 
 - **Star Atlas**: The metaverse gaming ecosystem
 - **Solana**: The blockchain platform powering SRSLY
-- **Anchor**: The framework used to build the SRSLY program
+- **Anchor**: The framework used to build the SRSLY program