@wuwei-labs/srsly 2.0.0-beta.15 → 2.0.0-beta.17

package/README.md

@@ -4,1073 +4,310 @@
 [![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 building Solana instructions to interact with the SRSLY (Space Rental from SLY) program - a decentralized rental system for Star Atlas fleets.
+A TypeScript SDK for building and sending Solana transactions to interact with the SRSLY (Space Rental from SLY) program - a decentralized rental system for Star Atlas fleets.
 
 ## What This SDK Does
 
-The SRSLY SDK is an **instruction builder** that helps you create properly formatted Solana instructions for the SRSLY rental program. It handles:
+The SRSLY SDK is an **instruction builder** that helps you create properly formatted Solana instructions for fleet rentals. It provides:
 
-- ✅ Network-specific program addresses and configurations
-- ✅ Account derivation and validation
+- ✅ Account derivation and validation  
 - ✅ Instruction data encoding
 - ✅ Type-safe parameter handling
+- 🚧 Transaction building and submission (coming soon)
+- 🚧 RPC connection management (coming soon)
 
-## What You Need to Provide
-
-The SDK **does not** handle transaction creation, signing, or submission. You'll need to:
-
-- 🔧 Choose a transaction library (`@solana/web3.js` or `@solana/kit`)
-- 🔧 Connect to a Solana RPC endpoint
-- 🔧 Handle wallet integration (Phantom, Solflare, etc.)
-- 🔧 Build, sign, and send transactions
+**Current Status**: Full instruction building support. Transaction submission via `.send()` is planned for a future release.
 
 ## Installation
 
-### NPM
-
 ```bash
 npm install @wuwei-labs/srsly
-```
-
-### PNPM
-
-```bash
+# or
 pnpm add @wuwei-labs/srsly
-```
-
-### Yarn
-
-```bash
+# or  
 yarn add @wuwei-labs/srsly
 ```
 
 ## Quick Start
 
-```typescript
-import { 
-  createContract, 
-  setConfig 
-} from '@wuwei-labs/srsly';
-
-import {
-  createDefaultSolanaRpc,
-  createTransaction, 
-  appendInstructions,
-  signAndSendTransaction,
-  pipe
-} from '@solana/kit';
+### Current: Instruction Building
 
-// Step 1: Set up RPC connection
-const rpc = createDefaultSolanaRpc('https://api.atlasnet.solana.com');
-
-// Step 2: Get wallet from browser extension (Phantom, Solflare, etc.)
-// Assumes you've already connected to the user's wallet
-const wallet = window.solana; // or your wallet adapter
+```typescript
+import { createContract, setConfig } from '@wuwei-labs/srsly';
+import { Connection, Transaction } from '@solana/web3.js';
 
-// Step 3: Configure SDK to use atlasnet program addresses
-setConfig({ network: 'atlasnet' });
+// 1. Configure SDK for your network
+setConfig({ programs: 'atlasnet' });
 
-// Step 4: Build the instruction using SRSLY SDK
-const contractInstruction = await createContract({
-  owner: wallet.publicKey, // Wallet's public key
+// 2. Build instruction
+const instruction = await createContract({
+  owner: walletPublicKey,
   fleet: fleetAddress,
   ownerProfile: profileAddress,
-  rate: 1000000, // Rate in ATLAS tokens
-  durationMin: 86400, // 1 day in seconds
-  durationMax: 604800, // 1 week in seconds
-  paymentsFreq: 'daily',
-  ownerKeyIndex: 0
+  rate: 1000000, // ATLAS tokens
+  durationMin: 86400, // 1 day
+  durationMax: 604800, // 1 week
+  paymentsFreq: 'daily'
 });
 
-// Step 5: Build transaction and send (using your preferred method)
-const transaction = pipe(
-  createTransaction({ version: 0 }),
-  tx => appendInstructions([contractInstruction], tx)
-);
-
-// Sign and send using wallet extension
-const signature = await signAndSendTransaction(rpc, transaction, wallet);
-console.log('Transaction signature:', signature);
+// 3. Build and send transaction yourself
+const connection = new Connection('https://api.atlasnet.solana.com');
+const transaction = new Transaction().add(instruction);
+const signature = await wallet.signAndSendTransaction(transaction);
 ```
 
-**Alternative with @solana/web3.js:**
+### Future: Transaction Sending (Coming Soon)
 
 ```typescript
-import { Connection, Transaction } from '@solana/web3.js';
-
-const connection = new Connection('https://api.atlasnet.solana.com');
-const transaction = new Transaction().add(contractInstruction);
-
-// Sign and send with wallet extension
-const signature = await window.solana.signAndSendTransaction(transaction);
+// This will be available in a future release:
+const signature = await createContract({
+  owner: walletPublicKey,
+  fleet: fleetAddress,
+  ownerProfile: profileAddress,
+  rate: 1000000, // ATLAS tokens
+  durationMin: 86400, // 1 day
+  durationMax: 604800, // 1 week
+  paymentsFreq: 'daily'
+}).send(signer); // 🚧 Not yet implemented
 ```
 
-> **Note**: The SRSLY SDK only creates instructions. You're responsible for:
-> - Setting up RPC connections
-> - Managing wallet connections (Phantom, Solflare, etc.)
-> - Building, signing, and sending transactions
-> - Handling transaction confirmation and errors
+## Core Features
 
----
+### Flexible Address Input
 
-## SDK Features
+The SDK accepts both string and Address types for all address parameters, automatically converting them to the proper format:
 
-The following examples show how to use the SRSLY SDK to build instructions. Add these instructions to transactions using your preferred Solana library (`@solana/web3.js` or `@solana/kit`).
+```typescript
+import { createContract, address } from '@wuwei-labs/srsly';
 
-### Contract Management
+// Mixed usage allowed
+const createIx = await createContract({
+  owner: wallet,
+  fleet: "123abc...",              // string
+  ownerProfile: address("456def..."), // Address<string>
+  rate: 5000000,
+  durationMin: 86400,
+  durationMax: 2592000,
+  paymentsFreq: 'daily'
+});
+```
 
-Create and manage rental contracts for Star Atlas fleets:
+### Contract Management
 
 ```typescript
 import { createContract, closeContract } from '@wuwei-labs/srsly';
 
-// Create a new rental contract with network configuration
+// Create rental contract instruction
 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 atlasnet programs (direct await)
+  rate: 5000000,
+  durationMin: 86400,
+  durationMax: 2592000,
+  paymentsFreq: 'daily'
+});
+
+// Close contract instruction
 const closeIx = await closeContract({
   owner: wallet,
   fleet: fleetAddress,
-  contract: contractAddress,
-  faction: 'mud' // or faction number: 1, 2, 3
+  contract: contractAddress
 });
 ```
 
 ### Rental Operations
 
-Handle rental lifecycle operations with automatic token conversion:
-
 ```typescript
-import { 
-  acceptRental, 
-  cancelRental, 
-  closeRental, 
-  resetRental,
-  ATLAS_TO_STARDUST
-} from '@wuwei-labs/srsly';
+import { acceptRental, cancelRental, closeRental } from '@wuwei-labs/srsly';
 
-// Accept a rental offer on atlasnet (rate-based with automatic conversion)
+// Accept rental offer instruction
 const acceptIx = await acceptRental({
   borrower: borrowerWallet,
   borrowerProfile: borrowerProfileAddress,
-  borrowerFaction: 'oni', // or faction number: 1=mud, 2=oni, 3=ustur
+  borrowerFaction: 'mud', // or 1, 2, 3
   fleet: fleetAddress,
   contract: contractAddress,
-  rate: 100, // ATLAS tokens (not per second, just ATLAS)
+  rate: 100, // ATLAS per day
   duration: 86400 // 1 day in seconds
-  // amount = rate * duration * ATLAS_TO_STARDUST automatically calculated
-}).set({ network: 'atlasnet' });
+});
 
