High-Level Utilities

/**
 * Airdrop function signature
 */
type AirdropFunction = (config: {
  /** Address to receive airdrop */
  recipientAddress: Address;
  /** Amount in lamports */
  lamports: Lamports;
  /** Commitment level for confirmation */
  commitment?: Commitment;
  /** Custom confirmation timeout */
  confirmationTimeout?: number;
}) => Promise<Signature>;

/**
 * Configuration for airdrop factory
 */
interface AirdropFactoryConfig<TCluster> {
  /** RPC client with airdrop and signature status APIs */
  rpc: Rpc<RequestAirdropApi & GetSignatureStatusesApi> & { '~cluster'?: TCluster };
  /** Subscriptions client for signature notifications */
  rpcSubscriptions: RpcSubscriptions<SignatureNotificationsApi> & { '~cluster'?: TCluster };
}

/**
 * Create airdrop function for devnet
 * @param config - Factory configuration
 * @returns Configured airdrop function
 */
function airdropFactory(config: AirdropFactoryConfig<'devnet'>): AirdropFunction;

/**
 * Create airdrop function for testnet
 * @param config - Factory configuration
 * @returns Configured airdrop function
 */
function airdropFactory(config: AirdropFactoryConfig<'testnet'>): AirdropFunction;

/**
 * Create airdrop function for any cluster
 * @param config - Factory configuration
 * @returns Configured airdrop function
 */
function airdropFactory<TCluster extends 'devnet' | 'mainnet' | 'testnet' | void = void>(
  config: AirdropFactoryConfig<TCluster>
): AirdropFunction;

import { 
  airdropFactory,
  createSolanaRpc,
  createSolanaRpcSubscriptions,
  address,
  lamports
} from "@solana/web3.js";

// Create clients
const rpc = createSolanaRpc("https://api.devnet.solana.com");
const rpcSubscriptions = createSolanaRpcSubscriptions("wss://api.devnet.solana.com");

// Create airdrop function
const airdrop = airdropFactory({ rpc, rpcSubscriptions });

// Request airdrop
const signature = await airdrop({
  recipientAddress: address("your-address-here"),
  lamports: lamports(2_000_000_000n), // 2 SOL
  commitment: "confirmed",
  confirmationTimeout: 60000 // 60 seconds
});

console.log("Airdrop confirmed:", signature);

/**
 * Send and confirm transaction function signature
 */
type SendAndConfirmTransactionFunction = (
  transaction: FullySignedTransaction & TransactionWithBlockhashLifetime,
  config?: {
    /** Commitment level for confirmation */
    commitment?: Commitment;
    /** Skip preflight checks */
    skipPreflight?: boolean;
    /** Maximum confirmation timeout */
    confirmationTimeout?: number;
    /** Maximum retries for sending */
    maxRetries?: number;
  }
) => Promise<void>;

/**
 * Factory configuration for transaction sending
 */
interface SendAndConfirmTransactionFactoryConfig<TCluster> {
  /** RPC client with transaction APIs */
  rpc: Rpc<GetEpochInfoApi & GetSignatureStatusesApi & SendTransactionApi> & { '~cluster'?: TCluster };
  /** Subscriptions client for notifications */
  rpcSubscriptions: RpcSubscriptions<SignatureNotificationsApi & SlotNotificationsApi> & { '~cluster'?: TCluster };
}

/**
 * Create transaction sending function
 * @param config - Factory configuration
 * @returns Configured send and confirm function
 */
function sendAndConfirmTransactionFactory<TCluster extends 'devnet' | 'mainnet' | 'testnet' | void = void>(
  config: SendAndConfirmTransactionFactoryConfig<TCluster>
): SendAndConfirmTransactionFunction;

import {
  sendAndConfirmTransactionFactory,
  createTransactionMessage,
  compileTransaction,
  signTransaction
} from "@solana/web3.js";

// Create send function
const sendAndConfirmTransaction = sendAndConfirmTransactionFactory({
  rpc,
  rpcSubscriptions
});

// Create and sign transaction
const message = createTransactionMessage({
  version: 0,
  feePayer: signer.address,
  blockhash,
  instructions: [/* your instructions */]
});

let transaction = compileTransaction(message);
transaction = await signTransaction(transaction, [signer]);

// Send and confirm
await sendAndConfirmTransaction(transaction, {
  commitment: "confirmed",
  confirmationTimeout: 30000,
  maxRetries: 3
});

console.log("Transaction confirmed!");

