@wuwei-labs/srsly 2.0.0-beta.3 → 2.0.0-beta.31

package/README.md

@@ -4,307 +4,432 @@
 [![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 building Solana instructions to interact with the SRSLY (Space Rental from SLY) program - a decentralized rental system for Star Atlas fleets.
 
-## Installation
+## What This SDK Does
+
+The SRSLY SDK is a focused instruction builder that helps you create Solana instructions for fleet rentals. It provides:
+
+- ✅ **Instruction Building** - Creates properly formatted Solana instructions using @solana/kit
+- ✅ **Account derivation and validation** - Automatically derives required accounts
+- ✅ **Instruction data encoding** - Handles all the complex encoding for you
+- ✅ **Type-safe parameter handling** - Full TypeScript support with validation
+- ✅ **Duration helper functions** - `days()`, `weeks()`, `months()` for time calculations
+- ✅ **Default Star Atlas Programs** - Support for mainnet, atlasnet, and holosim
+
+**Current Status**: Instruction-only SDK using @solana/kit. Users handle transaction assembly and sending.
 
-### NPM
+## Installation
 
 ```bash
+# Install the SDK (includes @solana/kit as a dependency)
 npm install @wuwei-labs/srsly
 ```
 
-### PNPM
+The SDK uses @solana/kit internally and provides seamless conversion to @solana/web3.js format for browser wallet compatibility.
 
-```bash
-pnpm add @wuwei-labs/srsly
+## Quick Start
+
+### Using with @solana/kit (Default)
+
+```typescript
+import { createContract, setConfig, days } from '@wuwei-labs/srsly';
+
+// 1. Configure SDK for your network
+setConfig({ 
+  programs: 'atlasnet' // or 'mainnet', 'holosim'
+});
+
+// 2. Create an instruction (returns @solana/kit format by default)
+const instruction = await createContract({
+  owner: signer,  // Can be a signer object or string address
+  fleet: "FleetAddress123...",        // String address
+  ownerProfile: "ProfileAddr...",     // String address  
+  rate: 1000000,                      // ATLAS tokens per payment period
+  durationMax: days(7),               // 7 days using helper function
+  paymentsFreq: 'daily'               // Payment frequency
+});
+
+// 3. Add instruction to your transaction and send
+// (Use your preferred transaction building and sending method)
 ```
 
-### Yarn
+### Using with @solana/web3.js (wallet-adapter)
 
-```bash
-yarn add @wuwei-labs/srsly
+```typescript
+import { createContract, setConfig, days } from '@wuwei-labs/srsly';
+import { Transaction, PublicKey } from '@solana/web3.js';
+
+// 1. Configure SDK for your network
+setConfig({ programs: 'atlasnet' });
+
+// 2. Create and convert to web3.js format
+const web3jsInstruction = await createContract({
+  owner: wallet.publicKey.toString(),  // String address
+  fleet: "FleetAddress123...",         // String address
+  ownerProfile: "ProfileAddr...",      // String address
+  rate: 1000000,
+  durationMax: days(7),
+  paymentsFreq: 'daily'
+}).web3js(PublicKey); // Convert to web3.js format with PublicKey instances
+
+// 3. Add to transaction and send
+const transaction = new Transaction().add(web3jsInstruction);
+const signature = await wallet.sendTransaction(transaction, connection);
 ```
 
-## Quick Start
+## Core Features
+
+### Instruction Building & Format Conversion
+
+The SDK creates @solana/kit compatible instructions with seamless web3.js conversion:
+
+- **📦 Instruction-Only**: Focus on instruction building, users handle transaction assembly/sending
+- **🔄 Format Conversion**: Built-in `.web3js(PublicKey)` method for wallet compatibility
+- **🎯 String Addresses**: Simple string-based addressing for all inputs  
+- **⚡ Lightweight**: Uses @solana/kit internally with optional web3.js conversion
+
+### Web3.js Format Conversion
+
+The SDK accepts string addresses as input and provides seamless conversion to @solana/web3.js format for browser wallet compatibility:
 
 ```typescript
-import { Connection, PublicKey } from '@solana/web3.js';
-import { 
-  createContract, 
-  acceptRental, 
-  setNetwork,
-  ContractState,
-  RentalState 
-} from '@wuwei-labs/srsly';
+import { createContract } from '@wuwei-labs/srsly';
+import { Transaction, PublicKey } from '@solana/web3.js';
+
+// Web3.js format with PublicKey instances
+const web3jsInstruction = await createContract({
+  owner: "OwnerAddress123...",     // String address input
+  fleet: "FleetAddress123...",    // String address input
+  ownerProfile: "ProfileAddr...", // String address input
+  rate: 1000000,
+  durationMax: days(7),
+  paymentsFreq: 'daily'
+}).web3js(PublicKey);
+
+// Chain configuration with conversion
+const configuredInstruction = await createContract({
+  owner: "OwnerAddress123...",
+  fleet: "FleetAddress123...",
+  ownerProfile: "ProfileAddr...",
+  rate: 1000000,
+  durationMax: days(7),
+  paymentsFreq: 'daily'
+}).set({ programs: 'mainnet' })
+  .web3js(PublicKey);
+
+// Use in transactions
+const transaction = new Transaction().add(web3jsInstruction);
+```
+
+**Key points:**
 
-// Set global network (optional - defaults to devnet)
-setNetwork('mainnet');
+- SDK inputs are always **string addresses**
+- `.web3js(PublicKey)` converts output to web3.js format with PublicKey instances
+- Use when working with browser wallets (Phantom, Solflare, etc.)
 
-// Create a rental contract using global network setting (direct await)
-const contractInstruction = await createContract({
+### Duration Helper Functions
+
+The SDK provides convenient helper functions for converting time units to seconds:
+
+```typescript
+import { days, weeks, months, hours, minutes, duration } from '@wuwei-labs/srsly';
+
+// Individual helper functions
+const sevenDays = days(7);        // 604800 seconds
+const twoWeeks = weeks(2);        // 1209600 seconds  
+const oneMonth = months(1);       // 2678400 seconds (31 days)
+const sixHours = hours(6);        // 21600 seconds
+const thirtyMinutes = minutes(30); // 1800 seconds
+
+// Using in contract creation
+const contract = await createContract({
   owner: wallet,
   fleet: fleetAddress,
   ownerProfile: profileAddress,
-  rate: 1000000, // Rate in lamports
-  durationMin: 86400, // 1 day in seconds
-  durationMax: 604800, // 1 week in seconds
-  paymentsFreq: 'daily',
-  ownerKeyIndex: 0
+  rate: 1000000,
+  durationMax: weeks(2),        // 2 weeks maximum
+  paymentsFreq: 'daily'
 });
 
-// Or override network for specific instruction
-const mainnetInstruction = await createContract(params).mainnet();
-const devnetInstruction = await createContract(params).devnet();
-```
+// Alternative: use the duration object
+const anotherContract = await createContract({
+  owner: wallet,
+  fleet: fleetAddress,
+  ownerProfile: profileAddress,
+  rate: 500000,
+  durationMax: duration.months(3), // 3 months maximum
+  paymentsFreq: 'weekly'
+});
 
-## Core Features
+// You can still use raw seconds if preferred
+const rawContract = await createContract({
+  owner: wallet,
+  fleet: fleetAddress,
+  ownerProfile: profileAddress,
+  rate: 750000,
+  durationMax: 86400,         // Raw 86400 seconds (1 day)
+  paymentsFreq: 'daily'
+});
+```
 
 ### Contract Management
 
-Create and manage rental contracts for Star Atlas:
-
 ```typescript
-import { createContract, closeContract } from '@wuwei-labs/srsly';
+import { createContract, closeContract, days, months } from '@wuwei-labs/srsly';
 
-// Create a new rental contract with network selection
+// Create rental contract instruction
 const createIx = await createContract({
   owner: wallet,
   fleet: fleetAddress,
   ownerProfile: profileAddress,
-  rate: 5000000, // 0.005 SOL per day
-  durationMin: 86400, // Minimum 1 day
-  durationMax: 2592000, // Maximum 30 days
-  paymentsFreq: 'daily',
-  ownerKeyIndex: 0
-}).mainnet(); // Use mainnet for this instruction
-
-// Close an existing contract using global network setting (direct await)
+  rate: 5000000,
+  durationMax: months(1),  // 30 days using helper function
+  paymentsFreq: 'daily'
+});
+
+// Close contract instruction
 const closeIx = await closeContract({
   owner: wallet,
   fleet: fleetAddress,
-  contract: contractAddress,
-  faction: 'mud',
-  ownerProfile: profileAddress
+  contract: contractAddress
 });
 ```
 
 ### Rental Operations
 
-Handle rental lifecycle operations:
-
 ```typescript
-import { 
-  acceptRental, 
-  cancelRental, 
-  closeRental, 
-  resetRental 
-} from '@wuwei-labs/srsly';
+import { acceptRental, cancelRental, closeRental, resetRental } from '@wuwei-labs/srsly';
+import { Transaction, PublicKey } from '@solana/web3.js';
 
-// Accept a rental offer on devnet
+// Accept rental offer instruction (all addresses are strings)
 const acceptIx = await acceptRental({
-  borrower: borrowerWallet,
-  borrowerProfile: borrowerProfileAddress,
-  contract: contractAddress,
-  borrowerFaction: 'oni',
-  duration: 86400,
-  amount: 1000000
-}).devnet();
+  borrower: borrowerWallet,                // signer object or string address
+  borrowerProfile: borrowerProfileAddress, // string address
+  borrowerFaction: 'mud', // or 1, 2, 3
+  fleet: fleetAddress,                     // string address
+  contract: contractAddress,               // string address
+  rate: 100, // ATLAS per payment period (based on contract's payment frequency)
+  duration: 86400 // Duration in seconds (must be between contract's min/max)
+});
 
