@wuwei-labs/srsly 2.0.0-beta.7 → 2.3.3-canary.36.16828734028.0

package/README.md

@@ -4,665 +4,530 @@
 [![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 fleets with network-specific configuration support.
+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
 
-### NPM
+The SRSLY SDK is a focused instruction builder that helps you create Solana instructions for fleet rentals. It provides:
 
-```bash
-npm install @wuwei-labs/srsly
-```
+- ✅ **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
+- ✅ **Smart Parameters** - Intuitive parameter formats with ATLAS as default unit
+- ✅ **Network Agnostic** - Same program works across all networks (mainnet, devnet, etc.)
 
-### PNPM
+**Current Status**: Instruction-only SDK using @solana/kit. Users handle transaction assembly and sending.
 
-```bash
-pnpm add @wuwei-labs/srsly
-```
+**RPC Requirement**: The SDK requires an RPC URL to fetch account states. This enables automatic PDA derivation and validation but means you must configure an RPC endpoint.
 
-### Yarn
+## Installation
 
 ```bash
-yarn add @wuwei-labs/srsly
+# Install the SDK (includes @solana/kit as a dependency)
+npm install @wuwei-labs/srsly
 ```
 
+The SDK uses @solana/kit internally and provides seamless conversion to @solana/web3.js format for browser wallet compatibility.
+
 ## Quick Start
 
-```typescript
-import { 
-  createContract, 
-  acceptRental,
-  setConfig,
-  setNetwork, 
-  ATLAS_TO_STARDUST
-} from '@wuwei-labs/srsly';
+### Using with @solana/kit (Default)
 
-// Option 1: Set global configuration (recommended for most apps)
-setConfig({ network: 'mainnet' });
-// or use the convenience function: setNetwork('mainnet');
+```typescript
+import { createContract, setConfig } from '@wuwei-labs/srsly';
 
-// 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
+// 1. Configure SDK with your RPC endpoint
+setConfig({
+  rpcUrl: 'https://your-rpc-endpoint.com' // Required - no defaults provided
+});
 
-// 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
+// 2. Create an instruction with smart parameters (v3)
+const instruction = await createContract({
+  owner: signer,  // Can be a signer object or string address
+  fleet: "FleetAddress123...",        // String address
+  ownerProfile: "ProfileAddr...",     // String address
+  rate: 10,                           // ATLAS tokens per payment period (v3 default)
+  durationMax: { days: 7 },           // Smart duration parameter
+  paymentsFreq: 'daily'               // Payment frequency
+});
 
-// Option 2: Override global config for specific instructions
-const devnetInstruction = await createContract(params).set({ network: 'devnet' });
+// 3. Add instruction to your transaction and send
+// (Use your preferred transaction building and sending method)
 ```
 
-## Core Features
-
-### Contract Management
-
-Create and manage rental contracts for Star Atlas fleets:
+### Using with @solana/web3.js (wallet-adapter)
 
 ```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
+import { createContract, setConfig } from '@wuwei-labs/srsly';
+import { Transaction, PublicKey } from '@solana/web3.js';
+
+// 1. Configure SDK with your RPC endpoint
+setConfig({
+  rpcUrl: 'https://your-rpc-endpoint.com', // Required - no defaults provided
+  library: 'web3js',
+  PublicKey // required to ensure addresses use web3js publickey format
 });
-```
-
-### 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
+// 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: 10,                            // ATLAS per period (v3 default)
+  durationMax: { days: 7 },            // Smart duration parameter
+  paymentsFreq: 'daily'
 });
 
-// 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...'
-});
+// 3. Add to transaction and send
+const transaction = new Transaction().add(web3jsInstruction);
+const signature = await wallet.sendTransaction(transaction, connection);
 ```
 
-### Account State Management
-
-Fetch and decode account states using network-specific functions:
-
-```typescript
-import { getCachedNetworkModule } from '@wuwei-labs/srsly';
+## Core Features
 
-// Get network-specific account functions (defaults to devnet)
-const accountsModule = await getCachedNetworkModule('accounts');
-const { fetchContractState, fetchRentalState } = accountsModule;
+### Universal Signer Pattern
 
-// Or specify network explicitly
-const mainnetAccountsModule = await getCachedNetworkModule('accounts', 'mainnet');
+The SDK supports both CLI/Node.js and browser usage patterns through its Universal Signer functionality:
 
-// 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());
+**Browser Usage** (String Addresses):
 
-// 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));
+```typescript
+// Pass string addresses for browser wallets
+const instruction = await acceptRental({
+  borrower: wallet.publicKey.toString(),  // String address
+  // ... other params
+});
+// Browser wallet handles signing separately
 ```
 
-### Token Conversion
-
-The SDK includes automatic ATLAS to stardust conversion for rental operations:
+**CLI/Node.js Usage** (Signer Objects):
 
 ```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
+// Pass signer objects for full signing capability
+const instruction = await acceptRental({
+  borrower: wallet,  // Signer object
+  // ... other params
+});
+// Can sign transactions directly
 ```
 
-## Program Information
-
-- **Program ID**: `SRSLY1fq9TJqCk1gNSE7VZL2bztvTn9wm4VR8u8jMKT`
-- **Network**: Solana Mainnet or Atlasnet
-- **Built with**: Anchor Framework
-
-## Payment Structure
+### Instruction Building & Format Conversion
 
-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.
+The SDK creates @solana/kit compatible instructions with seamless web3.js conversion:
 
-### Overview
+- **📦 Instruction-Only**: Focus on instruction building, users handle transaction assembly/sending
+- **🔄 Format Conversion**: Built-in `.web3js(PublicKey)` method for wallet compatibility
+- **🎯 Universal Signer**: Accepts both string addresses and signer objects
+- **⚡ Lightweight**: Uses @solana/kit internally with optional web3.js conversion
 
-```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
+### Web3.js Format Conversion
 
-When a borrower accepts a rental, they deposit the **full rental amount upfront** into an escrow account:
+The SDK accepts string addresses as input and provides seamless conversion to @solana/web3.js format for browser wallet compatibility:
 
 ```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
+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({
+  rpcUrl: 'https://api.mainnet-beta.solana.com'
+}).web3js(PublicKey);
+
+// Use in transactions
+const transaction = new Transaction().add(web3jsInstruction);
 ```
 
-**Key Points:**
+**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
+- 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.)
 
-### 2. Periodic Payments
+### Smart Parameters (v3)
 
-The system creates an automated thread that executes payments based on the contract's payment frequency:
+The SDK v3 introduces smart parameters that make working with amounts and durations more intuitive:
 
+#### Duration Parameters
 ```typescript
-// Contract with daily payments
-const contractIx = await createContract({
+// Smart duration objects - no mental math needed!
+const contract = 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
+  rate: 10,                        // ATLAS per period (v3 default)
+  durationMin: { hours: 1 },       // 1 hour minimum
+  durationMax: { weeks: 2 },       // 2 weeks maximum
+  paymentsFreq: 'daily'
 });
-```
-
-**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
+// Supported duration formats
+duration: { minutes: 30 }   // 30 minutes
+duration: { hours: 12 }     // 12 hours  
+duration: { days: 7 }       // 7 days
+duration: { weeks: 4 }      // 4 weeks
+duration: { months: 3 }     // 3 months (31 days each)
 
-**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
+// Backwards compatible - raw seconds still work
+duration: 604800            // 7 days in seconds
 ```
 
-### 3. Fee Structure
+#### Amount and Rate Parameters
+```typescript
+// v3 Default: Numbers are ATLAS
+const contract = await createContract({
+  rate: 10,                  // 10 ATLAS per period (NEW DEFAULT)
+  durationMax: { days: 30 },
+  // ...
+});
 
-Each payment is subject to a **10% platform fee** with optional **10% referral sharing**:
+// Explicit formats for clarity
+rate: { atlas: 10 }          // 10 ATLAS per period
+rate: { stardust: 1000000000 } // 10 ATLAS in stardust units
 
-```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
+// Accept rental with smart amount
+const rental = await acceptRental({
+  borrower: wallet,
+  contract: "ContractAddr...",
+  duration: { days: 7 },     // Smart duration
+  // amount calculated automatically
+});
 ```
 
-**Fee Calculation:**
+#### Breaking Change Notice
+**v3 Breaking Change**: Rate and amount parameters now default to ATLAS units instead of stardust. This makes the SDK more intuitive but requires updating existing code:
 
 ```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
-```
+// v2 (old) - rate in stardust
+rate: 1000000000  // 10 ATLAS in stardust
 
-**Example Payment Breakdown:**
+// v3 (new) - rate in ATLAS  
+rate: 10          // 10 ATLAS (much cleaner!)
 
-```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
+// v3 with explicit unit
+rate: { atlas: 10 }
 ```
 
-### 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
+### Contract Management
 
-3. **Owner Payment**
-   - Amount: `payment_amount - total_fee`
-   - Destination: Fleet owner's token account
+```typescript
+import { createContract, closeContract } from '@wuwei-labs/srsly';
 
-**Code Example:**
+// Create rental contract instruction
+const createIx = await createContract({
+  owner: wallet,
+  fleet: fleetAddress,
+  ownerProfile: profileAddress,
+  rate: 5,                     // 5 ATLAS per day (v3 default)
+  durationMax: { months: 1 },  // 1 month maximum
+  paymentsFreq: 'daily'
+});
 
-```typescript
-// Accept rental with referral
-const acceptIx = await acceptRental({
-  borrower: wallet,
-  borrowerProfile: profileAddress,
-  borrowerFaction: 'mud',
+// Close contract instruction
+const closeIx = await closeContract({
+  owner: wallet,
   fleet: fleetAddress,
   contract: contractAddress,
-  rate: 1000,
-  duration: 86400,
-  referralTokenAccount: referrerTokenAccount // 10% of fees
+  faction: 'mud' // or 1, 2, 3
 });
 ```
 
-### 5. Refund Mechanism
+#### Important Contract Close Behavior
 
-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.**
+**Contract closure behavior depends on the rental state:**
 
-**Early Cancellation:**
+- **No Active Rental**: If `current_rental_state` is not set (equals system program ID), the contract closes immediately
+- **Active Rental**: If there's an active rental (`current_rental_state` is set), the contract is only flagged for closure (`to_close = true`)
+- **Two-Step Closure Process**: When a contract has an active rental, you must:
+  1. Use `closeRental()` to close the rental (when expired)
+  2. Then use `closeContract()` to close the flagged contract
 
 ```typescript
-const cancelIx = await cancelRental({
-  borrower: wallet,
+// Step 1: Close the expired rental
+const closeRentalIx = await closeRental({
+  borrower: borrowerWallet,
   contract: contractAddress,
-  rentalState: rentalStateAddress
+  rentalState: rentalStateAddress,
+  ownerTokenAccount: ownerTokenAccountAddress
 });
-```
 
-**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
+// Step 2: Close the flagged contract (must be done by contract owner)
+const closeContractIx = await closeContract({
+  owner: wallet,
+  fleet: fleetAddress,
+  contract: contractAddress,
+  faction: 'mud'
+});
 ```
 
-### 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
+**Thread-based Payment Processing**: The SRSLY program uses automated thread-based payment processing through the Antegen/Clockwork system. The `rental_pay` instruction automatically:
 
-## Payment Frequencies
+- Processes periodic payments from escrow to owner
+- Handles rental completion and cleanup when expired
+- Closes flagged contracts after rental ends
 
-The SDK supports multiple payment frequencies:
+Manual intervention is only needed when the automated system doesn't process successfully.
 
-- `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:
+### Rental Operations
 
 ```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
+import { acceptRental, cancelRental, closeRental, resetRental } from '@wuwei-labs/srsly';
+import { Transaction, PublicKey } from '@solana/web3.js';
 
-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:
+// Accept rental offer instruction (all addresses are strings)
+const acceptIx = await acceptRental({
+  borrower: borrowerWallet,                // signer object or string address
+  borrowerProfile: borrowerProfileAddress, // string address
+  borrowerFaction: 'mud',                  // or 1, 2, 3 (optional - auto-resolved from fleet)
+  contract: contractAddress,               // string address
+  duration: { days: 1 }                    // Smart duration parameter (v3)
+  // amount is calculated automatically based on contract rate
+});
 
-```typescript
-import { setConfig, setNetwork, getConfig, createContract } from '@wuwei-labs/srsly';
+// Cancel active rental instruction
+// Note: Must cancel at least one payment period before rental ends
+const cancelIx = await cancelRental({
+  borrower: borrowerWallet,
+  contract: contractAddress,
+  rentalState: rentalStateAddress
+});
 
-// Option 1: Full configuration
-setConfig({ 
-  network: 'mainnet',
-  gameId: 'custom-game-id...' 
+// Close completed rental instruction
+const closeIx = await closeRental({
+  borrower: borrowerWallet,
+  contract: contractAddress,
+  rentalState: rentalStateAddress,
+  ownerTokenAccount: ownerTokenAccountAddress
 });
 
-// Option 2: Network-only (convenience function)
-setNetwork('mainnet');
+// Reset rental instruction
+const resetIx = await resetRental({
+  borrower: borrowerWallet,
+  contract: contractAddress,
+  rentalState: rentalStateAddress
+});
 
-// Check current configuration
-console.log(getConfig()); // { network: 'mainnet' }
+// Convert any instruction to web3.js format for wallet compatibility
+const web3jsAcceptIx = await acceptRental(params).web3js(PublicKey);
+const web3jsCancelIx = await cancelRental(params).web3js(PublicKey);
 
-// All operations now use mainnet by default
-const ix1 = await createContract(params);
-const ix2 = await acceptRental(params);
+// Use in web3.js transactions
+const transaction = new Transaction()
+  .add(web3jsAcceptIx)
+  .add(web3jsCancelIx);
 ```
 
-### Per-Instruction Configuration
+## Configuration
 
-Override global configuration for specific instructions using the fluent `.set()` interface:
+The SDK provides simple configuration:
 
 ```typescript
-import { createContract, acceptRental } from '@wuwei-labs/srsly';
-
-// Assume global config is set to mainnet
-setConfig({ network: 'mainnet' });
+import { setConfig, getConfig, clearConfig } from '@wuwei-labs/srsly';
+
+// Set configuration (RPC URL is always required)
+setConfig({
+  rpcUrl: 'https://your-rpc-endpoint.com', // REQUIRED - no defaults provided
+  srslyProgramAddress: 'custom-program-address...', // Optional override
+  profileFactionProgramAddress: 'custom-profile-program...', // Optional override
+  gameId: 'custom-game-id...', // Optional override
+  atlasMint: 'custom-atlas-mint...' // Optional override
+});
 
-// Use global mainnet config
-const mainnetIx = await createContract(params);
+// Example configurations
+setConfig({
+  rpcUrl: 'https://api.mainnet-beta.solana.com'
+});
+setConfig({
+  rpcUrl: 'https://api.devnet.solana.com'
+});
 
-// Override to use devnet for this specific instruction
-const devnetIx = await createContract(params).set({ network: 'devnet' });
+// Check current configuration
+console.log(getConfig());
 
-// Override specific constants while keeping global network
-const customIx = await createContract(params).set({ 
-  sageProgramAddress: 'custom...',
-  gameId: 'custom...'
-  // network: 'mainnet' inherited from global config
-});
+// Reset to defaults (you'll need to setConfig again with rpcUrl)
+clearConfig();
 ```
 
 ### Configuration Options
 
-All SDK functions support these usage patterns:
+| Option | Type | Description | Default |
+|--------|------|-------------|---------|
+| `rpcUrl` | `string` | **REQUIRED** - RPC endpoint for fetching accounts | None (must provide) |
+| `srslyProgramAddress` | `string` | SRSLY program address override | `SRSLY1fq9TJqCk1gNSE7VZL2bztvTn9wm4VR8u8jMKT` |
+| `profileFactionProgramAddress` | `string` | Profile Faction program override | Network dependent |
+| `gameId` | `string` | SAGE game ID override | Network dependent |
+| `atlasMint` | `string` | ATLAS token mint override | Network dependent |
 
-**Direct await (uses global config or devnet fallback):**
+## Duration and Payment Frequency
 
-```typescript
-// Uses global configuration if set, otherwise devnet
-await createContract(params);
-await acceptRental(params);
-```
+**Important**: All durations must be aligned with the payment frequency to ensure proper payment calculations.
 
-**Global configuration functions:**
+### Duration Rules
 
-- `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
+1. **Duration Units**: Use smart duration objects (`{ days: 7 }`) or raw seconds for backwards compatibility
+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
 
-**Per-instruction overrides with `.set()` method:**
+### Payment Frequency Intervals
 
-- `.set({ network: 'mainnet' })` - Override global network
-- `.set({ sageProgramAddress: '...' })` - Override specific constants only
-- `.set({ network: 'mainnet', sageProgramAddress: '...' })` - Multiple overrides
+| 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) |
 
-**Chainable configurations:**
+### Examples
 
 ```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
-```
+// ✅ Valid: 7 day max duration with daily payments
+await createContract({
+  rate: 10,                        // 10 ATLAS per day (v3 default)
+  durationMax: { days: 7 },        // Smart duration parameter
+  paymentsFreq: 'daily'            // Min duration automatically set to 1 day
+});
 
-### Available Configuration Options
+// ❌ Invalid: 3.5 day max duration with daily payments
+await createContract({
+  rate: 10,
+  durationMax: 302400,             // 3.5 days (302400 % 86400 = 43200) ✗
+  paymentsFreq: 'daily'
+});
+// Error: Duration (302400 seconds) must be a multiple of daily frequency (86400 seconds)
 
-```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
-}
+// ✅ Valid: Hourly payments with hour-aligned max duration
+await createContract({
+  rate: 1,                         // 1 ATLAS per hour
+  durationMax: { hours: 48 },      // 48 hours (smart parameter)
+  paymentsFreq: 'hourly'           // Min duration automatically set to 1 hour
+});
 ```
 
-### Network-Specific Constants
+### Rate Calculation
 
-The SDK automatically resolves network-specific constants:
-
-```typescript
-import { 
-  getSageProgramAddress, 
-  getProfileFactionProgramAddress, 
-  getSageGameId 
-} from '@wuwei-labs/srsly';
+The `rate` parameter in contracts represents ATLAS tokens per payment period that the owner will receive:
 
-// Get constants for devnet (default)
-const sageProgram = await getSageProgramAddress();
-const gameId = await getSageGameId();
+- For `daily` frequency: rate is ATLAS per day
+- For `weekly` frequency: rate is ATLAS per week
+- For `hourly` frequency: rate is ATLAS per hour
 
-// Get constants for specific network
-const mainnetSageProgram = await getSageProgramAddress({ network: 'mainnet' });
-const mainnetGameId = await getSageGameId({ network: 'mainnet' });
-```
+**Important**: The 10% service fee is collected upfront from the borrower. The rental state stores the net rate (after fees) to ensure consistent payments to the owner regardless of future fee changes.
 
-## IDL and Types
+## Payment System
 
-### Network-Specific IDLs
+SRSLY implements an escrow-based payment system:
 
-The SDK provides network-specific IDLs since program configurations differ between networks:
+1. **Escrow**: Borrower deposits full rental amount upfront
+2. **Service Fee**: 10% fee collected upfront at rental acceptance
+3. **Net Rate**: Rental state stores the net rate (after fees), ensuring owners receive consistent payments
+4. **Periodic Payments**: Automated payments based on frequency (hourly/daily/weekly/monthly)
+5. **Refunds**: Pro-rata refunds for early cancellation (must cancel at least one payment period before rental ends)
 
 ```typescript
-// Mainnet IDL
-import mainnetIdl from '@wuwei-labs/srsly/idl/mainnet';
+// Payment calculation example (v3 with ATLAS as default)
+const rate = 10; // 10 ATLAS per day (v3 default unit)
+const paymentFrequency = 'daily'; // Payment every 86400 seconds
+const durationDays = 7; // 7 days
+const paymentPeriods = 7; // 7 daily periods
+const grossAmount = rate * paymentPeriods; // 70 ATLAS total
+const serviceFee = grossAmount * 0.10; // 7 ATLAS fee (10%)
+const netAmount = grossAmount - serviceFee; // 63 ATLAS to escrow
+
+// The rental state will store: netAmount / paymentPeriods = 9 ATLAS per period
+// This ensures the owner receives the full rate regardless of fee changes
+```
 
-// Devnet IDL  
-import devnetIdl from '@wuwei-labs/srsly/idl/devnet';
+## Program Information
 
-// Use with Anchor
-import { Program } from '@coral-xyz/anchor';
-const program = new Program(mainnetIdl, provider);
-```
+The SRSLY program is network agnostic with the same address across all networks:
 
-### Network-Specific Types
+**SRSLY Program ID**: `SRSLY1fq9TJqCk1gNSE7VZL2bztvTn9wm4VR8u8jMKT`
 
-Import TypeScript types that match your target network:
+Note: While the SRSLY program is network agnostic, Star Atlas programs (SAGE, Profile, etc.) may have different addresses on different networks. The SDK will automatically detect these based on your RPC endpoint.
+
+## Types and Constants
 
 ```typescript
-import type { 
+import type {
   ContractState,
   RentalState,
-  PaymentFrequency,
-  ClockData,
-  ThreadResponse,
-  ConfigOptions
+  ConfigOptions,
+  PaymentFrequency
 } 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';
-```
-
-## Constants and Utilities
-
-### Available Constants
-
-```typescript
-import { 
+import {
   ATLAS_TO_STARDUST,
-  STARBASE_SEED,
-  STARBASE_PLAYER_SEED,
-  SAGE_PLAYER_PROFILE_SEED,
-  PROFILE_FACTION_SEED,
-  FACTION_MAPPING,
-  FACTION_SPECIFIC_CSS
+  FACTION_MAPPING
 } 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'
+
+// Smart duration parameters (v3)
+// Use objects for duration: { days: 7 }, { hours: 12 }, { months: 1 }
+// Or raw seconds for backwards compatibility: 604800
 ```
 
-### Profile Derivation
+## IDL and Program Information
 
 ```typescript
-import { 
-  deriveProfileFaction,
-  deriveSagePlayerProfile,
-  deriveStarbase,
-  deriveStarbasePlayer,
-  deriveGameAccounts
-} from '@wuwei-labs/srsly';
+// Access program IDL
+import idl from '@wuwei-labs/srsly/idl';
+```
 
-// 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' }
-);
+## Error Handling
+
+```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);
+  }
+}
 ```
 
-## Documentation
+## Package Structure
 
-- **TypeDoc Documentation**: [API Reference](https://wuwei-labs.github.io/srsly/)
+The SDK provides optimized builds for different environments:
+
+- **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)
 
-## 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/)
+- **Browser Usage Examples**: [Browser Integration Guide](./examples/browser-usage.md)
+- **Universal Signer Tests**: [Test Examples](./tests/features/universal-signer.test.mjs)