-// Cancel an active rental using atlasnet programs (direct await)
+// Cancel active rental instruction
 const cancelIx = await cancelRental({
   borrower: borrowerWallet,
   contract: contractAddress,
   rentalState: rentalStateAddress
 });
 
-// Close a completed rental on mainnet
+// Close completed rental instruction
 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 (programs to atlasnet)
-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));
-```
-
-### Error Handling
-
-The SDK provides custom error types for better debugging:
-
-```typescript
-import { SrslyError } from '@wuwei-labs/srsly';
-
-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);
-  }
-}
-```
-
-### 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
-
-
 ## Network Configuration
 
-The SDK supports both Solana mainnet and atlasnet with different IDL artifacts and default program addresses for each network. The configuration system has two main purposes:
-
-### What `setConfig` Does:
-
-**1. Network Selection (IDL/Module Loading):**
-- ✅ Selects which IDL artifacts to use (`mainnet` vs `atlasnet`)
-- ✅ Loads appropriate codama-generated instruction builders
-- ✅ Determines default program addresses for the network
+The SDK supports multiple network configurations:
 
-**2. Program Address Selection:**
-- ✅ Select predefined program address sets (mainnet, atlasnet, holosim)
-- ✅ Override specific program addresses (SRSLY, SAGE, Profile Faction)
-- ✅ Override game IDs and other network constants
-- ✅ Mix and match programs across networks if needed
-
-**What it does NOT do:**
-- ❌ Configure RPC endpoints
-- ❌ Handle wallet connections
-- ❌ Manage transactions
-
-### Global Configuration (Recommended)
-
-Set default configuration once for all SDK operations:
+### Global Configuration
 
 ```typescript