-// Cancel an active rental using current network setting (direct await)
+// Cancel active rental instruction
 const cancelIx = await cancelRental({
   borrower: borrowerWallet,
-  rental: rentalAddress
+  contract: contractAddress,
+  rentalState: rentalStateAddress
 });
 
-// Close a completed rental on mainnet
+// Close completed rental instruction
 const closeIx = await closeRental({
   borrower: borrowerWallet,
-  rental: rentalAddress
-}).mainnet();
+  contract: contractAddress,
+  rentalState: rentalStateAddress,
+  ownerTokenAccount: ownerTokenAccountAddress
+});
 
-// Reset rental state (admin only) with specific network
+// Reset rental instruction
 const resetIx = await resetRental({
-  fleet: fleetAddress,
+  borrower: borrowerWallet,
   contract: contractAddress,
-  rentalState: rentalStateAddress,
-  faction: 'mud',
-  ownerProfile: ownerProfileAddress
-}).network('mainnet');
+  rentalState: rentalStateAddress
+});
+
+// Convert any instruction to web3.js format for wallet compatibility
+const web3jsAcceptIx = await acceptRental(params).web3js(PublicKey);
+const web3jsCancelIx = await cancelRental(params).web3js(PublicKey);
+
+// Use in web3.js transactions
+const transaction = new Transaction()
+  .add(web3jsAcceptIx)
+  .add(web3jsCancelIx);
 ```
 
-### Account State Management
+## Configuration
 
-Fetch and decode account states:
+The SDK provides simple configuration for different networks:
 
 ```typescript
