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

package/dist/types/utils/derive-pda.d.ts

@@ -0,0 +1,213 @@
+/**
+ * @purpose PDA derivation utilities for multi-program architecture with cross-program integration
+ * @reviewed 2025-07-29
+ */
+/**
+ * # PDA Derivation Utilities for Multi-Program Architecture
+ *
+ * The SRSLY rental system integrates with multiple Solana programs, each requiring
+ * PDAs to be derived using their specific program IDs for proper cross-program
+ * invocation (CPI) and account ownership.
+ *
+ * ## Program Responsibilities:
+ * - **SRSLY Program**: Contract, Rental State, Rental Authority PDAs
+ * - **Antegen Program**: Automated payment threads via scheduling
+ * - **Profile Program**: Star Atlas SAGE profiles and starbase management
+ * - **Player Faction Program**: Player faction enrollment in SAGE ecosystem
+ *
+ * ## Cross-Program Integration:
+ * Each program owns its respective PDAs and must be used for derivation to
+ * ensure proper account ownership and enable CPI calls between programs.
+ *
+ * @note Future Enhancement: Consider requesting codama to auto-generate PDA
+ *       utilities alongside instruction code to reduce manual maintenance.
+ */
+import { type Address } from '@solana/kit';
+import { type ConfigState } from '../generated/codama/accounts';
+/**
+ * Derives the rental contract PDA using the SRSLY program ID
+ *
+ * Contract PDAs are derived from the fleet address and provide deterministic
+ * addresses for rental contracts without requiring a private key. The SDK
+ * automatically resolves the correct SRSLY program address for the current network
+ * unless a specific program ID is provided.
+ *
+ * @param fleet - The fleet address to create a contract for
+ * @param program - Optional SRSLY program ID (defaults to network-resolved address)
+ * @returns The contract PDA derived using SRSLY program ID
+ *
+ * @example
+ * ```typescript
+ * // Use network-resolved program address (recommended)
+ * const contractAddress = await deriveContract('FleetAddress123...');
+ *
+ * // Use specific program address
+ * const contractAddress = await deriveContract(
+ *   'FleetAddress123...',
+ *   'SRSLY1fq9TJqCk1gNSE7VZL2bztvTn9wm4VR8u8jMKT'
+ * );
+ * ```
+ */
+export declare function deriveContract(fleet: string | Address, program?: string | Address): Promise<Address<string>>;
+/**
+ * Derives the rental thread PDA using the Antegen program ID
+ *
+ * Thread accounts are managed by the Antegen program, so they must be derived
+ * using the Antegen program ID rather than the SRSLY program ID. The SDK
+ * automatically resolves the correct Antegen program address for the current network
+ * unless a specific program ID is provided.
+ *
+ * @param authority - The rental authority PDA (derived with SRSLY program)
+ * @param rental - The rental state PDA (derived with SRSLY program)
+ * @param program - Optional Antegen program ID (defaults to network-resolved address)
+ * @returns The rental thread PDA derived using Antegen program ID
+ *
+ * @example
+ * ```typescript
+ * // Use network-resolved program address (recommended)
+ * const threadPda = await deriveRentalThread(rentalAuthorityPda, rentalStatePda);
+ *
+ * // Use specific program address
+ * const threadPda = await deriveRentalThread(
+ *   rentalAuthorityPda,
+ *   rentalStatePda,
+ *   'AgThdyi1P5RkVeZD2rQahTvs8HePJoGFFxKtvok5s2J1'
+ * );
+ * ```
+ */
+export declare function deriveRentalThread(rental: string | Address, authority?: string | Address, program?: string | Address): Promise<Address<string>>;
+/**
+ * Derives the rental state PDA using the SRSLY program ID
+ *
+ * The SDK automatically resolves the correct SRSLY program address for the current network
+ * unless a specific program ID is provided.
+ *
+ * @param contract - The rental contract address
+ * @param borrower - The borrower's public key
+ * @param program - Optional SRSLY program ID (defaults to network-resolved address)
+ * @returns The rental state PDA
+ *
+ * @example
+ * ```typescript
+ * // Use network-resolved program address (recommended)
+ * const rentalStateAddress = await deriveRentalState(contractAddress, borrowerAddress);
+ *
+ * // Use specific program address
+ * const rentalStateAddress = await deriveRentalState(
+ *   contractAddress,
+ *   borrowerAddress,
+ *   'SRSLY1fq9TJqCk1gNSE7VZL2bztvTn9wm4VR8u8jMKT'
+ * );
+ * ```
+ */
+export declare function deriveRental(contract: string | Address, borrower: string | Address, program?: string | Address): Promise<Address<string>>;
+/**
+ * Derives the rental authority PDA using the SRSLY program ID
+ *
+ * The SDK automatically resolves the correct SRSLY program address for the current network
+ * unless a specific program ID is provided.
+ *
+ * @param program - Optional SRSLY program ID (defaults to network-resolved address)
+ * @returns The rental authority PDA
+ *
+ * @example
+ * ```typescript
+ * // Use network-resolved program address (recommended)
+ * const rentalAuthorityAddress = await deriveRentalAuthority();
+ *
+ * // Use specific program address
+ * const rentalAuthorityAddress = await deriveRentalAuthority(
+ *   'SRSLY1fq9TJqCk1gNSE7VZL2bztvTn9wm4VR8u8jMKT'
+ * );
+ * ```
+ */
+export declare function deriveRentalAuthority(program?: string | Address): Promise<Address<string>>;
+/**
+ * Derives the config PDA using the SRSLY program ID
+ *
+ * The SDK automatically resolves the correct SRSLY program address for the current network
+ * unless a specific program ID is provided.
+ *
+ * @param program - Optional SRSLY program ID (defaults to network-resolved address)
+ * @returns The config PDA
+ *
+ * @example
+ * ```typescript
+ * // Use network-resolved program address (recommended)
+ * const configAddress = await deriveConfig();
+ *
+ * // Use specific program address
+ * const configAddress = await deriveConfig(
+ *   'SRSLY1fq9TJqCk1gNSE7VZL2bztvTn9wm4VR8u8jMKT'
+ * );
+ * ```
+ */
+export declare function deriveConfig(program?: string | Address): Promise<Address<string>>;
+/**
+ * Helper function to derive the borrower's profile faction account
+ *
+ * @param profile The borrower's profile address
+ * @returns Promise that resolves to the derived profile faction address
+ */
+export declare function deriveProfileFaction(profile: string | Address): Promise<Address<string>>;
+/**
+ * Helper function to derive the sage player profile
+ *
+ * @param borrowerProfile The borrower's profile address
+ * @param gameId The game ID from the fleet or contract state
+ * @returns Promise that resolves to the derived sage player profile address
+ */
+export declare function deriveSagePlayerProfile(borrowerProfile: string | Address, gameId: string | Address): Promise<Address<string>>;
+/**
+ * Helper function to derive the starbase address based on faction
+ *
+ * @param faction The faction (1/2/3 or 'mud'/'oni'/'ustur')
+ * @param gameId The game ID from the fleet or contract state
+ * @returns Promise that resolves to the derived starbase address
+ */
+export declare function deriveStarbase(faction: number | string, gameId: string | Address): Promise<Address<string>>;
+/**
+ * Helper function to derive the starbase player address
+ *
+ * @param sagePlayerProfile The sage player profile address
+ * @param starbase The starbase address
+ * @param starbaseSeqId The starbase sequence ID (defaults to 0)
+ * @returns Promise that resolves to the derived starbase player address
+ */
+export declare function deriveStarbasePlayer(sagePlayerProfile: string | Address, starbase: string | Address, starbaseSeqId?: number): Promise<Address<string>>;
+/**
+ * Derives all three accounts needed: profileFaction, starbase, and starbasePlayer
+ *
+ * @param profile The borrower's profile address
+ * @param faction The faction (1/2/3 or 'mud'/'oni'/'ustur')
+ * @param starbaseSeqId The starbase sequence ID (defaults to 0)
+ * @param gameId The game ID from the fleet or contract state
+ * @returns Promise that resolves to the three derived addresses
+ */
+export declare function deriveGameAccounts(profile: string | Address, faction: number | string, starbaseSeqId: number | undefined, gameId: string | Address): Promise<{
+    profileFaction: Address<string>;
+    starbase: Address<string>;
+    starbasePlayer: Address<string>;
+}>;
+/**
+ * Derives the fee token account PDA using the Associated Token Program
+ *
+ * This account holds the collected service fees in ATLAS tokens. It's an associated
+ * token account derived from the config's fees_account and the ATLAS mint address.
+ * Both values are retrieved from the ConfigState account.
+ *
+ * @param configState - Optional ConfigState account data. If not provided, will fetch it automatically
+ * @returns The fee token account PDA
+ *
+ * @example
+ * ```typescript
+ * // Auto-fetch config state (recommended for one-off use)
+ * const feeTokenAccount = await deriveFeeTokenAccount();
+ *
+ * // Use already-fetched config state (recommended when you already have it)
+ * const configState = await fetchConfigState();
+ * const feeTokenAccount = await deriveFeeTokenAccount(configState);
+ * ```
+ */
+export declare function deriveFeeTokenAccount(configState?: ConfigState): Promise<Address<string>>;
+//# sourceMappingURL=derive-pda.d.ts.map