-import { setConfig, getConfig, createContract } from '@wuwei-labs/srsly';
-
-// Example 1: Use mainnet IDL with default mainnet program addresses
-setConfig({ 
-  network: 'mainnet'
-});
+import { setConfig, getConfig, clearConfig } from '@wuwei-labs/srsly';
 
-// Example 2: Use atlasnet IDL with default atlasnet program addresses
-setConfig({ 
-  network: 'atlasnet'
-});
+// Use mainnet programs (includes default RPC URL)
+setConfig({ programs: 'mainnet' });
 
-// Example 3: Use atlasnet IDL with holosim program addresses
+// Use atlasnet programs (default) - requires explicit RPC URL
 setConfig({ 
-  network: 'atlasnet',
-  programs: 'holosim'
+  programs: 'atlasnet',
+  rpcUrl: 'https://api.atlasnet.solana.com' // Required for atlasnet
 });
 
-// Example 4: Use atlasnet IDL with holosim programs but custom SAGE
+// Use holosim test programs - requires explicit RPC URL
 setConfig({ 
-  network: 'atlasnet',
   programs: 'holosim',
-  sageProgramAddress: 'custom-sage-program-id...'
-});
-
-// Example 5: Use mainnet IDL with atlasnet program addresses
-setConfig({ 
-  network: 'mainnet',
-  programs: 'atlasnet'
+  rpcUrl: 'https://api.atlasnet.solana.com' // Required for holosim
 });
 
-// Example 6: Custom overrides only
+// Custom configuration
 setConfig({ 
-  network: 'atlasnet',
-  srslyProgramAddress: 'custom-srsly-program-id...',
-  sageProgramAddress: 'custom-sage-program-id...',
-  gameId: 'custom-game-id...'
+  programs: 'mainnet',
+  srslyProgramAddress: 'custom-srsly-program...',
+  gameId: 'custom-game-id...',
+  atlasMint: 'custom-atlas-mint...'
+  // mainnet includes default RPC URL
 });
 
-// Check current configuration
+// Check current config
 console.log(getConfig());
 