-import { ContractState, RentalState } from '@wuwei-labs/srsly';
-
-// Fetch contract state
-const contractAccount = await connection.getAccountInfo(contractPublicKey);
-const contractState = ContractState.fromAccountInfo(contractAccount)[0];
+import { setConfig, getConfig, clearConfig } from '@wuwei-labs/srsly';
+
+// Set network configuration
+setConfig({
+  programs: 'atlasnet', // 'mainnet' | 'atlasnet' | 'holosim'
+  srslyProgramAddress: 'custom-program-address...', // Optional override
+  profileFactionProgramAddress: 'custom-profile-program...', // Optional override
+  gameId: 'custom-game-id...', // Optional override
+  atlasMint: 'custom-atlas-mint...' // Optional override
+});
 
-console.log('Contract rate:', contractState.rate.toString());
-console.log('Duration range:', contractState.durationMin.toString(), '-', contractState.durationMax.toString());
+// Simple network configurations
+setConfig({ programs: 'mainnet' });
+setConfig({ programs: 'atlasnet' });
+setConfig({ programs: 'holosim' });
 
-// Fetch rental state
-const rentalAccount = await connection.getAccountInfo(rentalPublicKey);
-const rentalState = RentalState.fromAccountInfo(rentalAccount)[0];
+// Check current configuration
+console.log(getConfig());
 
