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

package/dist/types/idl/srsly-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"srsly-data.d.ts","sourceRoot":"","sources":["../../../src/idl/srsly-data.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwjGN,CAAC;AACX,eAAe,GAAG,CAAC"}

package/dist/types/index.d.ts

@@ -1,6 +1,214 @@
-export * from "./contract";
-export * from "./rental";
-export * from "./utils";
-export type { ContractState, RentalState, Fleet, CreateContractInstruction, AcceptRentalInstruction, CancelRentalInstruction, CloseRentalInstruction, CloseContractInstruction, ResetRentalInstruction, ClockData, ThreadResponse } from "./codama/devnet";
-export { PaymentFrequency } from "./utils/constants";
+/**
+ * @purpose SRSLY SDK - Solana Rental System Library main entry point
+ * @reviewed 2025-07-29
+ *
+ * A comprehensive TypeScript SDK for interacting with the SRSLY Solana program,
+ * which facilitates fleet rentals in the Star Atlas ecosystem. This SDK provides
+ * a fluent, developer-friendly interface that works with both @solana/kit and
+ * @solana/web3.js libraries.
+ *
+ * ## Features
+ *
+ * - **Universal Compatibility**: Works with both @solana/kit and @solana/web3.js
+ * - **Fluent API**: Chainable methods for intuitive development experience
+ * - **String-Based Addresses**: Uses strings for all addresses to eliminate library conflicts
+ * - **Network Agnostic**: Supports mainnet, devnet, and custom RPC endpoints
+ * - **Type Safety**: Full TypeScript support with comprehensive type definitions
+ * - **Auto-Generated Types**: Types generated from Solana program IDL for accuracy
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { createContract, acceptRental } from '@srsly/sdk';
+ *
+ * // Create a rental contract
+ * const instruction = await createContract({
+ *   owner: wallet,
+ *   fleet: "FleetAddress123...",
+ *   ownerProfile: "ProfileAddr...",
+ *   rate: 1000,
+ *   durationMax: 7,  // 7 payment periods (7 days for @daily)
+ *   paymentsFreq: 'daily'
+ * });
+ *
+ * // Accept a rental
+ * const rentalInstruction = await acceptRental({
+ *   borrower: borrowerWallet,
+ *   contract: contractAddress,
+ *   amount: 7000,
+ *   duration: { days: 7 }  // Smart parameter format
+ * });
+ * ```
+ *
+ * ## Architecture
+ *
+ * The SDK is organized into several main modules:
+ * - **Contract**: Functions for creating and managing rental contracts
+ * - **Rental**: Functions for rental operations (accept, cancel, close)
+ * - **Utils**: Helper functions for duration, payment frequency, and account management
+ * - **Types**: TypeScript type definitions and interfaces
+ *
+ * @packageDocumentation
+ */
+export * from './contract';
+export * from './rental';
+export * from './config';
+export { setSdkConfig as setConfig, getSdkConfig as getConfig, clearSdkConfig as clearConfig, resolveProgramAddresses, type SdkConfigOptions, type SdkConfigSelector, type PublicKeyConstructor, type ProgramSet, } from './utils/config';
+export * from './utils';
+export type { KitInstruction, FluentInstruction } from './utils/instruction-converter';
+export type { ConfigState, ContractState, RentalState, CreateContractInstruction, AcceptRentalInstruction, CancelRentalInstruction, CloseRentalInstruction, CloseContractInstruction, ResetRentalInstruction, ClockData, ThreadResponse, } from './generated/codama';
+/**
+ * Account fetch functions that work with any RPC endpoint.
+ *
+ * These functions accept RPC URL strings and return account data,
+ * making it easy to fetch program state from any network.
+ *
+ * @example
+ * ```typescript
+ * const contract = await fetchContractState(
+ *   "https://api.mainnet-beta.solana.com",
+ *   contractAddress
+ * );
+ *
+ * // Fetch SAGE fleet data using manual struct parsing
+ * const fleet = await fetchFleetState(fleetAddress);
+ * ```
+ */
+export { fetchContractState, fetchRentalState, fetchConfigState, fetchFleetState, fetchMultipleContractStates, fetchMultipleRentalStates, type FleetState, } from './utils/fetch-accounts';
+/**
+ * Payment frequency enum generated from the Rust program.
+ *
+ * This enum mirrors the Rust PaymentFrequency type and provides
+ * type-safe payment frequency values for contract creation.
+ */
+export { PaymentFrequency } from './types/payment-frequency';
+/**
+ * Payment frequency types and validation utilities.
+ *
+ * These exports provide string-based payment frequency handling,
+ * validation functions, and mapping between different representations.
+ *
+ * @example
+ * ```typescript
+ * if (isValidPaymentFrequency('daily')) {
+ *   const frequency = getPaymentFrequencyFromString('daily');
+ * }
+ * ```
+ */
+export { PaymentFrequencyString, VALID_PAYMENT_FREQUENCIES, PAYMENT_FREQUENCY_MAP, PAYMENT_FREQUENCY_CONSTANTS, PAYMENT_FREQUENCY_TO_CRON, CRON_TO_PAYMENT_FREQUENCY, getPaymentFrequencyFromString, isValidPaymentFrequency, } from './types/payment-frequency';
+/**
+ * Payment frequency utilities that mirror the Rust program implementation.
+ *
+ * These functions provide conversion between payment frequencies and time durations,
+ * ensuring consistency with the on-chain program logic.
+ *
+ * @example
+ * ```typescript
+ * const seconds = paymentFrequencyStringToSeconds('weekly');
+ * validateDurationAlignment(duration, 'daily');
+ * ```
+ */
+export { paymentFrequencyToSeconds, paymentFrequencyStringToSeconds, validateDurationAlignment, normalizePaymentSchedule, } from './utils/payment-frequency';
+/**
+ * Cron expression utilities for advanced payment scheduling.
+ *
+ * These functions provide cron expression parsing, validation, and scheduling
+ * capabilities using the croner library, mirroring the Rust implementation.
+ *
+ * @example
+ * ```typescript
+ * // Validate a cron expression
+ * if (validateCronExpression("0 9 * * MON-FRI")) {
+ *   // Calculate next payment time
+ *   const nextPayment = getNextCronOccurrence("@daily", Date.now() / 1000);
+ * }
+ *
+ * // Preview payment schedule
+ * const schedule = calculatePaymentSchedule("@hourly", startTime, duration);
+ * console.log(`${schedule.totalPayments} payments will occur`);
+ * ```
+ */
+export { getNextCronOccurrence, validateCronExpression, paymentFrequencyToCron, parseScheduleString, calculatePaymentSchedule, formatPaymentSchedulePreview, } from './utils/cron';
+/**
+ * Schedule validation utilities for rental contracts.
+ *
+ * These functions validate payment schedules against contract constraints
+ * and provide detailed feedback on potential issues.
+ *
+ * @example
+ * ```typescript
+ * const validation = validateRentalSchedule(
+ *   "@daily",
+ *   { days: 7 },   // Smart parameter format
+ *   { days: 1 },   // Smart parameter format
+ *   { days: 30 }   // Smart parameter format
+ * );
+ *
+ * if (validation.valid) {
+ *   console.log(`${validation.paymentCount} payments scheduled`);
+ * }
+ * ```
+ */
+export { validateRentalSchedule, validateFrequencyForDuration, type ScheduleValidationResult, } from './utils/schedule-validation';
+/**
+ * Schedule builder for creating and previewing payment schedules.
+ *
+ * Provides a fluent API for building payment schedules with validation
+ * and preview capabilities.
+ *
+ * @example
+ * ```typescript
+ * // From standard frequency
+ * const schedule = ScheduleBuilder
+ *   .fromFrequency("daily")
+ *   .preview(Date.now() / 1000, { days: 7 });
+ *
+ * // Custom cron expression
+ * const custom = ScheduleBuilder
+ *   .fromCron("0 12 * * MON")
+ *   .validate({ days: 30 }, { days: 1 }, { days: 90 });
+ *
+ * // Common intervals
+ * const every3Hours = ScheduleBuilder
+ *   .every('hours', 3)
+ *   .preview(Date.now() / 1000, { days: 1 });
+ * ```
+ */
+export { ScheduleBuilder, createSchedule, type SchedulePreview, type PaymentInfo, } from './utils/schedule-builder';
+/**
+ * Duration helper functions (DEPRECATED)
+ *
+ * Duration helper functions have been deprecated in favor of smart parameters.
+ * Use the smart parameter format instead for better type safety and clarity.
+ *
+ * @example
+ * ```typescript
+ * // Old approach (deprecated):
+ * // const rentalDuration = days(7);
+ *
+ * // New approach with smart parameters:
+ * const rentalDuration = { days: 7 };
+ * const paymentPeriod = { hours: 6 };
+ * const longRental = { weeks: 2 };
+ * ```
+ */
+/**
+ * SRSLY Program IDL
+ *
+ * Export the complete IDL for the SRSLY program, useful for:
+ * - Building custom decoders
+ * - Generating client code
+ * - Inspecting program structure
+ * - Version-aware deserialization
+ */
+export { IDL, type IDL as IDLType } from './idl';
+/**
+ * Legacy versioned decoders are now deprecated.
+ *
+ * Use the native Codama lazy decoder instead:
+ * - Replace: fetchMaybeRentalStateVersioned(rpc, address)
+ * - With: fetchMaybeRentalState(rpc, address, { lazy: true })
+ *
+ * The lazy decoder is available in all generated account fetch functions.
+ */
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AAIxB,YAAY,EAEV,aAAa,EACb,WAAW,EACX,KAAK,EAGL,yBAAyB,EACzB,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,EACtB,wBAAwB,EACxB,sBAAsB,EAGtB,SAAS,EACT,cAAc,EACf,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAGH,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AAGzB,cAAc,UAAU,CAAC;AAGzB,OAAO,EACL,YAAY,IAAI,SAAS,EACzB,YAAY,IAAI,SAAS,EACzB,cAAc,IAAI,WAAW,EAC7B,uBAAuB,EAEvB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,UAAU,GAChB,MAAM,gBAAgB,CAAC;AAExB,cAAc,SAAS,CAAC;AAGxB,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAIvF,YAAY,EAEV,WAAW,EACX,aAAa,EACb,WAAW,EAGX,yBAAyB,EACzB,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,EACtB,wBAAwB,EACxB,sBAAsB,EAGtB,SAAS,EACT,cAAc,GACf,MAAM,oBAAoB,CAAC;AAE5B;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,2BAA2B,EAC3B,yBAAyB,EACzB,KAAK,UAAU,GAChB,MAAM,wBAAwB,CAAC;AAEhC;;;;;GAKG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAE7D;;;;;;;;;;;;GAYG;AACH,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,qBAAqB,EACrB,2BAA2B,EAC3B,yBAAyB,EACzB,yBAAyB,EACzB,6BAA6B,EAC7B,uBAAuB,GACxB,MAAM,2BAA2B,CAAC;AAEnC;;;;;;;;;;;GAWG;AACH,OAAO,EACL,yBAAyB,EACzB,+BAA+B,EAC/B,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,2BAA2B,CAAC;AAEnC;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,mBAAmB,EACnB,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,cAAc,CAAC;AAEtB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EACL,sBAAsB,EACtB,4BAA4B,EAC5B,KAAK,wBAAwB,GAC9B,MAAM,6BAA6B,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EACL,eAAe,EACf,cAAc,EACd,KAAK,eAAe,EACpB,KAAK,WAAW,GACjB,MAAM,0BAA0B,CAAC;AAElC;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;GAQG;AACH,OAAO,EAAE,GAAG,EAAE,KAAK,GAAG,IAAI,OAAO,EAAE,MAAM,OAAO,CAAC;AAEjD;;;;;;;;GAQG"}