-// All operations now use configured settings
-const ix1 = await createContract(params); // Uses configured SRSLY program
-const ix2 = await acceptRental(params);   // Uses configured SAGE program
+// Reset to defaults
+clearConfig();
 ```
 
 ### Per-Instruction Configuration
 
-Override global program address configuration for specific instructions using the fluent `.set()` interface:
-
-```typescript
-import { createContract, acceptRental } from '@wuwei-labs/srsly';
-
-// Assume global config is set to mainnet program addresses
-setConfig({ network: 'mainnet' });
-
-// Use global mainnet program addresses
-const mainnetIx = await createContract(params);
-
-// Override to use atlasnet program addresses for this specific instruction
-const atlasnetIx = await createContract(params).set({ network: 'atlasnet' });
-
-// Override specific program addresses while keeping global network
-const customIx = await createContract(params).set({ 
-  sageProgramAddress: 'custom-sage-program-id...',
-  gameId: 'custom-game-id...'
-  // network: 'mainnet' inherited from global config
-});
-```
-
-### Configuration Options
-
-All SDK functions support these usage patterns:
-
-**Direct await (uses global config or atlasnet fallback):**
-
-```typescript
-// Uses global program addresses if set, otherwise atlasnet programs
-await createContract(params);
-await acceptRental(params);
-```
-
-**Global configuration functions:**
-
-- `setConfig({ network: 'mainnet', gameId: '...' })` - Set global program addresses
-- `getConfig()` - Get current global configuration
-- `clearConfig()` - Reset to atlasnet programs
-
-**Per-instruction overrides with `.set()` method:**
-
-- `.set({ network: 'mainnet' })` - Override to mainnet program addresses
-- `.set({ sageProgramAddress: '...' })` - Override specific program address only  
-- `.set({ network: 'mainnet', sageProgramAddress: '...' })` - Multiple overrides
-
-**Chainable configurations:**
-
-```typescript
-// Chain multiple configurations (later ones override earlier ones)
-await createContract(params)
-  .set({ network: 'atlasnet' })
-  .set({ sageProgramAddress: 'override...' });
-
-// Examples with global config
-setConfig({ network: 'mainnet' });
-await createContract(params); // Uses mainnet program addresses
-await acceptRental(params).set({ network: 'atlasnet' }); // Override to atlasnet programs  
-await closeContract(params).set({ gameId: 'custom...' }); // Custom gameId, mainnet programs
-```
-
-### Available Configuration Options
-
-```typescript
-interface ConfigOptions {
-  network?: 'mainnet' | 'atlasnet';            // Which IDL artifacts to use
-  programs?: 'mainnet' | 'atlasnet' | 'holosim'; // Which program address set to use
-  srslyProgramAddress?: string;                // Override SRSLY program address
-  sageProgramAddress?: string;                 // Override SAGE program address
-  profileFactionProgramAddress?: string;       // Override Profile Faction program address  
-  gameId?: string;                            // Override SAGE game ID
-}
-```
-
-**Available Program Address Sets:**
-
 ```typescript
-// mainnet
-{
-  srslyProgram: 'SRSLY1fq9TJqCk1gNSE7VZL2bztvTn9wm4VR8u8jMKT',
-  sageProgram: 'SAGE2HAwep459SNq61LHvjxPk4pLPEJLoMETef7f7EE',
-  profileFactionProgram: 'pFACSRuobDmvfMKq1bAzwj27t6d2GJhSCHb1VcfnRmq',
-  gameId: 'GAMEzqJehF8yAnKiTARUuhZMvLvkZVAsCVri5vSfemLr'
-}
-
-// atlasnet (default) - values currently empty, to be filled
-{
-  srslyProgram: 'SRSLY1fq9TJqCk1gNSE7VZL2bztvTn9wm4VR8u8jMKT',
-  sageProgram: '',
-  profileFactionProgram: '', 
-  gameId: ''
-}
-
-// holosim
-{
-  srslyProgram: 'SRSLY1fq9TJqCk1gNSE7VZL2bztvTn9wm4VR8u8jMKT',
-  sageProgram: 'SAgeTraQfBMdvGVDJYoEvjnbq5szW7RJPi6obDTDQUF',
-  profileFactionProgram: 'PprofUW1pURCnMW2si88GWPXEEK3Bvh9Tksy8WtnoYJ', 
-  gameId: 'GAMEC7U7cqmFFaRow33j1LwuV8u4YhAS1mJ5Dqjnar2k'
-}
-```
-
-**Priority Order:**
-1. Individual overrides (highest priority)
-2. programs configuration
-3. Network default (if programs not specified)
-
-**Key Concepts:**
-
-- **Network** = Which IDL/codama artifacts to load (affects instruction structure)
-- **programs** = Which predefined program address set to use (mainnet, atlasnet, holosim)
-- **Program Overrides** = Override individual program addresses (highest priority)
-- **Default Behavior** = If programs not specified, uses network's program addresses
-- **Flexibility** = Mix any IDL with any program set, plus individual overrides
-
-### Network-Specific Constants
-
-The SDK automatically resolves network-specific constants:
-
-```typescript
-import { 
-  getSageProgramAddress, 
-  getProfileFactionProgramAddress, 
-  getSageGameId 
-} from '@wuwei-labs/srsly';
-
-// Get constants for atlasnet (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
-
-### Network-Specific IDLs
+// Override global config for specific instructions
+const ix = await createContract(params).set({ programs: 'mainnet' });
 