package/dist/types/utils/derive-pda.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive-pda.d.ts","sourceRoot":"","sources":["../../../src/utils/derive-pda.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAIL,KAAK,OAAO,EACb,MAAM,aAAa,CAAC;AAcrB,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAchE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,MAAM,GAAG,OAAO,EACvB,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,GACzB,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAmB1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,GAAG,OAAO,EACxB,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,EAC5B,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,GACzB,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAsB1B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,GAAG,OAAO,EAC1B,QAAQ,EAAE,MAAM,GAAG,OAAO,EAC1B,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,GACzB,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAoB1B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAmBhG;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,YAAY,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAevF;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,MAAM,GAAG,OAAO,GACxB,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAS1B;AAED;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,eAAe,EAAE,MAAM,GAAG,OAAO,EACjC,MAAM,EAAE,MAAM,GAAG,OAAO,GACvB,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAa1B;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,MAAM,EAAE,MAAM,GAAG,OAAO,GACvB,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAoC1B;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,iBAAiB,EAAE,MAAM,GAAG,OAAO,EACnC,QAAQ,EAAE,MAAM,GAAG,OAAO,EAC1B,aAAa,GAAE,MAAU,GACxB,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAoB1B;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,MAAM,GAAG,OAAO,EACzB,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,aAAa,EAAE,MAAM,YAAI,EACzB,MAAM,EAAE,MAAM,GAAG,OAAO,GACvB,OAAO,CAAC;IACT,cAAc,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAChC,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1B,cAAc,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;CACjC,CAAC,CAqBD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,qBAAqB,CACzC,WAAW,CAAC,EAAE,WAAW,GACxB,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAyB1B"}