/**
 * Send transaction without confirming function signature
 */
type SendTransactionWithoutConfirmingFunction = (
  transaction: FullySignedTransaction,
  config?: {
    /** Skip preflight checks */
    skipPreflight?: boolean;
    /** Maximum retries */
    maxRetries?: number;
    /** Custom retry delay */
    retryDelay?: number;
  }
) => Promise<void>;

/**
 * Factory configuration for fire-and-forget sending
 */
interface SendTransactionWithoutConfirmingFactoryConfig {
  /** RPC client with send transaction API */
  rpc: Rpc<SendTransactionApi>;
}

/**
 * Create fire-and-forget send function
 * @param config - Factory configuration
 * @returns Configured send function
 */
function sendTransactionWithoutConfirmingFactory(
  config: SendTransactionWithoutConfirmingFactoryConfig
): SendTransactionWithoutConfirmingFunction;

/**
 * Durable nonce transaction sending function signature
 */
type SendAndConfirmDurableNonceTransactionFunction = (
  transaction: FullySignedTransaction & TransactionWithDurableNonceLifetime,
  config?: {
    /** Commitment level */
    commitment?: Commitment;
    /** Confirmation timeout */
    confirmationTimeout?: number;
    /** Maximum retries */
    maxRetries?: number;
  }
) => Promise<void>;

/**
 * Factory configuration for durable nonce transactions
 */
interface SendAndConfirmDurableNonceTransactionFactoryConfig<TCluster> {
  /** RPC client with required APIs */
  rpc: Rpc<GetAccountInfoApi & GetSignatureStatusesApi & SendTransactionApi> & { '~cluster'?: TCluster };
  /** Subscriptions client */
  rpcSubscriptions: RpcSubscriptions<AccountNotificationsApi & SignatureNotificationsApi> & { '~cluster'?: TCluster };
}

/**
 * Create durable nonce transaction sender
 * @param config - Factory configuration
 * @returns Configured sender function
 */
function sendAndConfirmDurableNonceTransactionFactory<TCluster extends 'devnet' | 'mainnet' | 'testnet' | void = void>(
  config: SendAndConfirmDurableNonceTransactionFactoryConfig<TCluster>
): SendAndConfirmDurableNonceTransactionFunction;

/**
 * Compute unit estimation function signature
 */
type ComputeUnitEstimateFunction = (
  transactionMessage: CompilableTransactionMessage | (ITransactionMessageWithFeePayer & TransactionMessage),
  config?: {
    /** Commitment level for simulation */
    commitment?: Commitment;
    /** Accounts to include in simulation */
    accounts?: {
      encoding?: "base64" | "jsonParsed";
      addresses?: Address[];
    };
    /** Replace recent blockhash */
    replaceRecentBlockhash?: boolean;
  }
) => Promise<number>;

/**
 * Factory configuration for compute estimation
 */
interface ComputeUnitEstimateFactoryConfig {
  /** RPC client with simulate transaction API */
  rpc: Rpc<SimulateTransactionApi>;
}

/**
 * Create compute unit estimation function
 * @param config - Factory configuration
 * @returns Configured estimation function
 */
function getComputeUnitEstimateForTransactionMessageFactory(
  config: ComputeUnitEstimateFactoryConfig
): ComputeUnitEstimateFunction;

import {
  getComputeUnitEstimateForTransactionMessageFactory,
  createTransactionMessage
} from "@solana/web3.js";

// Create estimation function
const getComputeUnitEstimate = getComputeUnitEstimateForTransactionMessageFactory({ rpc });

// Create transaction message
const message = createTransactionMessage({
  version: 0,
  feePayer: myAddress,
  blockhash,
  instructions: [/* complex instructions */]
});

// Estimate compute units
const estimatedUnits = await getComputeUnitEstimate(message, {
  commitment: "processed",
  replaceRecentBlockhash: true
});

console.log("Estimated compute units:", estimatedUnits);

// Add compute budget instruction if needed
if (estimatedUnits > 200000) {
  const computeBudgetInstruction = createComputeBudgetInstruction({
    units: estimatedUnits + 10000 // Add buffer
  });
  
  message.instructions.unshift(computeBudgetInstruction);
}

/**
 * Decompile transaction message with automatic lookup table fetching
 * @param compiledMessage - Compiled transaction message
 * @param rpc - RPC client for fetching lookup tables
 * @param config - Optional configuration
 * @returns Promise resolving to decompiled message
 */