-The SDK provides network-specific IDLs since program configurations differ between networks:
-
-```typescript
-// Mainnet IDL
-import mainnetIdl from '@wuwei-labs/srsly/idl/mainnet';
-
-// Devnet IDL  
-import atlasnetIdl from '@wuwei-labs/srsly/idl/atlasnet';
-
-// Use with Anchor
-import { Program } from '@coral-xyz/anchor';
-const program = new Program(mainnetIdl, provider);
-```
-
-### Network-Specific Types
-
-Import TypeScript types that match your target network:
-
-```typescript
-import type { 
-  ContractState,
-  RentalState,
-  PaymentFrequency,
-  ClockData,
-  ThreadResponse,
-  ConfigOptions
-} 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/atlasnet';
+// Chain multiple configurations
+const ix2 = await acceptRental(params)
+  .set({ programs: 'holosim' })
+  .set({ gameId: 'custom-game-id...' });
 ```
 
-### Accessing Packaged IDLs
+## Payment System
 
-The SDK includes pre-packaged IDL (Interface Definition Language) files for each network. These IDL files contain the complete program interface definition and can be accessed in multiple ways:
+SRSLY implements an escrow-based payment system:
 
-#### 1. Import IDL as JavaScript/TypeScript Module
+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)
 
 ```typescript
-// CommonJS
-const mainnetIdl = require('@wuwei-labs/srsly/idl/mainnet');
-const atlasnetIdl = require('@wuwei-labs/srsly/idl/atlasnet');
-
-// ES Modules
-import mainnetIdl from '@wuwei-labs/srsly/idl/mainnet';
-import atlasnetIdl from '@wuwei-labs/srsly/idl/atlasnet';
-
-// Use with Anchor
-import { Program } from '@coral-xyz/anchor';
-const program = new Program(mainnetIdl, provider);
-```
-
-#### 2. Access Raw IDL JSON Files
-
-The raw IDL JSON files are included in the npm package and can be found at:
-
-```
-node_modules/@wuwei-labs/srsly/target/idl/srsly-mainnet.json
-node_modules/@wuwei-labs/srsly/target/idl/srsly-atlasnet.json
+// Payment calculation
+const rate = 1000; // ATLAS per day
+const duration = 86400; // 1 day in seconds
+const totalAmount = rate * duration * ATLAS_TO_STARDUST; // in stardust
 ```
 
-You can read these files directly if you need the raw JSON:
+## Available Networks
 
 ```typescript
-// Using Node.js fs
-import fs from 'fs';
-import path from 'path';
-
-const idlPath = path.join(
-  require.resolve('@wuwei-labs/srsly/package.json'),
-  '../target/idl/srsly-mainnet.json'
-);
-const idlJson = JSON.parse(fs.readFileSync(idlPath, 'utf-8'));
-
-// Using dynamic import (works in browsers with bundlers)
-const idlModule = await import('@wuwei-labs/srsly/idl/mainnet');
-const idl = idlModule.default;
-```
-
-#### 3. IDL Structure
-
-Each IDL file contains:
-
-- **address**: The program's on-chain address
-- **metadata**: Program name, version, and description
-- **instructions**: All available program instructions with their discriminators
-- **accounts**: Account structures used by the program
-- **types**: Custom types and enums defined in the program
-- **errors**: Custom error codes and messages
-
-Example IDL structure:
-```json
-{
-  "address": "SRSLY1fq9TJqCk1gNSE7VZL2bztvTn9wm4VR8u8jMKT",
-  "metadata": {
-    "name": "srsly",
-    "version": "0.1.0",
-    "spec": "0.1.0"
+// Program address sets
+const networks = {
+  mainnet: {
+    sageProgram: 'SAGE2HAwep459SNq61LHvjxPk4pLPEJLoMETef7f7EE',
+    gameId: 'GAMEzqJehF8yAnKiTARUuhZMvLvkZVAsCVri5vSfemLr',
+    atlasMint: 'ATLASXmbPQxBUYbxPsV97usA3fPQYEqzQBUHgiFCUsXx',
+    rpcUrl: 'https://api.mainnet-beta.solana.com' // Default RPC for mainnet
   },
-  "instructions": [...],
-  "accounts": [...],
-  "types": [...]
-}
+  atlasnet: {
+    sageProgram: 'SAgeTraQfBMdvGVDJYoEvjnbq5szW7RJPi6obDTDQUF',
+    gameId: 'GAMEC7U7cqmFFaRow33j1LwuV8u4YhAS1mJ5Dqjnar2k',
+    atlasMint: 'ATLASXmbPQxBUYbxPsV97usA3fPQYEqzQBUHgiFCUsXx'
+    // No default RPC - must provide rpcUrl required permissions
+  },
+  holosim: { 
+    sageProgram: 'SAgeTraQfBMdvGVDJYoEvjnbq5szW7RJPi6obDTDQUF',
+    gameId: 'GAMEC7U7cqmFFaRow33j1LwuV8u4YhAS1mJ5Dqjnar2k',
+    atlasMint: 'ATLASXmbPQxBUYbxPsV97usA3fPQYEqzQBUHgiFCUsXx'
+    // No default RPC - must provide rpcUrl required permissions
+  }
+};
 ```
 