package/dist/types/utils/fetch-accounts.d.ts

@@ -0,0 +1,158 @@
+/**
+ * @purpose Blockchain account fetching utilities with RPC connection management
+ * @reviewed 2025-07-29
+ */
+import { type ConfigState, type ContractState, type RentalState } from '../generated/codama/accounts';
+import { type Address } from '@solana/kit';
+/**
+ * Fetches contract state data from the blockchain
+ *
+ * @param contract - The contract account address to fetch (string or Address)
+ * @param rpcUrl - Optional RPC endpoint URL. If not provided, uses RPC from global config
+ * @returns The contract state data directly (no .data wrapper)
+ * @throws Error with descriptive message if contract not found or fetch fails
+ *
+ * @example
+ * ```typescript
+ * // Uses RPC URL from global config
+ * const contractState = await fetchContractState('ContractAddress123...');
+ * console.log('Contract owner:', contractState.owner);
+ *
+ * // Uses specific RPC URL
+ * const contractState2 = await fetchContractState(
+ *   'ContractAddress123...',
+ *   'https://api.devnet.solana.com'
+ * );
+ * console.log('Contract rate:', contractState2.rate);
+ * ```
+ */
+export declare function fetchContractState<TAddress extends string = string>(contract: string | Address<TAddress>, rpcUrl?: string): Promise<ContractState>;
+/**
+ * Fetches rental state data from the blockchain
+ *
+ * @param rental - The rental account address to fetch (string or Address)
+ * @param rpcUrl - Optional RPC endpoint URL. If not provided, uses RPC from global config
+ * @returns The rental state data directly (no .data wrapper)
+ * @throws Error with descriptive message if rental state not found or fetch fails
+ *
+ * @example
+ * ```typescript
+ * // Uses RPC URL from global config
+ * const rentalState = await fetchRentalState('RentalAddress123...');
+ * console.log('Rental borrower:', rentalState.borrower);
+ *
+ * // Uses specific RPC URL
+ * const rentalState2 = await fetchRentalState(
+ *   'RentalAddress123...',
+ *   'https://api.devnet.solana.com'
+ * );
+ * console.log('Rental start:', rentalState2.start);
+ * ```
+ */
+export declare function fetchRentalState<TAddress extends string = string>(rental: string | Address<TAddress>, rpcUrl?: string): Promise<RentalState>;
+/**
+ * Fetches config state data from the blockchain
+ *
+ * @param config - Optional config account address. If not provided, derives config PDA automatically
+ * @param rpcUrl - Optional RPC endpoint URL. If not provided, uses RPC from global config
+ * @returns The config state data directly (no .data wrapper)
+ * @throws Error with descriptive message if config not found or fetch fails
+ *
+ * @example
+ * ```typescript
+ * // Auto-derive config PDA using global config
+ * const configState = await fetchConfigState();
+ * console.log('Config authority:', configState.authority);
+ *
+ * // Use specific config address
+ * const configState2 = await fetchConfigState('ConfigAddress123...');
+ * console.log('Config fees:', configState2.fees);
+ *
+ * // Use specific config address and RPC URL
+ * const configState3 = await fetchConfigState(
+ *   'ConfigAddress123...',
+ *   'https://api.devnet.solana.com'
+ * );
+ * console.log('Config authority:', configState3.authority);
+ * ```
+ */
+export declare function fetchConfigState<TAddress extends string = string>(config?: string | Address<TAddress>, rpcUrl?: string): Promise<ConfigState>;
+/**
+ * Fetches multiple contract states in a single RPC call
+ *
+ * @param contracts - Array of contract addresses to fetch
+ * @param rpcUrl - Optional RPC endpoint URL. If not provided, uses RPC from global config
+ * @returns Array of contract states (some may be null if not found)
+ *
+ * @example
+ * ```typescript
+ * const contracts = await fetchMultipleContractStates(
+ *   ['Contract1...', 'Contract2...', 'Contract3...']
+ * );
+ *
+ * contracts.forEach((contract, i) => {
+ *   if (contract.exists) {
+ *     console.log(`Contract ${i}: ${contract.data.owner}`);
+ *   }
+ * });
+ * ```
+ */
+export declare function fetchMultipleContractStates<TAddress extends string = string>(contracts: (string | Address<TAddress>)[], rpcUrl?: string): Promise<import("@solana/kit").Account<ContractState>[]>;
+/**
+ * Fetches multiple rental states in a single RPC call
+ *
+ * @param rentals - Array of rental addresses to fetch
+ * @param rpcUrl - Optional RPC endpoint URL. If not provided, uses RPC from global config
+ * @returns Array of rental states (some may be null if not found)
+ *
+ * @example
+ * ```typescript
+ * const rentals = await fetchMultipleRentalStates(
+ *   ['Rental1...', 'Rental2...', 'Rental3...']
+ * );
+ *
+ * rentals.forEach((rental, i) => {
+ *   if (rental.exists) {
+ *     console.log(`Rental ${i}: ${rental.data.borrower}`);
+ *   }
+ * });
+ * ```
+ */
+export declare function fetchMultipleRentalStates<TAddress extends string = string>(rentals: (string | Address<TAddress>)[], rpcUrl?: string): Promise<import("@solana/kit").Account<RentalState>[]>;
+/**
+ * Interface representing a SAGE Fleet account structure
+ */
+export interface FleetState {
+    version: number;
+    gameId: string;
+    ownerProfile: string;
+    fleetShips: string;
+    subProfile: string;
+    subProfileInvalidator: string;
+    faction: number;
+    [key: string]: any;
+}
+/**
+ * Fetches fleet state data from the SAGE program
+ *
+ * @param fleetAddress - The fleet account address to fetch (string or Address)
+ * @param rpcUrl - Optional RPC endpoint URL. If not provided, uses RPC from global config
+ * @returns The fleet state data directly (no .data wrapper)
+ * @throws Error with descriptive message if fleet not found or fetch fails
+ *
+ * @example
+ * ```typescript
+ * // Uses RPC URL from global config
+ * const fleetState = await fetchFleetState('FleetAddress123...');
+ * console.log('Fleet owner profile:', fleetState.ownerProfile);
+ *
+ * // Uses specific RPC URL
+ * const fleetState2 = await fetchFleetState(
+ *   'FleetAddress123...',
+ *   'https://api.devnet.solana.com'
+ * );
+ * console.log('Fleet faction:', fleetState2.faction);
+ * ```
+ */
+export declare function fetchFleetState<TAddress extends string = string>(fleetAddress: string | Address<TAddress>, rpcUrl?: string): Promise<FleetState>;
+//# sourceMappingURL=fetch-accounts.d.ts.map