package/dist/types/rental/accept.d.ts

@@ -1,92 +1,196 @@
-import { Address, TransactionSigner } from '@solana/kit';
-import { type ConfigSelector } from '../utils/config';
-type AcceptRentalInstruction = any;
 /**
- * Simplified parameters for accepting a rental
+ * @purpose Rental contract acceptance with payment calculation and SAGE integration
+ * @reviewed 2025-07-29
+ */
+import { type SdkConfigSelector } from '../utils/config';
+import { type FluentInstruction, type SmartFluentConfigSelector } from '../utils/instruction-converter';
+import { type UniversalSigner } from '../utils/signer';
+import type { DurationParam } from '../utils/smart-params';
+type UniversalAddress = string;
+/**
+ * Parameters for accepting a rental contract.
+ *
+ * This interface defines the required parameters for a borrower to accept an existing
+ * rental contract. The SDK automatically fetches contract details and calculates the
+ * required payment amount based on the contract's rate and payment frequency.
+ *
+ * @interface AcceptRentalParams
  */
 export interface AcceptRentalParams {
     /**
-     * The borrower wallet that will sign the transaction
-     */
-    borrower: TransactionSigner<string>;
-    /**
-     * The borrower's profile account address
-     */
-    borrowerProfile: Address<string>;
-    /**
-     * The borrower's faction (1 = mud, 2 = oni, 3 = ustur)
-     * Or as string: 'mud', 'oni', 'ustur'
-     */
-    borrowerFaction: number | string;
-    /**
-     * The fleet account address that will be rented
+     * The borrower who will rent the fleet (signer object or base58 string address).
+     * This account will control the fleet during the rental period and make payments.
+     * Can be a wallet/signer object (CLI usage) or base58 address string (browser usage).
      */
-    fleet: Address<string>;
+    borrower: UniversalSigner;
     /**
-     * The rental contract account address
+     * String address of the borrower's profile in the Star Atlas game.
+     * Used for SAGE integration to transfer fleet control to the borrower.
      */
-    contract: Address<string>;
+    borrowerProfile: UniversalAddress;
     /**
-     * The game ID account address
-     * If not provided, will use network-specific default
+     * Faction identifier for the borrower in Star Atlas.
+     * Can be provided as a number (1 = MUD, 2 = ONI, 3 = Ustur) or string ('mud', 'oni', 'ustur').
+     * If not provided, the faction will be automatically resolved from the fleet account.
+     * Used for deriving faction-specific game accounts required by SAGE.
+     * @example 'mud' // or 1
      */
-    gameId?: Address<string>;
+    borrowerFaction?: number | string;
     /**
-     * The rental rate (in ATLAS tokens)
+     * String address of the rental contract to accept.
+     * The SDK will automatically fetch the contract state to retrieve:
+     * - Fleet address and ownership details
+     * - Rental rate per payment period
+     * - Payment frequency (hourly, daily, weekly, monthly)
+     * - Duration constraints (minimum and maximum)
+     * - Owner information for payment routing
      */
-    rate: number | bigint;
+    contract: UniversalAddress;
     /**
-     * The rental duration (in seconds)
+     * Rental duration.
+     * Can be specified as seconds (number) or time units (object).
+     * Must be within the contract's minimum and maximum duration limits.
+     * @example { days: 7 } // 7 days
+     * @example { weeks: 2 } // 2 weeks
+     * @example 604800 // 7 days in seconds (backwards compatible)
      */
-    duration: number | bigint;
-    /**
-     * Optional referral token account address
-     * If provided, referrer will receive 5% of the platform fees
-     */
-    referralTokenAccount?: Address<string>;
+    duration: DurationParam;
 }
 /**
- * Creates an instruction to accept a rental with fluent configuration.
+ * Creates an instruction to accept a rental contract with fluent configuration.
+ *
+ * This function allows a borrower to accept an existing rental contract, automatically
+ * calculating the required payment amount based on the contract's rate and payment frequency.
+ * The SDK fetches contract details, validates duration constraints, and derives all
+ * necessary accounts for the rental operation.
+ *
+ * ## Features
+ *
+ * - **Automatic Payment Calculation**: Fetches contract state and calculates exact payment amount
+ * - **Automatic Faction Resolution**: Optionally fetches faction from fleet account if not provided
+ * - **Duration Validation**: Ensures rental duration meets contract constraints
+ * - **Account Derivation**: Automatically derives all required game accounts
+ * - **SAGE Integration**: Sets up fleet ownership transfer in the Star Atlas ecosystem
+ * - **Clockwork Integration**: Configures automated payment scheduling
+ * - **Universal Library Support**: Works with both @solana/kit and @solana/web3.js
+ *
+ * ## Process
+ *
+ * 1. **Fetch Contract**: Retrieves contract state from the blockchain
+ * 2. **Validate Duration**: Checks that rental duration meets contract constraints
+ * 3. **Calculate Payment**: Computes payment amount using contract rate and payment frequency
+ * 4. **Derive Accounts**: Generates required game accounts (starbase, faction, etc.)
+ * 5. **Create Instruction**: Builds the rental acceptance instruction
+ * 6. **Setup Threading**: Configures automated payment processing
+ *
+ * ## Payment Calculation
+ *
+ * The payment amount is calculated using the formula:
+ * ```text
+ * payment = rate × payment_periods × stardust_to_atlas_conversion
+ * ```
+ *
+ * Where:
+ * - `rate`: Contract's rental rate per payment period
+ * - `payment_periods`: Duration divided by payment frequency interval
+ * - `stardust_to_atlas_conversion`: Network-specific conversion factor
+ *
+ * ## Requirements
+ *
+ * - Contract must exist and be active
+ * - Duration must be within contract's min/max limits
+ * - Duration must be multiple of payment frequency
+ * - Borrower must have sufficient ATLAS tokens for payment
  *
  * @example
  * ```typescript
- * // Use devnet defaults
- * const ix = await acceptRental({
+ * import { acceptRental } from '@srsly/sdk';
+ *
+ * // Using smart duration parameters (recommended)
+ * const instruction = await acceptRental({
+ *   borrower: wallet,                      // Wallet object for signing
+ *   borrowerProfile: "ProfileAddr...",     // Borrower's Star Atlas profile
+ *   contract: "ContractAddr...",           // Contract to accept
+ *   duration: { days: 7 }                  // 7 days rental duration
+ *   // borrowerFaction auto-resolved from fleet account
+ * });
+ *
+ * // Different duration formats
+ * const hourlyRental = await acceptRental({
+ *   borrower: wallet,
+ *   borrowerProfile: "ProfileAddr...",
+ *   contract: "ContractAddr...",
+ *   duration: { hours: 12 }                // 12 hours
+ * });
+ *
+ * const weeklyRental = await acceptRental({
  *   borrower: wallet,
- *   borrowerProfile: profileAddress,
- *   borrowerFaction: 1, // 1 = mud, 2 = oni, 3 = ustur
- *   fleet: fleetAddress,
- *   contract: contractAddress,
- *   rate: 1000, // ATLAS tokens
- *   duration: 86400  // 1 day in seconds (total: 1000 * 86400 * 100M stardust)
+ *   borrowerProfile: "ProfileAddr...",
+ *   contract: "ContractAddr...",
+ *   duration: { weeks: 2 }                 // 2 weeks
  * });
  *
- * // With referral (referrer gets 5% of platform fees)
- * const ix = await acceptRental({
+ * const monthlyRental = await acceptRental({
  *   borrower: wallet,
- *   borrowerProfile: profileAddress,
- *   borrowerFaction: 1,
- *   fleet: fleetAddress,
- *   contract: contractAddress,
- *   rate: 1000,
- *   duration: 86400,
- *   referralTokenAccount: referrerTokenAddress
+ *   borrowerProfile: "ProfileAddr...",
+ *   contract: "ContractAddr...",
+ *   duration: { months: 1 }                // 1 month
  * });
  *
- * // Use mainnet configuration
- * const ix = await acceptRental(params).set({ network: 'mainnet' });
+ * // Backwards compatible - raw seconds
+ * const legacyRental = await acceptRental({
+ *   borrower: wallet,
+ *   borrowerProfile: "ProfileAddr...",
+ *   contract: "ContractAddr...",
+ *   duration: 604800                       // 7 days in seconds
+ * });
  *
- * // Override specific constants
- * const ix = await acceptRental(params).set({
- *   network: 'mainnet',
- *   gameId: 'custom-game-id...'
+ * // Manual faction specification (optional)
+ * const manualInstruction = await acceptRental({
+ *   borrower: wallet.publicKey.toString(), // Address string for browser
+ *   borrowerProfile: "ProfileAddr...",     // Borrower's Star Atlas profile
+ *   borrowerFaction: 'mud',                // Optional: 'mud', 'oni', or 'ustur'
+ *   contract: "ContractAddr...",           // Contract to accept
+ *   duration: { days: 7 }                  // 7 days rental duration
  * });
+ *
+ * // Configure for mainnet
+ * const mainnetInstruction = await acceptRental({
+ *   borrower: wallet,                      // Wallet object (CLI style)
+ *   borrowerProfile: "ProfileAddr...",
+ *   borrowerFaction: 1,                    // Can use numbers: 1=mud, 2=oni, 3=ustur
+ *   contract: "ContractAddr...",
+ *   duration: { days: 7 }
+ * }).set({ programs: 'mainnet' });
+ *
+ * // Use with your preferred Solana library
+ * const transaction = new Transaction().add(mainnetInstruction);
+ * await sendAndConfirmTransaction(connection, transaction, [wallet]);
  * ```
  *
- * @param params The simplified parameters for accepting a rental
- * @returns A ConfigSelector that can be configured with .set() or awaited directly
+ * @param params - The rental acceptance parameters including borrower, contract, and duration
+ * @returns A SmartFluentConfigSelector that can be configured with .set() or awaited directly
+ * @throws Error when contract is not found, duration constraints are violated, or payment calculation fails
+ */
+export declare function acceptRental(params: AcceptRentalParams): SmartFluentConfigSelector<FluentInstruction>;
+/**
+ * Low-level function to create a rental acceptance instruction with raw input parameters.
+ *
+ * This function provides direct access to the underlying codama-generated instruction
+ * builder. It's primarily used internally by the SDK but can be used for advanced
+ * use cases where full control over instruction parameters is needed.
+ *
+ * @internal
+ * @param input - Raw instruction input parameters as expected by codama
+ * @param options - Optional instruction options including program address
+ * @returns A SdkConfigSelector for the raw instruction
  */