function decompileTransactionMessageFetchingLookupTables(
  compiledMessage: CompiledTransactionMessage,
  rpc: Rpc<GetMultipleAccountsApi>,
  config?: {
    /** Commitment level for account fetching */
    commitment?: Commitment;
    /** Last valid block height */
    lastValidBlockHeight?: bigint;
    /** Account fetch configuration */
    accountsConfig?: FetchAccountsConfig;
  }
): Promise<CompilableTransactionMessage>;

import { decompileTransactionMessageFetchingLookupTables } from "@solana/web3.js";

// Received compiled message from network
const compiledMessage = /* compiled transaction with lookup tables */;

// Decompile with automatic lookup table resolution
const decompiled = await decompileTransactionMessageFetchingLookupTables(
  compiledMessage,
  rpc,
  {
    commitment: "confirmed",
    lastValidBlockHeight: 200000000n
  }
);

console.log("Decompiled instructions:", decompiled.instructions.length);
console.log("Fee payer:", decompiled.feePayer);

/**
 * Complete transaction workflow: build, send, and confirm
 * @param config - Workflow configuration
 * @returns Promise resolving to transaction signature
 */
function executeTransactionWorkflow(config: {
  /** RPC clients */
  rpc: Rpc<SendTransactionApi & GetSignatureStatusesApi>;
  rpcSubscriptions: RpcSubscriptions<SignatureNotificationsApi>;
  /** Transaction instructions */
  instructions: IInstruction[];
  /** Signers */
  signers: TransactionSigner[];
  /** Fee payer */
  feePayer: Address;
  /** Transaction options */
  options?: {
    commitment?: Commitment;
    skipPreflight?: boolean;
    confirmationTimeout?: number;
  };
}): Promise<Signature>;

/**
 * Batch transaction sending with retry logic
 * @param transactions - Transactions to send
 * @param config - Batch configuration
 * @returns Promise resolving to signature results
 */
function sendTransactionBatch(
  transactions: FullySignedTransaction[],
  config: {
    rpc: Rpc<SendTransactionApi>;
    batchSize?: number;
    retryConfig?: RetryConfig;
    delayBetweenBatches?: number;
  }
): Promise<Array<{ signature?: Signature; error?: Error }>>;

/**
 * Transaction with blockhash-based lifetime
 */
interface TransactionWithBlockhashLifetime {
  /** Recent blockhash */
  blockhash: Blockhash;
  /** Last valid block height */
  lastValidBlockHeight: bigint;
}

/**
 * Transaction with durable nonce lifetime  
 */
interface TransactionWithDurableNonceLifetime {
  /** Nonce account address */
  nonceAccount: Address;
  /** Nonce authority address */
  nonceAuthority: Address;
  /** Current nonce value */
  nonceValue: string;
}

/**
 * Fully signed transaction ready for sending
 */
interface FullySignedTransaction {
  /** Transaction signatures */
  signatures: Signature[];
  /** Compiled message bytes */
  messageBytes: Uint8Array;
}

/**
 * Transaction message with fee payer
 */
interface ITransactionMessageWithFeePayer {
  /** Fee payer address */
  feePayer: Address;
}

import {
  executeTransactionWorkflow,
  sendTransactionBatch,
  createTransferInstruction,
  generateKeyPair,
  createSignerFromKeyPair
} from "@solana/web3.js";

// Complete workflow example
const keyPair = await generateKeyPair();
const signer = await createSignerFromKeyPair(keyPair);

const signature = await executeTransactionWorkflow({
  rpc,
  rpcSubscriptions,
  instructions: [
    createTransferInstruction({
      fromPubkey: signer.address,
      toPubkey: recipientAddress,
      lamports: lamports(1_000_000n)
    })
  ],
  signers: [signer],
  feePayer: signer.address,
  options: {
    commitment: "confirmed",
    confirmationTimeout: 30000
  }
});

console.log("Workflow completed:", signature);

// Batch sending example
const transactions = [/* array of signed transactions */];

const results = await sendTransactionBatch(transactions, {
  rpc,
  batchSize: 5,
  delayBetweenBatches: 1000,
  retryConfig: {
    maxRetries: 3,
    baseDelay: 1000,
    backoffMultiplier: 2
  }
});

console.log("Batch results:", results);
results.forEach((result, index) => {
  if (result.error) {
    console.error(`Transaction ${index} failed:`, result.error);
  } else {
    console.log(`Transaction ${index} succeeded:`, result.signature);
  }
});