package/dist/types/utils/fetch-accounts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-accounts.d.ts","sourceRoot":"","sources":["../../../src/utils/fetch-accounts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAML,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,WAAW,EACjB,MAAM,8BAA8B,CAAC;AAItC,OAAO,EAAqD,KAAK,OAAO,EAAE,MAAM,aAAa,CAAC;AA0D9F;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,SAAS,MAAM,GAAG,MAAM,EACvE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,EACpC,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,aAAa,CAAC,CAExB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,SAAS,MAAM,GAAG,MAAM,EACrE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,EAClC,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,WAAW,CAAC,CAEtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,SAAS,MAAM,GAAG,MAAM,EACrE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,EACnC,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,WAAW,CAAC,CAStB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,2BAA2B,CAAC,QAAQ,SAAS,MAAM,GAAG,MAAM,EAChF,SAAS,EAAE,CAAC,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,EAAE,EACzC,MAAM,CAAC,EAAE,MAAM,2DAGhB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,yBAAyB,CAAC,QAAQ,SAAS,MAAM,GAAG,MAAM,EAC9E,OAAO,EAAE,CAAC,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,EAAE,EACvC,MAAM,CAAC,EAAE,MAAM,yDAGhB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAeD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,eAAe,CAAC,QAAQ,SAAS,MAAM,GAAG,MAAM,EACpE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,EACxC,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,UAAU,CAAC,CAiBrB"}

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