-export declare function acceptRental(params: AcceptRentalParams): ConfigSelector<AcceptRentalInstruction>;
-export declare function getAcceptRentalInstructionAsync(input: any, options?: any): ConfigSelector<any>;
+export declare function getAcceptRentalInstructionAsync(input: any, options?: any): SdkConfigSelector<any>;
+export declare const acceptRentalDemo: {
+    tabName: string;
+    description: string;
+    imports: string;
+    instruction: string;
+};
 export {};
 //# sourceMappingURL=accept.d.ts.map

package/dist/types/rental/accept.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"accept.d.ts","sourceRoot":"","sources":["../../../src/rental/accept.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAgD,KAAK,cAAc,EAAsB,MAAM,iBAAiB,CAAC;AAKxH,KAAK,uBAAuB,GAAG,GAAG,CAAC;AAMnC;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,QAAQ,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAEpC;;OAEG;IACH,eAAe,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAEjC;;;OAGG;IACH,eAAe,EAAE,MAAM,GAAG,MAAM,CAAC;IAEjC;;OAEG;IACH,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAEvB;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAE1B;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAEzB;;OAEG;IACH,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAEtB;;OAEG;IACH,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAE1B;;;OAGG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;CACxC;AAkED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,kBAAkB,GACzB,cAAc,CAAC,uBAAuB,CAAC,CAEzC;AAED,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,cAAc,CAAC,GAAG,CAAC,CAK9F"}
+{"version":3,"file":"accept.d.ts","sourceRoot":"","sources":["../../../src/rental/accept.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAKL,KAAK,iBAAiB,EAEvB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,yBAAyB,EAC/B,MAAM,gCAAgC,CAAC;AAIxC,OAAO,EAA2B,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAChF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAI3D,KAAK,gBAAgB,GAAG,MAAM,CAAC;AAG/B;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,QAAQ,EAAE,eAAe,CAAC;IAE1B;;;OAGG;IACH,eAAe,EAAE,gBAAgB,CAAC;IAElC;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAElC;;;;;;;;OAQG;IACH,QAAQ,EAAE,gBAAgB,CAAC;IAE3B;;;;;;;OAOG;IACH,QAAQ,EAAE,aAAa,CAAC;CACzB;AAmID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmHG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,kBAAkB,GACzB,yBAAyB,CAAC,iBAAiB,CAAC,CAG9C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAKjG;AAGD,eAAO,MAAM,gBAAgB;;;;;CAU5B,CAAC"}

package/dist/types/rental/cancel.d.ts

@@ -1,44 +1,141 @@
-import { Address, TransactionSigner } from '@solana/kit';
-import { type ConfigSelector } from '../utils/config';
-type CancelRentalInstruction = any;
 /**
- * Simplified parameters for canceling a rental
+ * @purpose Rental cancellation with penalty processing and thread cleanup
+ * @reviewed 2025-07-29
+ */
+import { type SdkConfigSelector } from '../utils/config';
+import { type UniversalSigner } from '../utils/signer';
+import { type FluentInstruction, type SmartFluentConfigSelector } from '../utils/instruction-converter';
+type UniversalAddress = string;
+/**
+ * Parameters for canceling an active rental.
+ *
+ * This interface defines the required parameters for a borrower to cancel their
+ * active rental. Canceling a rental stops automated payments but typically
+ * incurs a penalty fee as defined in the contract terms.
+ *
+ * You can provide either the contract address OR the rental state address.
+ * If both are provided, rental takes priority.
+ *
+ * @interface CancelRentalParams
  */
 export interface CancelRentalParams {
     /**
-     * The borrower wallet that will sign the transaction
+     * The borrower who wants to cancel the rental (signer object or base58 string address).
+     * Must be the original borrower who accepted the rental contract.
+     * This account will pay any cancellation penalties.
+     * Can be a wallet/signer object (CLI usage) or base58 address string (browser usage).
+     */
+    borrower: UniversalSigner;
+    /**
+     * String address of the rental contract associated with the active rental.
+     * The rental state for this contract will be canceled and automated payments stopped.
+     *
+     * Either this OR rental must be provided. If both are provided, rental takes priority.
      */
-    borrower: TransactionSigner<string>;
+    contract?: UniversalAddress;
     /**
-     * The rental contract account address
+     * String address of the rental state account to cancel.
+     * This is an alternative to providing the contract address - the SDK will
+     * fetch the rental state to determine the associated contract.
+     *
+     * Either this OR contract must be provided. If both are provided, this takes priority.
      */
-    contract: Address<string>;
+    rental?: UniversalAddress;
 }
 /**
  * Creates an instruction to cancel a rental with fluent configuration.
  *
+ * This function allows a borrower to cancel their active rental before the
+ * rental period expires. Canceling a rental stops automated payments but
+ * may incur penalty fees as defined in the contract terms. The fleet ownership
+ * is immediately returned to the original owner.
+ *
+ * ## Features
+ *
+ * - **Immediate Cancellation**: Stops the rental and automated payments immediately
+ * - **Fleet Transfer**: Returns fleet control to the original owner
+ * - **Thread Cleanup**: Cancels the automated payment thread
+ * - **Penalty Processing**: Handles any cancellation fees as defined in the contract
+ * - **Universal Library Support**: Works with both @solana/kit and @solana/web3.js
+ *
+ * ## Process
+ *
+ * 1. **Validate Authority**: Ensures only the borrower can cancel their rental
+ * 2. **Calculate Penalties**: Computes any cancellation fees owed
+ * 3. **Transfer Fleet**: Returns fleet ownership to the original owner
+ * 4. **Cancel Thread**: Stops automated payment processing
+ * 5. **Update State**: Marks rental as canceled in the rental state account
+ *
+ * ## Requirements
+ *
+ * - Rental must be active (not already canceled or completed)
+ * - Caller must be the original borrower
+ * - Borrower must have sufficient funds for any cancellation penalties
+ *
+ * ## Cancellation Effects
+ *
+ * - **Fleet Control**: Immediately returned to owner
+ * - **Automated Payments**: Stopped permanently
+ * - **Rental State**: Marked as canceled
+ * - **Thread Account**: Cleaned up and closed
+ * - **Penalties**: Charged according to contract terms
+ *
  * @example
  * ```typescript
- * // Use devnet defaults
- * const ix = await cancelRental({
+ * import { cancelRental } from '@srsly/sdk';
+ *
+ * // Cancel rental using contract address
+ * const instruction = await cancelRental({
  *   borrower: wallet,
- *   contract: contractAddress
+ *   contract: "ContractAddr..."
  * });
  *
- * // Use mainnet configuration
- * const ix = await cancelRental(params).set({ network: 'mainnet' });
- *
- * // Override specific constants
- * const ix = await cancelRental(params).set({
- *   network: 'mainnet',
- *   sageProgramAddress: 'custom...'
+ * // Cancel rental using rental state address (alternative approach)
+ * const instruction2 = await cancelRental({
+ *   borrower: wallet,
+ *   rental: "RentalStateAddr..."
  * });
+ *
+ * // Configure for mainnet
+ * const mainnetInstruction = await cancelRental({
+ *   borrower: wallet,
+ *   contract: "ContractAddr..."
+ * }).set({ programs: 'mainnet' });
+ *
+ * // Convert to @solana/web3.js format
+ * const web3jsInstruction = await cancelRental({
+ *   borrower: wallet,
+ *   rental: "RentalStateAddr..."
+ * }).web3js();
+ *
+ * // Use with your preferred Solana library
+ * const transaction = new Transaction().add(web3jsInstruction);
+ * await sendAndConfirmTransaction(connection, transaction, [wallet]);
  * ```
  *
- * @param params The simplified parameters for canceling a rental
- * @returns A ConfigSelector that can be configured with .set() or awaited directly
+ * @param params - The rental cancellation parameters including borrower and either contract or rentalState
+ * @returns A SmartFluentConfigSelector that can be configured with .set() or awaited directly
+ * @throws Error when rental is not active, caller is not the borrower, or instruction generation fails
+ */
+export declare function cancelRental(params: CancelRentalParams): SmartFluentConfigSelector<FluentInstruction>;
+/**
+ * Low-level function to create a rental cancellation instruction with raw input parameters.
+ *
+ * This function provides direct access to the underlying codama-generated instruction
+ * builder. It's primarily used internally by the SDK but can be used for advanced
+ * use cases where full control over instruction parameters is needed.
+ *
+ * @internal
+ * @param input - Raw instruction input parameters as expected by codama
+ * @param options - Optional instruction options including program address
+ * @returns A SdkConfigSelector for the raw instruction
  */
-export declare function cancelRental(params: CancelRentalParams): ConfigSelector<CancelRentalInstruction>;
-export declare function getCancelRentalInstructionAsync(input: any, options?: any): ConfigSelector<any>;
+export declare function getCancelRentalInstructionAsync(input: any, options?: any): SdkConfigSelector<any>;
+export declare const cancelRentalDemo: {
+    tabName: string;
+    description: string;
+    imports: string;
+    instruction: string;
+};
 export {};
 //# sourceMappingURL=cancel.d.ts.map