-console.log('Rental status:', rentalState.status);
-console.log('Start time:', new Date(rentalState.startTime.toNumber() * 1000));
+// Reset to defaults
+clearConfig();
 ```
 
-## Program Information
-
-- **Program ID**: `SRSLY1fq9TJqCk1gNSE7VZL2bztvTn9wm4VR8u8jMKT`
-- **Network**: Solana Mainnet or Atlasnet
-- **Built with**: Anchor Framework
-
-## Payment Frequencies
-
-The SDK supports multiple payment frequencies:
-
-- `daily` - Daily payments
-- `weekly` - Weekly payments  
-- `monthly` - Monthly payments
+### Configuration Options
 
-## Error Handling
+| Option | Type | Description | Default |
+|--------|------|-------------|---------|
+| `programs` | `'mainnet' \| 'atlasnet' \| 'holosim'` | Predefined program address set | `'atlasnet'` |
+| `srslyProgramAddress` | `string` | SRSLY program address override | From program set |
+| `profileFactionProgramAddress` | `string` | Profile Faction program override | From program set |
+| `gameId` | `string` | SAGE game ID override | From program set |
+| `atlasMint` | `string` | ATLAS token mint override | From program set |
 
-The SDK includes comprehensive error types:
+## Duration and Payment Frequency
 
-```typescript
-import { SrslyError } from '@wuwei-labs/srsly';
+**Important**: All durations must be aligned with the payment frequency to ensure proper payment calculations.
 
-try {
-  const instruction = await createContract({...});
-} catch (error) {
-  if (error instanceof SrslyError) {
-    console.error('SRSLY Error:', error.message);
-    console.error('Error code:', error.code);
-  }
-}
-```
+### Duration Rules
 
-## Network Configuration
+1. **Duration Units**: All durations are specified in seconds
+2. **Alignment Requirement**: Durations must be multiples of the payment frequency interval
+3. **Validation**: The SDK automatically validates duration alignment and throws an error if invalid
 
-The SDK supports both Solana mainnet and devnet with network-specific program configurations. You can configure networks globally or per instruction.
+### Payment Frequency Intervals
 
-### Global Network Configuration
+| Frequency | Interval | Example Valid Durations |
+|-----------|----------|------------------------|
+| `hourly`  | 3,600 seconds (1 hour) | 3,600 (1h), 7,200 (2h), 86,400 (24h) |
+| `daily`   | 86,400 seconds (1 day) | 86,400 (1d), 172,800 (2d), 604,800 (7d) |
+| `weekly`  | 604,800 seconds (1 week) | 604,800 (1w), 1,209,600 (2w), 2,419,200 (4w) |
+| `monthly` | 2,678,400 seconds (31 days) | 2,678,400 (1m), 5,356,800 (2m) |
 
-Set the default network for all SDK operations:
+### Examples
 
 ```typescript