@@ -1,4 +1,17 @@
-export * from "./constants";
-export * from "./profiles";
-export * from "./config";
+/**
+ * @purpose Re-exports all utility functions and types for SDK usage
+ * @reviewed 2025-07-29
+ */
+export * from './constants';
+export * from './config';
+export * from './payment-frequency';
+export * from './cron';
+export * from './schedule-validation';
+export * from './schedule-builder';
+export * from './instruction-converter';
+export * from './fetch-accounts';
+export * from './derive-pda';
+export * from './signer';
+export * from './smart-params';
+export * from './param-converters';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,qBAAqB,CAAC;AACpC,cAAc,QAAQ,CAAC;AACvB,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC"}

package/dist/types/utils/instruction-converter.d.ts

@@ -0,0 +1,171 @@
+/**
+ * @purpose Fluent instruction interface for format conversion between @solana/kit and @solana/web3.js
+ * @reviewed 2025-07-29
+ */
+/**
+ * Fluent instruction interface for format conversion between @solana/kit and @solana/web3.js
+ */
+import { SdkConfigSelector, SdkConfigOptions, PublicKeyConstructor } from './config';
+/**
+ * @solana/kit 2.x compatible instruction format
+ * This matches the structure expected by appendTransactionMessageInstruction
+ */
+export interface KitInstruction {
+    programAddress: string;
+    accounts?: Array<{
+        address: string;
+        role: number;
+    }>;
+    data?: Uint8Array;
+}
+/**
+ * @solana/web3.js instruction format with string addresses
+ */
+export interface Web3jsInstructionWithStrings {
+    keys: Array<{
+        pubkey: string;
+        isWritable: boolean;
+        isSigner: boolean;
+    }>;
+    programId: string;
+    data: Uint8Array | {
+        [key: string]: number;
+    };
+}
+/**
+ * @solana/web3.js instruction format with PublicKey instances
+ */
+export interface Web3jsInstructionWithPublicKeys<TPublicKey = any> {
+    keys: Array<{
+        pubkey: TPublicKey;
+        isWritable: boolean;
+        isSigner: boolean;
+    }>;
+    programId: TPublicKey;
+    data: Uint8Array | {
+        [key: string]: number;
+    };
+}
+/**
+ * Generic web3.js instruction format
+ */
+export type Web3jsInstruction<TPublicKey = string> = TPublicKey extends string ? Web3jsInstructionWithStrings : Web3jsInstructionWithPublicKeys<TPublicKey>;
+/**
+ * Fluent instruction wrapper that provides format conversion methods
+ * @example
+ * ```typescript
+ * import { PublicKey } from '@solana/web3.js';
+ *
+ * // Get FluentInstruction
+ * const fluentInstruction = await createContract(params);
+ *
+ * // Access pure instruction data for @solana/kit
+ * const kitInstruction = fluentInstruction.instruction;
+ * // or
+ * const kitInstruction = fluentInstruction.kit();
+ *
+ * // Convert to web3.js format with string addresses
+ * const web3jsInstruction = fluentInstruction.web3js();
+ *
+ * // Convert to web3.js format with PublicKey instances
+ * const web3jsInstructionWithPK = fluentInstruction.web3js(PublicKey);
+ *
+ * // Use with libraries
+ * const transaction = new Transaction().add(web3jsInstructionWithPK);
+ * ```
+ */
+export interface FluentInstruction {
+    /**
+     * Pure instruction data (can be passed directly to @solana/kit)
+     * This property contains the clean KitInstruction without any method pollution
+     */
+    instruction: KitInstruction;
+    /**
+     * Get pure KitInstruction format (alias for .instruction property)
+     * @returns Instruction in @solana/kit format
+     */
+    kit(): KitInstruction;
+    /**
+     * Convert instruction to @solana/web3.js format with string addresses
+     * @returns Instruction in @solana/web3.js format with string pubkeys
+     */
+    web3js(): Web3jsInstructionWithStrings;
+    /**
+     * Convert instruction to @solana/web3.js format with PublicKey instances
+     * @param PublicKey Constructor for creating PublicKey instances (cleaner API than PublicKeyConstructor)
+     * @returns Instruction in @solana/web3.js format with PublicKey instances
+     */
+    web3js<TPublicKey>(PublicKey: PublicKeyConstructor<TPublicKey>): Web3jsInstructionWithPublicKeys<TPublicKey>;
+}
+/**
+ * Fluent config selector that adds format conversion methods
+ * This allows chaining both configuration and format conversion
+ * @deprecated Use SmartFluentConfigSelector instead
+ */
+export interface FluentConfigSelector<T extends FluentInstruction> extends SdkConfigSelector<T> {
+    /**
+     * Convert instruction to @solana/web3.js format with string addresses
+     * @returns Promise that resolves to Web3jsInstructionWithStrings
+     */
+    web3js(): Promise<Web3jsInstructionWithStrings>;
+    /**
+     * Convert instruction to @solana/web3.js format with PublicKey instances
+     * @param PublicKey Constructor for creating PublicKey instances (cleaner API than PublicKeyConstructor)
+     * @returns Promise that resolves to Web3jsInstructionWithPublicKeys
+     */
+    web3js<TPublicKey>(PublicKey: PublicKeyConstructor<TPublicKey>): Promise<Web3jsInstructionWithPublicKeys<TPublicKey>>;
+}
+/**
+ * Smart fluent config selector that returns different types based on library configuration
+ *
+ * Return behavior based on config:
+ * - No library config: Returns FluentInstruction (must use .kit() or .web3js())
+ * - library='kit': Returns KitInstruction directly
+ * - library='web3js': Returns web3js instruction format directly
+ */
+export interface SmartFluentConfigSelector<T extends FluentInstruction> extends SdkConfigSelector<any> {
+    /**
+     * Set configuration options for this call
+     */
+    set(options: SdkConfigOptions): SmartFluentConfigSelector<T>;
+    /**
+     * Build with current configuration (explicit call)
+     */
+    build(): Promise<T>;
+    /**
+     * Get pure KitInstruction format
+     * @returns Promise that resolves to KitInstruction
+     */
+    kit(): Promise<KitInstruction>;
+    /**
+     * Convert instruction to @solana/web3.js format with string addresses
+     * @returns Promise that resolves to Web3jsInstructionWithStrings
+     */
+    web3js(): Promise<Web3jsInstructionWithStrings>;
+    /**
+     * Convert instruction to @solana/web3.js format with PublicKey instances
+     * @param PublicKey Constructor for creating PublicKey instances (cleaner API than PublicKeyConstructor)
+     * @returns Promise that resolves to Web3jsInstructionWithPublicKeys
+     */
+    web3js<TPublicKey>(PublicKey: PublicKeyConstructor<TPublicKey>): Promise<Web3jsInstructionWithPublicKeys<TPublicKey>>;
+}
+/**
+ * Create a fluent instruction from a kit instruction using non-polluting design
+ * @param kitInstruction The base instruction in kit format
+ * @returns Fluent instruction with separate instruction property and conversion methods
+ */
+export declare function createFluentInstruction(kitInstruction: KitInstruction): FluentInstruction;
+/**
+ * Create a fluent config selector that adds format conversion methods
+ * @deprecated Use createSmartFluentConfigSelector instead
+ * @param baseSelector The base SdkConfigSelector
+ * @returns FluentConfigSelector with additional format conversion methods
+ */
+export declare function createFluentConfigSelector<T extends FluentInstruction>(baseSelector: SdkConfigSelector<T>): FluentConfigSelector<T>;
+/**
+ * Create a smart fluent config selector with library-aware return types
+ * @param baseSelector The base SdkConfigSelector
+ * @returns SmartFluentConfigSelector with smart return behavior
+ */
+export declare function createSmartFluentConfigSelector<T extends FluentInstruction>(baseSelector: SdkConfigSelector<T>): SmartFluentConfigSelector<T>;
+//# sourceMappingURL=instruction-converter.d.ts.map