-#### 4. Network Differences
-
-The main difference between network IDLs is the mint addresses used:
-- **Mainnet**: Uses production ATLAS mint (`ATLASXmbPQxBUYbxPsV97usA3fPQYEqzQBUHgiFCUsXx`)
-- **Atlasnet**: Uses test ATLAS mint (`ATLA5nAaVRfH6BNwD4SAyWp96EdQaAh6bBmGeTx956sx`)
-
-#### 5. Using IDLs with Other Tools
+**Note**: Atlasnet and holosim networks require you to explicitly provide an `rpcUrl` in your configuration since they don't have default RPC endpoints.
 
-The packaged IDLs are compatible with:
-- **Anchor Framework**: Use directly with `new Program(idl, provider)`
-- **Solana Playground**: Import the JSON for program interaction
-- **Custom Clients**: Parse the IDL to generate your own client code
-- **Testing Frameworks**: Use for mocking program interfaces
-
-### Accessing Packaged TypeScript Types
-
-The SDK includes comprehensive TypeScript type definitions that are automatically generated from the program IDL. These types ensure type safety when building instructions and handling program data.
-
-#### 1. Import SDK Types
-
-The main types are exported from the package root:
+## Types and Constants
 
 ```typescript
-import type {
-  // Account types
-  ContractState,
-  RentalState,
-  Fleet,
-  
-  // Instruction types
-  CreateContractInstruction,
-  AcceptRentalInstruction,
-  CloseContractInstruction,
-  
-  // Data types
-  ClockData,
-  ThreadResponse,
-  PaymentFrequency,
-  
-  // Configuration types
+import type { 
+  ContractState, 
+  RentalState, 
   ConfigOptions,
-  NetworkType
+  PaymentFrequency 
 } from '@wuwei-labs/srsly';
-```
-
-#### 2. Network-Specific Anchor Types
-
-Access the complete Anchor-generated types for each network:
-
-```typescript
-// Import network-specific program types
-import type { Srsly as SrslyMainnet } from '@wuwei-labs/srsly/types/mainnet';
-import type { Srsly as SrslyAtlasnet } from '@wuwei-labs/srsly/types/atlasnet';
-
-// These include all program types, accounts, and instructions
-type MainnetProgram = SrslyMainnet;
-type AtlasnetProgram = SrslyAtlasnet;
-
-// Access specific account types
-type MainnetContractAccount = SrslyMainnet['accounts']['contract'];
-type AtlasnetRentalAccount = SrslyAtlasnet['accounts']['rental'];
-```
-
-#### 3. Codama-Generated Types
-
-For advanced use cases, access the auto-generated Codama types directly:
-
-```typescript
-// Import specific codama-generated types
-import type {
-  Contract,
-  Rental,
-  contractDiscriminator
-} from '@wuwei-labs/srsly/dist/types/codama/mainnet/accounts';
-
-import type {
-  createContract,
-  CreateContractInstructionAccounts,
-  CreateContractInstructionData
-} from '@wuwei-labs/srsly/dist/types/codama/mainnet/instructions';
-
-// Network-specific imports
-import { SRSLY_PROGRAM_ADDRESS } from '@wuwei-labs/srsly/dist/types/codama/mainnet';
-```
-
-#### 4. Type File Locations in Package
-
-The TypeScript definition files are distributed in the npm package at:
-
-```
-node_modules/@wuwei-labs/srsly/
-├── dist/types/              # Compiled TypeScript definitions
-│   ├── index.d.ts          # Main entry point
-│   ├── contract/           # Contract operation types
-│   ├── rental/             # Rental operation types
-│   ├── utils/              # Utility types and constants
-│   └── codama/             # Auto-generated types
-│       ├── mainnet/        # Mainnet-specific types
-│       └── atlasnet/       # Atlasnet-specific types
-└── target/types/           # Anchor-generated types
-    ├── srsly-mainnet.ts    # Mainnet Anchor types
-    └── srsly-atlasnet.ts   # Atlasnet Anchor types
-```
-
-#### 5. Using Types in Your Application
-
-```typescript
-import { createContract } from '@wuwei-labs/srsly';
-import type { ContractState, CreateContractInstruction } from '@wuwei-labs/srsly';
-
-// Type-safe instruction building
-async function buildContractInstruction(): Promise<CreateContractInstruction> {
-  const instruction = await createContract({
-    owner: ownerPublicKey,
-    fleet: fleetPublicKey,
-    ownerProfile: profilePublicKey,
-    rate: 1000000,
-    durationMin: 86400,
-    durationMax: 604800,
-    paymentsFreq: 'daily',
-    ownerKeyIndex: 0
-  });
-  
-  return instruction; // Type: CreateContractInstruction
-}
-
-// Type-safe account decoding
-function handleContract(account: ContractState) {
-  console.log('Rate:', account.rate.toString());
-  console.log('Owner:', account.owner.toBase58());
-  console.log('Fleet:', account.fleet.toBase58());
-}
-```
 