-import { setNetwork, getNetwork } from '@wuwei-labs/srsly';
-
-// Set global network (defaults to 'devnet')
-setNetwork('mainnet');
+// ✅ Valid: 7 day max duration with daily payments
+await createContract({
+  durationMax: 604800,   // 7 days (604800 % 86400 = 0) ✓
+  paymentsFreq: 'daily'  // Min duration automatically set to 1 day
+});
 
-// Check current network
-console.log(getNetwork()); // 'mainnet'
+// ❌ Invalid: 3.5 day max duration with daily payments
+await createContract({
+  durationMax: 302400,   // 3.5 days (302400 % 86400 = 43200) ✗
+  paymentsFreq: 'daily'
+});
+// Error: Duration (302400 seconds) must be a multiple of daily frequency (86400 seconds)
 
-// All instructions will now use mainnet by default (direct await)
-const ix = await createContract(params);
+// ✅ Valid: Hourly payments with hour-aligned max duration
+await createContract({
+  durationMax: 172800,   // 48 hours (172800 % 3600 = 0) ✓
+  paymentsFreq: 'hourly' // Min duration automatically set to 1 hour
+});
 ```
 
-### Per-Instruction Network Selection
-
-Override the network for specific instructions using the fluent interface:
+### Rate Calculation
 
-```typescript
-import { createContract } from '@wuwei-labs/srsly';
+The `rate` parameter in contracts represents ATLAS tokens per payment period:
+- For `daily` frequency: rate is ATLAS per day
+- For `weekly` frequency: rate is ATLAS per week
+- For `hourly` frequency: rate is ATLAS per hour
 
-// Use mainnet for this specific instruction
-const mainnetIx = await createContract(params).mainnet();
+## Payment System
 
-// Use devnet for this specific instruction  
-const devnetIx = await createContract(params).devnet();
+SRSLY implements an escrow-based payment system:
 
-// Use a specific network
-const specificIx = await createContract(params).network('mainnet');
+1. **Escrow**: Borrower deposits full rental amount upfront
+2. **Periodic Payments**: Automated payments based on frequency (daily/weekly/monthly)
+3. **Fees**: 10% platform fee, optional 10% referral sharing
+4. **Refunds**: Pro-rata refunds for early cancellation (24-hour minimum)
 
-// Use global network setting (direct await - no .build() needed!)
-const globalIx = await createContract(params);
+```typescript
+// Payment calculation example
+const rate = 1000; // ATLAS per payment period
+const paymentFrequency = 'daily'; // Payment every 86400 seconds
+const duration = days(7); // 7 days using helper function
+const paymentPeriods = duration / days(1); // 7 periods
+const totalAmount = rate * paymentPeriods * ATLAS_TO_STARDUST; // Total in stardust
 ```
 
-### Network Selection Methods
+## Program Sets Reference
 
-All SDK functions support these usage patterns:
+The SDK includes predefined program address sets for different networks:
 
-**Direct await (uses global network):**
-```typescript
-await createContract(params);
-await acceptRental(params);
-```
+| Network | SAGE Program | Game ID | ATLAS Mint |
+|---------|--------------|---------|------------|
+| `mainnet` | `SAGE2HAwep459SNq61LHvjxPk4pLPEJLoMETef7f7EE` | `GAMEzqJehF8yAnKiTARUuhZMvLvkZVAsCVri5vSfemLr` | `ATLASXmbPQxBUYbxPsV97usA3fPQYEqzQBUHgiFCUsXx` |
+| `atlasnet` | `SAgeTraQfBMdvGVDJYoEvjnbq5szW7RJPi6obDTDQUF` | `GAMEC7U7cqmFFaRow33j1LwuV8u4YhAS1mJ5Dqjnar2k` | `ATLA5nAaVRfH6BNwD4SAyWp96EdQaAh6bBmGeTx956sx` |
+| `holosim` | `SAgeTraQfBMdvGVDJYoEvjnbq5szW7RJPi6obDTDQUF` | `GAMEC7U7cqmFFaRow33j1LwuV8u4YhAS1mJ5Dqjnar2k` | `ATLA5nAaVRfH6BNwD4SAyWp96EdQaAh6bBmGeTx956sx` |
 