package/dist/types/utils/instruction-converter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instruction-converter.d.ts","sourceRoot":"","sources":["../../../src/utils/instruction-converter.ts"],"names":[],"mappings":"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"}

package/dist/types/utils/param-converters.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @purpose Convert smart parameters to blockchain values (stardust, seconds, periods)
+ * @reviewed 2025-08-05
+ */
+import type { ConfigState } from '../generated/codama/accounts';
+import type { AmountParam, DurationParam, PercentageParam } from './smart-params';
+/**
+ * Convert duration parameter to seconds.
+ *
+ * @param duration - Duration in various formats
+ * @returns Total seconds
+ *
+ * @example
+ * convertDurationToSeconds({ days: 7 }); // 604800
+ * convertDurationToSeconds({ hours: 24, minutes: 30 }); // 88200
+ * convertDurationToSeconds(3600); // 3600 (passthrough)
+ */
+export declare function convertDurationToSeconds(duration: DurationParam): Promise<number>;
+export declare function convertDurationToPeriods(duration: DurationParam, frequency: string): Promise<number>;
+/**
+ * Convert amount parameter to stardust units.
+ * IMPORTANT: Numbers are interpreted as ATLAS by default (v3 breaking change).
+ *
+ * @param amount - Amount in ATLAS or stardust
+ * @param config - Optional config state (will fetch if not provided)
+ * @returns Amount in stardust units
+ *
+ * @example
+ * convertAmountToStardust(1); // 100_000_000 stardust (1 ATLAS)
+ * convertAmountToStardust({ atlas: 1.5 }); // 150_000_000 stardust
+ * convertAmountToStardust({ stardust: 123456789 }); // 123456789 stardust
+ */
+export declare function convertAmountToStardust(amount: AmountParam, config?: ConfigState): Promise<bigint>;
+/**
+ * Convert percentage parameter to basis points (100 = 1%).
+ *
+ * @param percentage - Percentage in various formats
+ * @returns Basis points
+ *
+ * @example
+ * convertPercentageToBasisPoints({ percent: 10 }); // 1000
+ * convertPercentageToBasisPoints({ basisPoints: 1050 }); // 1050
+ * convertPercentageToBasisPoints(500); // 500 (5%)
+ */
+export declare function convertPercentageToBasisPoints(percentage: PercentageParam): number;
+/**
+ * Format amount from stardust to ATLAS for display.
+ *
+ * @param stardust - Amount in stardust units
+ * @param config - Optional config state
+ * @returns Formatted ATLAS amount
+ *
+ * @example
+ * formatStardustToAtlas(100_000_000n); // "1"
+ * formatStardustToAtlas(150_000_000n); // "1.5"
+ * formatStardustToAtlas(123_456_789n); // "1.23456789"
+ */
+export declare function formatStardustToAtlas(stardust: bigint, config?: ConfigState): Promise<string>;
+/**
+ * Validate duration against config limits.
+ *
+ * @param durationSeconds - Duration in seconds
+ * @param config - Optional config state
+ * @throws Error if duration is outside allowed range
+ */
+export declare function validateDurationLimits(durationSeconds: number, config?: ConfigState): Promise<void>;
+//# sourceMappingURL=param-converters.d.ts.map

package/dist/types/utils/param-converters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"param-converters.d.ts","sourceRoot":"","sources":["../../../src/utils/param-converters.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAKlF;;;;;;;;;;GAUG;AACH,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,aAAa,GACtB,OAAO,CAAC,MAAM,CAAC,CAcjB;AAqCD,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,aAAa,EACvB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC,CAwBjB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,WAAW,EACnB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,MAAM,CAAC,CAkBjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,8BAA8B,CAC5C,UAAU,EAAE,eAAe,GAC1B,MAAM,CAeR;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,eAAe,EAAE,MAAM,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAgBf"}