-#### 6. Type Categories
-
-The SDK types are organized into several categories:
-
-- **Account Types**: Represent on-chain account data structures (`ContractState`, `RentalState`)
-- **Instruction Types**: Type definitions for each program instruction
-- **Utility Types**: Helper types like `PaymentFrequency`, `FactionType`
-- **Configuration Types**: Types for SDK configuration (`ConfigOptions`, `NetworkType`)
-- **Codama Types**: Low-level auto-generated types from the IDL
-
-#### 7. Type Safety Benefits
-
-Using the packaged types provides:
-
-- **Compile-time validation** of instruction parameters
-- **IntelliSense support** in your IDE
-- **Automatic type inference** for decoded accounts
-- **Network-specific type checking** to prevent cross-network errors
-- **Version compatibility** between your client and the on-chain program
-
-## 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
+  toAddress 
 } from '@wuwei-labs/srsly';
 
-// Token conversion
+// Conversion rate: 1 ATLAS = 100,000,000 stardust
 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[2]); // 'oni' 
 console.log(FACTION_MAPPING[3]); // 'ustur'
+
+// Address conversion utility
+const addressObj = toAddress("123abc..."); // converts string to Address<string>
+console.log(addressObj); // Address<string>
 ```
 
-### Profile Derivation
+## IDL and Program Information
 
 ```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' }
-);
+// Access program IDLs
+import mainnetIdl from '@wuwei-labs/srsly/idl/mainnet';
+import atlasnetIdl from '@wuwei-labs/srsly/idl/atlasnet';
 ```
 
-## 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
+## Error Handling
 
-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
+```typescript
+import { SrslyError } from '@wuwei-labs/srsly';
 
-# Test both package managers
-npm run test:package-managers
+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);
+  }
+}
 ```
 
-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
+## Package Structure
 
-## Documentation
+The SDK provides optimized builds for different environments:
 
-- **TypeDoc Documentation**: [API Reference](https://wuwei-labs.github.io/srsly/)
+- **CommonJS**: `./dist/cjs/` (Node.js, webpack)
+- **ESM**: `./dist/esm/` (Modern ES modules)
+- **Types**: `./dist/types/` (TypeScript definitions)
+- **Shared**: `./dist/shared/codama/` (Optimized codama exports)
 
-## Related Projects
+## Links
 
-- **Star Atlas**: The metaverse gaming ecosystem
-- **Solana**: The blockchain platform powering SRSLY
-- **Anchor**: The framework used to build the SRSLY program
+- **NPM Package**: [@wuwei-labs/srsly](https://www.npmjs.com/package/@wuwei-labs/srsly)
+- **TypeDoc Documentation**: [API Reference](https://wuwei-labs.github.io/srsly/)