-**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)
+## Types and Constants
 
 ```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
-```
+import type { 
+  ContractState, 
+  RentalState, 
+  ConfigOptions,
+  PaymentFrequency 
+} from '@wuwei-labs/srsly';
 
-## IDL and Types
+import { 
+  ATLAS_TO_STARDUST,
+  FACTION_MAPPING,
+  days,
+  weeks,
+  months,
+  duration
+} from '@wuwei-labs/srsly';
 
-### Network-Specific IDLs
+// Conversion rate: 1 ATLAS = 100,000,000 stardust
+console.log(ATLAS_TO_STARDUST); // 100_000_000
 
-The SDK provides network-specific IDLs since program configurations differ between networks:
+// Faction mappings
+console.log(FACTION_MAPPING[1]); // 'mud'
+console.log(FACTION_MAPPING[2]); // 'oni' 
+console.log(FACTION_MAPPING[3]); // 'ustur'
 
-```typescript
-// Mainnet IDL
-import mainnetIdl from '@wuwei-labs/srsly/idl/mainnet';
+// Duration helper functions
+console.log(days(7));        // 604800 (7 days in seconds)
+console.log(weeks(2));       // 1209600 (2 weeks in seconds)
+console.log(months(1));      // 2678400 (1 month in seconds)
+console.log(duration.hours(12)); // 43200 (12 hours in seconds)
+```
 
-// Devnet IDL  
-import devnetIdl from '@wuwei-labs/srsly/idl/devnet';
+## IDL and Program Information
 
-// Use with Anchor
-import { Program } from '@coral-xyz/anchor';
-const program = new Program(mainnetIdl, provider);
+```typescript
+// Access program IDL
+import idl from '@wuwei-labs/srsly/idl';
 ```
 
-### Network-Specific Types
-
-Import TypeScript types that match your target network:
+## Error Handling
 
 ```typescript
-import type { 
-  ContractState,
-  RentalState,
-  PaymentFrequency,
-  ClockData,
-  ThreadResponse
-} from '@wuwei-labs/srsly';
+import { SrslyError } from '@wuwei-labs/srsly';
 
-// 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';
+try {
+  const instruction = await createContract(params);
+  // Add to transaction and send...
+} catch (error) {
+  if (error instanceof SrslyError) {
+    console.error('SRSLY SDK Error:', error.message, error.code);
+  } else {
+    console.error('Other Error:', error);
+  }
+}
 ```
 
-### Building Network-Specific Assets
+## Package Structure
 
-To generate IDLs and types for different networks:
+The SDK provides optimized builds for different environments:
 
-```bash
-# Generate mainnet IDL and types
-pnpm run generate:mainnet
+- **CommonJS**: `./dist/cjs/` (Node.js, webpack)
+- **ESM**: `./dist/esm/` (Modern ES modules)
+- **Types**: `./dist/types/` (TypeScript definitions)
+- **Codama**: `./dist/*/codama/` (Generated Solana program interfaces)
+- **IDL**: `./target/idl/srsly.json` (Anchor IDL)
+- **Types**: `./target/types/srsly.ts` (Generated types)
 
-# Generate devnet IDL and types  
-pnpm run generate:devnet
-```
-
-## Documentation
+## Links
 
+- **NPM Package**: [@wuwei-labs/srsly](https://www.npmjs.com/package/@wuwei-labs/srsly)
 - **TypeDoc Documentation**: [API Reference](https://wuwei-labs.github.io/srsly/)
-
-## Related Projects
-
-- **Star Atlas**: The metaverse gaming ecosystem
-- **Solana**: The blockchain platform powering SRSLY
-- **Anchor**: The framework used to build the SRSLY program