@nosana/kit 1.0.10 → 2.0.9

package/README.md

@@ -2,6 +2,8 @@
 
 TypeScript SDK for interacting with the Nosana Network on Solana. Provides comprehensive tools for managing jobs, markets, runs, and protocol operations on the Nosana decentralized compute network.
 
+> **v2.0.0** - Major release featuring functional architecture, universal wallet support, and enhanced transaction handling. See [CHANGELOG.md](./CHANGELOG.md) for migration guide.
+
 ## Installation
 
 ```bash
@@ -16,17 +18,17 @@ npm install @nosana/kit
 ## Quick Start
 
 ```typescript
-import { NosanaClient, NosanaNetwork } from '@nosana/kit';
+import { createNosanaClient, NosanaNetwork } from '@nosana/kit';
 
 // Initialize with mainnet defaults
-const client = new NosanaClient();
+const client = createNosanaClient();
 
 // Or specify network and configuration
-const client = new NosanaClient(NosanaNetwork.DEVNET, {
+const client = createNosanaClient(NosanaNetwork.DEVNET, {
   solana: {
     rpcEndpoint: 'https://your-custom-rpc.com',
-    commitment: 'confirmed'
-  }
+    commitment: 'confirmed',
+  },
 });
 
 // Fetch a job by address
@@ -34,25 +36,29 @@ const job = await client.jobs.get('job-address');
 console.log('Job state:', job.state);
 
 // Query jobs with filters
-const completedJobs = await client.jobs.all({ 
+const completedJobs = await client.jobs.all({
   market: 'market-address',
-  state: 2  // JobState.COMPLETED
+  state: 2, // JobState.COMPLETED
 });
 ```
 
 ## Architecture
 
-The SDK is organized into clear, purpose-driven modules:
+The SDK uses a functional architecture with factory functions for improved modularity and testability:
 
-- **`services/`** - Utility services (SolanaService for RPC/transactions, NosService for NOS token operations)
-- **`programs/`** - On-chain program interfaces (JobsProgram, StakeProgram)
-- **`ipfs/`** - IPFS integration
-- **`config/`** - Network configurations
-- **`utils/`** - Helper utilities
+- **`services/`** - Utility services and program interfaces
+  - **`SolanaService`** - Low-level Solana RPC operations, transactions, and PDA derivations
+  - **`TokenService`** - Token account operations (configured for NOS token)
+  - **`programs/`** - On-chain program interfaces
+    - **`JobsProgram`** - Jobs, runs, and markets management
+    - **`StakeProgram`** - Staking account operations
+    - **`MerkleDistributorProgram`** - Merkle distributor and claim operations
+- **`ipfs/`** - IPFS integration for pinning and retrieving data
+- **`config/`** - Network configurations and defaults
+- **`utils/`** - Helper utilities and type conversions
+- **`generated_clients/`** - Auto-generated Solana program clients (exported as namespaces)
 
-This structure makes it clear that:
-- **Services** = Helper services and utilities for common operations
-- **Programs** = Interfaces to on-chain Solana programs
+All components use factory functions with explicit dependency injection, making the codebase modular, testable, and maintainable.
 
 ## Configuration
 
@@ -66,21 +72,24 @@ The SDK supports two networks:
 ### Configuration Options
 
 ```typescript
-import { NosanaClient, NosanaNetwork, NosanaLogLevel } from '@nosana/kit';
+import { createNosanaClient, NosanaNetwork, LogLevel } from '@nosana/kit';
 
-const client = new NosanaClient(NosanaNetwork.MAINNET, {
+const client = createNosanaClient(NosanaNetwork.MAINNET, {
   solana: {
     cluster: 'mainnet-beta',
     rpcEndpoint: 'https://api.mainnet-beta.solana.com',
-    commitment: 'confirmed'
+    commitment: 'confirmed',
   },
   ipfs: {
     api: 'https://api.pinata.cloud',
     jwt: 'your-pinata-jwt-token',
-    gateway: 'https://gateway.pinata.cloud/ipfs/'
+    gateway: 'https://gateway.pinata.cloud/ipfs/',
   },
-  logLevel: NosanaLogLevel.DEBUG,
-  wallet: keypairArray  // Optional: Set wallet during initialization
+  api: {
+    apiKey: 'your-api-key', // Optional: API key for authentication
+  },
+  logLevel: LogLevel.DEBUG,
+  wallet: myWallet, // Optional: Set wallet during initialization (must be a Wallet type)
 });
 ```
 
@@ -88,49 +97,92 @@ const client = new NosanaClient(NosanaNetwork.MAINNET, {
 
 ### NosanaClient
 
-Main entry point for SDK interactions.
+Main entry point for SDK interactions. Created using the `createNosanaClient()` factory function.
 
 **Properties:**
+
 - `config: ClientConfig` - Active configuration
 - `jobs: JobsProgram` - Jobs program interface
 - `stake: StakeProgram` - Staking program interface
+- `merkleDistributor: MerkleDistributorProgram` - Merkle distributor program interface
 - `solana: SolanaService` - General Solana utilities (RPC, transactions, PDAs)
-- `nos: NosService` - NOS token operations service
-- `ipfs: IPFS` - IPFS operations and utilities
+- `nos: TokenService` - Token operations service (configured for NOS token)
+- `api: NosanaApi | undefined` - Nosana API client for interacting with Nosana APIs (jobs, credits, markets)
+- `ipfs: ReturnType<typeof createIpfsClient>` - IPFS operations for pinning and retrieving data
+- `authorization: NosanaAuthorization | Omit<NosanaAuthorization, 'generate' | 'generateHeaders'>` - Authorization service for message signing and validation
 - `logger: Logger` - Logging instance
-- `wallet?: KeyPairSigner` - Active wallet (if set)
+- `wallet?: Wallet` - Active wallet (if set). Set this property directly to configure the wallet.
+
+**Factory Function:**
 
-**Methods:**
-- `setWallet(wallet: WalletConfig): Promise<KeyPairSigner>` - Set the signing wallet
+- `createNosanaClient(network?: NosanaNetwork, customConfig?: PartialClientConfig): NosanaClient` - Creates a new client instance
 
 ### Wallet Configuration
 
-The SDK supports multiple wallet input formats:
+The SDK supports universal wallet configuration through a unified `Wallet` type that must support both message and transaction signing (`MessageSigner & TransactionSigner`). This enables compatibility with both browser wallets (wallet-standard) and keypair-based wallets.
+
+#### Wallet Requirements
+
+The wallet must implement both `MessageSigner` and `TransactionSigner` interfaces from `@solana/kit`. This allows the SDK to use the wallet for:
+- **Message signing** - For API authentication and authorization
+- **Transaction signing** - For on-chain operations
+
+#### Browser Wallets (Wallet-Standard)
+
+Full support for wallet-standard compatible browser wallets (Phantom, Solflare, etc.):
 
 ```typescript
-// Number array (raw keypair)
-await client.setWallet([1, 2, 3, ..., 64]);
+import { createNosanaClient } from '@nosana/kit';
+import { useWalletAccountSigner } from '@nosana/solana-vue';
 
-// JSON string
-await client.setWallet(JSON.stringify(keypairArray));
+// Create client
+const client = createNosanaClient();
 
-// Base58 string
-await client.setWallet('base58EncodedPrivateKey');
+// Set browser wallet (wallet-standard compatible)
+client.wallet = useWalletAccountSigner(account, currentChain);
+```
 
-// File path
-await client.setWallet('/path/to/keypair.json');
+#### Keypair Wallets
 
-// Environment variable (JSON array or base58)
-process.env.SOLANA_PRIVATE_KEY = JSON.stringify(keypairArray);
-await client.setWallet('env:SOLANA_PRIVATE_KEY');
+Seamless support for keypair-based wallets:
 
-// Browser wallet adapter
-await client.setWallet(browserWalletAdapter);
+```typescript
+import { createNosanaClient } from '@nosana/kit';
+import { generateKeyPairSigner } from '@solana/kit';
 
-// Existing KeyPairSigner (passthrough)
-await client.setWallet(existingKeypairSigner);
+// Create client
+const client = createNosanaClient();
+
+// Set keypair wallet
+const keypair = generateKeyPairSigner();
+client.wallet = keypair;
 ```
 
+#### Configuration Options
+
+Wallets can be set at client initialization or dynamically assigned:
+
+```typescript
+import { createNosanaClient, NosanaNetwork } from '@nosana/kit';
+import type { Wallet } from '@nosana/kit';
+
+// Option 1: Set wallet during initialization
+const client = createNosanaClient(NosanaNetwork.MAINNET, {
+  wallet: myWallet,
+});
+
+// Option 2: Set wallet dynamically
+const client = createNosanaClient();
+client.wallet = myWallet;
+
+// Option 3: Change wallet at runtime
+client.wallet = anotherWallet;
+```
+
+#### Type Safety
+
+The SDK leverages `@solana/kit` types for compile-time safety, ensuring wallet compatibility before runtime.
+
 ## Jobs Program API
 
 ### Fetching Accounts
@@ -145,10 +197,10 @@ Fetch a job account. If `checkRun` is true (default), automatically checks for a
 
 ```typescript
 const job = await client.jobs.get('job-address');
-console.log(job.state);      // JobState enum
-console.log(job.price);      // Job price in smallest unit
-console.log(job.ipfsJob);    // IPFS CID of job definition
-console.log(job.timeStart);  // Start timestamp (if running)
+console.log(job.state); // JobState enum
+console.log(job.price); // Job price in smallest unit
+console.log(job.ipfsJob); // IPFS CID of job definition
+console.log(job.timeStart); // Start timestamp (if running)
 ```
 
 #### Get Single Run
@@ -161,9 +213,9 @@ Fetch a run account by address.
 
 ```typescript
 const run = await client.jobs.run('run-address');
-console.log(run.job);   // Associated job address
-console.log(run.node);  // Node executing the run
-console.log(run.time);  // Run start time
+console.log(run.job); // Associated job address
+console.log(run.node); // Node executing the run
+console.log(run.time); // Run start time
 ```
 
 #### Get Single Market
@@ -176,8 +228,8 @@ Fetch a market account by address.
 
 ```typescript
 const market = await client.jobs.market('market-address');
-console.log(market.queueType);  // MarketQueueType enum
-console.log(market.jobPrice);   // Market job price
+console.log(market.queueType); // MarketQueueType enum
+console.log(market.jobPrice); // Market job price
 ```
 
 #### Get Multiple Jobs
@@ -189,11 +241,7 @@ async multiple(addresses: Address[], checkRuns?: boolean): Promise<Job[]>
 Batch fetch multiple jobs by addresses.
 
 ```typescript
-const jobs = await client.jobs.multiple([
-  'job-address-1',
-  'job-address-2',
-  'job-address-3'
-], true);
+const jobs = await client.jobs.multiple(['job-address-1', 'job-address-2', 'job-address-3'], true);
 ```
 
 ### Querying with Filters
@@ -217,12 +265,12 @@ import { JobState } from '@nosana/kit';
 // Get all running jobs in a market
 const runningJobs = await client.jobs.all({
   state: JobState.RUNNING,
-  market: 'market-address'
+  market: 'market-address',
 });
 
 // Get all jobs for a project
 const projectJobs = await client.jobs.all({
-  project: 'project-address'
+  project: 'project-address',
 });
 ```
 
@@ -248,17 +296,13 @@ const nodeRuns = await client.jobs.runs({ node: 'node-address' });
 #### Query All Markets
 
 ```typescript
-async markets(filters?: {
-  project?: Address
-}): Promise<Market[]>
+async markets(): Promise<Market[]>
 ```
 
-Fetch markets with optional project filtering.
+Fetch all market accounts.
 
 ```typescript
-const projectMarkets = await client.jobs.markets({ 
-  project: 'project-address' 
-});
+const markets = await client.jobs.markets();
 ```
 
 ### Creating Jobs
@@ -278,18 +322,18 @@ Create a list instruction for posting a job to a market. Returns an instruction
 
 ```typescript
 // Set wallet first
-await client.setWallet(yourKeypair);
+client.wallet = yourWallet;
 
 // Create job instruction
 const instruction = await client.jobs.post({
   market: 'market-address',
-  timeout: 3600,           // Timeout in seconds
-  ipfsHash: 'QmXxx...',    // IPFS CID of job definition
-  node: 'node-address'     // Optional: target specific node
+  timeout: 3600, // Timeout in seconds
+  ipfsHash: 'QmXxx...', // IPFS CID of job definition
+  node: 'node-address', // Optional: target specific node
 });
 
 // Submit the instruction
-await client.solana.send(instruction);
+await client.solana.buildSignAndSend(instruction);
 ```
 
 ### Real-time Monitoring
@@ -312,7 +356,7 @@ Subscribe to real-time account updates via WebSocket. Includes automatic reconne
 const stopMonitoring = await client.jobs.monitor({
   onJobAccount: async (job) => {
     console.log('Job update:', job.address, job.state);
-    
+
     // Process updates - save to database, trigger workflows, etc.
     if (job.state === JobState.COMPLETED) {
       await processCompletedJob(job);
@@ -323,7 +367,7 @@ const stopMonitoring = await client.jobs.monitor({
   },
   onError: (error) => {
     console.error('Monitor error:', error);
-  }
+  },
 });
 
 // Stop monitoring when done
@@ -339,24 +383,24 @@ The monitor handles WebSocket reconnection automatically and continues processin
 ```typescript
 type Job = {
   address: Address;
-  state: JobState;           // QUEUED | RUNNING | COMPLETED | STOPPED
-  ipfsJob: string | null;    // IPFS CID of job definition
+  state: JobState; // QUEUED | RUNNING | COMPLETED | STOPPED
+  ipfsJob: string | null; // IPFS CID of job definition
   ipfsResult: string | null; // IPFS CID of job result
   market: Address;
   node: Address;
   payer: Address;
   project: Address;
   price: number;
-  timeStart: number;         // Unix timestamp
-  timeEnd: number;           // Unix timestamp
-  timeout: number;           // Seconds
+  timeStart: number; // Unix timestamp
+  timeEnd: number; // Unix timestamp
+  timeout: number; // Seconds
 };
 
 enum JobState {
   QUEUED = 0,
   RUNNING = 1,
   COMPLETED = 2,
-  STOPPED = 3
+  STOPPED = 3,
 }
 ```
 
@@ -365,9 +409,9 @@ enum JobState {
 ```typescript
 type Run = {
   address: Address;
-  job: Address;      // Associated job
-  node: Address;     // Node executing the job
-  time: number;      // Unix timestamp
+  job: Address; // Associated job
+  node: Address; // Node executing the job
+  time: number; // Unix timestamp
 };
 ```
 
@@ -376,7 +420,7 @@ type Run = {
 ```typescript
 type Market = {
   address: Address;
-  queueType: MarketQueueType;  // JOB_QUEUE | NODE_QUEUE
+  queueType: MarketQueueType; // JOB_QUEUE | NODE_QUEUE
   jobPrice: number;
   nodeStakeMinimum: number;
   jobTimeout: number;
@@ -387,7 +431,7 @@ type Market = {
 
 enum MarketQueueType {
   JOB_QUEUE = 0,
-  NODE_QUEUE = 1
+  NODE_QUEUE = 1,
 }
 ```
 
@@ -398,14 +442,34 @@ General Solana utility service for low-level RPC operations, transactions, and P
 ### Methods
 
 ```typescript
-// Send transaction (instruction, array, or transaction object)
-send(tx: IInstruction | IInstruction[] | Transaction): Promise<Signature>
+// Build, sign, and send transaction in one call (convenience method)
+buildSignAndSend(
+  instructions: Instruction | Instruction[],
+  options?: {
+    feePayer?: TransactionSigner;
+    commitment?: 'processed' | 'confirmed' | 'finalized';
+  }
+): Promise<Signature>
 
-// Get account balance
-getBalance(address: Address | string): Promise<bigint>
+// Build transaction from instructions
+buildTransaction(
+  instructions: Instruction | Instruction[],
+  options?: { feePayer?: TransactionSigner }
+): Promise<TransactionMessage & TransactionMessageWithFeePayer & TransactionMessageWithBlockhashLifetime>
 
-// Get latest blockhash
-getLatestBlockhash(): Promise<{ blockhash: string, lastValidBlockHeight: number }>
+// Sign a transaction message
+signTransaction(
+  transactionMessage: TransactionMessage & TransactionMessageWithFeePayer & TransactionMessageWithBlockhashLifetime
+): Promise<SendableTransaction & Transaction & TransactionWithBlockhashLifetime>
+
+// Send and confirm a signed transaction
+sendTransaction(
+  transaction: SendableTransaction & Transaction & TransactionWithBlockhashLifetime,
+  options?: { commitment?: 'processed' | 'confirmed' | 'finalized' }
+): Promise<Signature>
+
+// Get account balance
+getBalance(address?: Address | string): Promise<bigint>
 
 // Derive program derived address
 pda(seeds: Array<Address | string>, programId: Address): Promise<Address>
@@ -414,70 +478,390 @@ pda(seeds: Array<Address | string>, programId: Address): Promise<Address>
 ### Examples
 
 ```typescript
-// Send a single instruction
-const signature = await client.solana.send(instruction);
+// Send a single instruction (convenience method)
+const signature = await client.solana.buildSignAndSend(instruction);
 
 // Send multiple instructions atomically
-const signature = await client.solana.send([ix1, ix2, ix3]);
+const signature = await client.solana.buildSignAndSend([ix1, ix2, ix3]);
+
+// Or build, sign, and send separately for more control
+const transactionMessage = await client.solana.buildTransaction(instruction);
+const signedTransaction = await client.solana.signTransaction(transactionMessage);
+const signature = await client.solana.sendTransaction(signedTransaction);
 
 // Check account balance
 const balance = await client.solana.getBalance('address');
 console.log(`Balance: ${balance} lamports`);
 
 // Derive PDA
-const pda = await client.solana.pda(
-  ['seed1', 'seed2'],
-  programAddress
-);
+const pda = await client.solana.pda(['seed1', 'seed2'], programAddress);
 ```
 
-## IPFS Utilities
+## IPFS Service
 
-### Static Methods
+The IPFS service provides methods to pin data to IPFS and retrieve data from IPFS. It's configured via the `ipfs` property in the client configuration.
 
-```typescript
-// Convert Solana hash to IPFS CID
-IPFS.solHashToIpfsHash(hash: Uint8Array | number[]): string | null
+### Configuration
 
-// Convert IPFS hash to byte array
-IPFS.IpfsHashToByteArray(ipfsHash: string): Uint8Array
+```typescript
+const client = createNosanaClient(NosanaNetwork.MAINNET, {
+  ipfs: {
+    api: 'https://api.pinata.cloud',
+    jwt: 'your-pinata-jwt-token',
+    gateway: 'https://gateway.pinata.cloud/ipfs/',
+  },
+});
 ```
 
-### Instance Methods
+### Methods
 
 ```typescript
-// Pin JSON data to Pinata
-pin(data: object, name?: string): Promise<string>
+// Pin JSON data to IPFS
+pin(data: object): Promise<string>
 
-// Pin file to Pinata
-pinFile(filePath: string, name?: string): Promise<string>
-
-// Pin buffer/stream to Pinata
-pinFileFromBuffer(source: Buffer | Readable, filename: string): Promise<string>
+// Pin a file to IPFS
+pinFile(filePath: string): Promise<string>
 
 // Retrieve data from IPFS
-retrieve(hash: string | Uint8Array, options?: AxiosRequestConfig): Promise<any>
+retrieve(hash: string | Uint8Array): Promise<any>
 ```
 
 ### Examples
 
 ```typescript
-// Convert between Solana and IPFS hash formats
-const ipfsCid = IPFS.solHashToIpfsHash(solanaHashBytes);
-const solanaHash = IPFS.IpfsHashToByteArray(ipfsCid);
-
-// Pin job definition
+// Pin job definition to IPFS
 const cid = await client.ipfs.pin({
   version: 1,
   type: 'docker',
   image: 'ubuntu:latest',
-  command: ['echo', 'hello']
-}, 'job-definition');
+  command: ['echo', 'hello'],
+});
+console.log('Pinned to IPFS:', cid);
 
-// Retrieve job results
+// Pin a file to IPFS
+const fileCid = await client.ipfs.pinFile('/path/to/file.txt');
+
+// Retrieve job results from IPFS
 const results = await client.ipfs.retrieve(job.ipfsResult);
+console.log('Job results:', results);
+```
+
+### Utility Functions
+
+The SDK also exports utility functions for converting between Solana hash formats and IPFS CIDs:
+
+```typescript
+import { solBytesArrayToIpfsHash, ipfsHashToSolBytesArray } from '@nosana/kit';
+
+// Convert Solana hash bytes to IPFS CID
+const ipfsCid = solBytesArrayToIpfsHash(solanaHashBytes);
+
+// Convert IPFS CID to Solana hash bytes
+const solanaHash = ipfsHashToSolBytesArray(ipfsCid);
 ```
 
+## API Service
+
+The API service provides access to Nosana APIs for jobs, credits, and markets. It's automatically configured based on your authentication method.
+
+### Authentication Methods
+
+The API service supports two authentication methods:
+
+1. **API Key Authentication** (Recommended for server-side applications)
+   - Provide an API key in the configuration
+   - API key takes precedence over wallet-based authentication
+
+2. **Wallet-Based Authentication** (For client-side applications)
+   - Set a wallet on the client
+   - Uses message signing for authentication
+   - Automatically enabled when a wallet is configured
+
+### Configuration
+
+```typescript
+// Option 1: Use API key (recommended for servers)
+const client = createNosanaClient(NosanaNetwork.MAINNET, {
+  api: {
+    apiKey: 'your-api-key-here',
+  },
+});
+
+// Option 2: Use wallet-based auth (for client-side)
+const client = createNosanaClient(NosanaNetwork.MAINNET);
+client.wallet = myWallet;
+
+// Option 3: API key takes precedence when both are provided
+const client = createNosanaClient(NosanaNetwork.MAINNET, {
+  api: {
+    apiKey: 'your-api-key-here',
+  },
+  wallet: myWallet, // API key will be used, not wallet
+});
+```
+
+### Behavior
+
+- **With API Key**: API is created immediately with API key authentication
+- **With Wallet**: API is created when wallet is set, using wallet-based authentication
+- **Without Both**: API is `undefined` until either an API key or wallet is provided
+- **Priority**: If both API key and wallet are provided, API key is used
+
+### API Structure
+
+The API service provides access to three main APIs:
+
+```typescript
+client.api?.jobs    // Jobs API
+client.api?.credits // Credits API
+client.api?.markets // Markets API
+```
+
+### Examples
+
+```typescript
+// Using API key
+const client = createNosanaClient(NosanaNetwork.MAINNET, {
+  api: { apiKey: 'your-api-key' },
+});
+
+// API is immediately available
+if (client.api) {
+  // Use the API
+  const jobs = await client.api.jobs.list();
+}
+
+// Using wallet-based auth
+const client = createNosanaClient(NosanaNetwork.MAINNET);
+client.wallet = myWallet;
+
+// API is now available
+if (client.api) {
+  const credits = await client.api.credits.get();
+}
+
+// API updates reactively when wallet changes
+client.wallet = undefined; // API becomes undefined
+client.wallet = anotherWallet; // API is recreated with new wallet
+```
+
+## Authorization Service
+
+The authorization service provides cryptographic message signing and validation using Ed25519 signatures. It's automatically available on the client and adapts based on whether a wallet is configured.
+
+### Behavior
+
+- **With Wallet**: When a wallet is set, the authorization service provides all methods including `generate`, `validate`, `generateHeaders`, and `validateHeaders`.
+- **Without Wallet**: When no wallet is set, the authorization service only provides `validate` and `validateHeaders` methods (read-only validation).
+
+### Methods
+
+```typescript
+// Generate a signed message (requires wallet)
+generate(message: string | Uint8Array, options?: GenerateOptions): Promise<string>
+
+// Validate a signed message
+validate(
+  message: string | Uint8Array,
+  signature: string | Uint8Array,
+  publicKey?: string | Uint8Array
+): Promise<boolean>
+
+// Generate signed HTTP headers (requires wallet)
+generateHeaders(
+  method: string,
+  path: string,
+  body?: string | Uint8Array,
+  options?: GenerateHeaderOptions
+): Promise<Headers>
+
+// Validate HTTP headers
+validateHeaders(headers: Headers | Record<string, string>): Promise<boolean>
+```
+
+### Examples
+
+```typescript
+// Set wallet first to enable signing
+client.wallet = myWallet;
+
+// Generate a signed message
+const signedMessage = await client.authorization.generate('Hello, Nosana!');
+console.log('Signed message:', signedMessage);
+
+// Validate a signed message
+const isValid = await client.authorization.validate('Hello, Nosana!', signedMessage);
+console.log('Message is valid:', isValid);
+
+// Generate signed HTTP headers for API requests
+const headers = await client.authorization.generateHeaders(
+  'POST',
+  '/api/jobs',
+  JSON.stringify({ data: 'example' })
+);
+
+// Use headers in HTTP request
+fetch('https://api.nosana.com/api/jobs', {
+  method: 'POST',
+  headers: headers,
+  body: JSON.stringify({ data: 'example' }),
+});
+
+// Validate incoming HTTP headers
+const isValidRequest = await client.authorization.validateHeaders(requestHeaders);
+if (!isValidRequest) {
+  throw new Error('Invalid authorization');
+}
+```
+
+### Use Cases
+
+- **API Authentication**: Sign requests to Nosana APIs using message signatures
+- **Message Verification**: Verify signed messages from other parties
+- **Secure Communication**: Establish authenticated communication channels
+- **Request Authorization**: Validate incoming API requests
+
+## Merkle Distributor Program
+
+The MerkleDistributorProgram provides methods to interact with merkle distributor accounts and claim tokens from distributions.
+
+### Get a Single Distributor
+
+Fetch a merkle distributor account by its address:
+
+```typescript
+const distributor = await client.merkleDistributor.get('distributor-address');
+
+console.log('Distributor:', distributor.address);
+console.log('Admin:', distributor.admin);
+console.log('Mint:', distributor.mint);
+console.log('Root:', distributor.root);
+```
+
+### Get All Distributors
+
+Fetch all merkle distributor accounts:
+
+```typescript
+const distributors = await client.merkleDistributor.all();
+console.log(`Found ${distributors.length} distributors`);
+```
+
+### Get Claim Status
+
+Fetch claim status for a specific distributor and claimant:
+
+```typescript
+// Get claim status for the wallet's address
+const claimStatus =
+  await client.merkleDistributor.getClaimStatusForDistributor('distributor-address');
+
+// Or specify a claimant address
+const claimStatus = await client.merkleDistributor.getClaimStatusForDistributor(
+  'distributor-address',
+  'claimant-address'
+);
+
+if (claimStatus) {
+  console.log('Claimed:', claimStatus.claimed);
+  console.log('Amount Unlocked:', claimStatus.amountUnlocked);
+  console.log('Amount Locked:', claimStatus.amountLocked);
+} else {
+  console.log('No claim status found');
+}
+```
+
+### Get Claim Status PDA
+
+Derive the ClaimStatus PDA address:
+
+```typescript
+// Derive for wallet's address
+const pda = await client.merkleDistributor.getClaimStatusPda('distributor-address');
+
+// Or specify a claimant address
+const pda = await client.merkleDistributor.getClaimStatusPda(
+  'distributor-address',
+  'claimant-address'
+);
+```
+
+### Claim Tokens
+
+Claim tokens from a merkle distributor:
+
+```typescript
+// Set wallet first
+client.wallet = yourWallet;
+
+// Claim tokens
+const instruction = await client.merkleDistributor.claim({
+  distributor: 'distributor-address',
+  amountUnlocked: 1000000, // Amount in smallest unit
+  amountLocked: 500000,
+  proof: [
+    /* merkle proof array */
+  ],
+  target: ClaimTarget.YES, // or ClaimTarget.NO
+});
+
+// Submit the instruction
+await client.solana.buildSignAndSend(instruction);
+```
+
+### Clawback Tokens
+
+Clawback tokens from a merkle distributor (admin only):
+
+```typescript
+// Set wallet first (must be admin)
+client.wallet = adminWallet;
+
+// Clawback tokens
+const instruction = await client.merkleDistributor.clawback({
+  distributor: 'distributor-address',
+});
+
+// Submit the instruction
+await client.solana.buildSignAndSend(instruction);
+```
+
+### Type Definitions
+
+```typescript
+interface MerkleDistributor {
+  address: Address;
+  admin: Address;
+  mint: Address;
+  root: string; // Base58 encoded merkle root
+  buffer0: string;
+  buffer1: string;
+  buffer2: string;
+  // ... additional fields
+}
+
+interface ClaimStatus {
+  address: Address;
+  distributor: Address;
+  claimant: Address;
+  claimed: boolean;
+  amountUnlocked: number;
+  amountLocked: number;
+}
+
+enum ClaimTarget {
+  YES = 'YES',
+  NO = 'NO',
+}
+```
+
+### Use Cases
+
+- **Airdrop Claims**: Allow users to claim tokens from merkle tree distributions
+- **Reward Distribution**: Distribute rewards to eligible addresses
+- **Token Vesting**: Manage locked and unlocked token distributions
+- **Governance**: Distribute governance tokens to eligible participants
+
 ## Staking Program
 
 The StakeProgram provides methods to interact with Nosana staking accounts on-chain.
@@ -506,7 +890,7 @@ Fetch multiple stake accounts by their addresses:
 const addresses = ['address1', 'address2', 'address3'];
 const stakes = await client.stake.multiple(addresses);
 
-stakes.forEach(stake => {
+stakes.forEach((stake) => {
   console.log(`${stake.address}: ${stake.amount} staked`);
 });
 ```
@@ -555,9 +939,7 @@ const totalStaked = allStakes.reduce((sum, stake) => sum + stake.amount, 0);
 const averageStake = totalStaked / allStakes.length;
 
 // Find largest stake
-const largestStake = allStakes.reduce((max, stake) => 
-  Math.max(max, stake.amount), 0
-);
+const largestStake = allStakes.reduce((max, stake) => Math.max(max, stake.amount), 0);
 
 console.log('Staking Statistics:');
 console.log(`Total Staked: ${totalStaked.toLocaleString()} NOS`);
@@ -566,9 +948,9 @@ console.log(`Largest Stake: ${largestStake.toLocaleString()} NOS`);
 console.log(`Number of Stakers: ${allStakes.length}`);
 ```
 
-## NOS Token Service
+## Token Service
 
-The NosService provides methods to interact with NOS token accounts on Solana.
+The TokenService provides methods to interact with token accounts on Solana. In the NosanaClient, it's configured for the NOS token and accessible via `client.nos`.
 
 ### Get All Token Holders
 
@@ -580,7 +962,7 @@ const holders = await client.nos.getAllTokenHolders();
 
 console.log(`Found ${holders.length} NOS token holders`);
 
-holders.forEach(holder => {
+holders.forEach((holder) => {
   console.log(`${holder.owner}: ${holder.uiAmount} NOS`);
 });
 
@@ -593,9 +975,9 @@ const userAccounts = await client.nos.getAllTokenHolders({ excludePdaAccounts: t
 console.log(`User-owned accounts: ${userAccounts.length}`);
 
 // Combine filters
-const activeUsers = await client.nos.getAllTokenHolders({ 
+const activeUsers = await client.nos.getAllTokenHolders({
   includeZeroBalance: false,
-  excludePdaAccounts: true 
+  excludePdaAccounts: true,
 });
 console.log(`Active user accounts: ${activeUsers.length}`);
 ```
@@ -640,7 +1022,7 @@ interface TokenAccount {
 }
 
 interface TokenAccountWithBalance extends TokenAccount {
-  uiAmount: number;  // Balance with decimals applied
+  uiAmount: number; // Balance with decimals applied
 }
 ```
 
@@ -658,7 +1040,7 @@ interface TokenAccountWithBalance extends TokenAccount {
 const holders = await client.nos.getAllTokenHolders();
 
 // Find holders with at least 1000 NOS
-const largeHolders = holders.filter(h => h.uiAmount >= 1000);
+const largeHolders = holders.filter((h) => h.uiAmount >= 1000);
 
 // Sort by balance descending
 largeHolders.sort((a, b) => b.uiAmount - a.uiAmount);
@@ -694,7 +1076,7 @@ enum ErrorCodes {
   VALIDATION_ERROR = 'VALIDATION_ERROR',
   NO_WALLET = 'NO_WALLET',
   FILE_ERROR = 'FILE_ERROR',
-  WALLET_CONVERSION_ERROR = 'WALLET_CONVERSION_ERROR'
+  WALLET_CONVERSION_ERROR = 'WALLET_CONVERSION_ERROR',
 }
 ```
 
@@ -713,7 +1095,7 @@ try {
         break;
       case ErrorCodes.NO_WALLET:
         console.error('Wallet not configured');
-        await client.setWallet(keypair);
+        client.wallet = myWallet;
         break;
       case ErrorCodes.TRANSACTION_ERROR:
         console.error('Transaction failed:', error.details);
@@ -722,7 +1104,7 @@ try {
         console.error('Unknown error:', error.message);
     }
   } else {
-    throw error;  // Re-throw non-Nosana errors
+    throw error; // Re-throw non-Nosana errors
   }
 }
 ```
@@ -734,23 +1116,23 @@ The SDK includes a built-in singleton logger with configurable levels.
 ### Log Levels
 
 ```typescript
-enum NosanaLogLevel {
+enum LogLevel {
   DEBUG = 'debug',
   INFO = 'info',
   WARN = 'warn',
   ERROR = 'error',
-  NONE = 'none'
+  NONE = 'none',
 }
 ```
 
 ### Configuration
 
 ```typescript
-import { NosanaClient, NosanaLogLevel } from '@nosana/kit';
+import { createNosanaClient, LogLevel } from '@nosana/kit';
 
 // Set log level during initialization
-const client = new NosanaClient(NosanaNetwork.MAINNET, {
-  logLevel: NosanaLogLevel.DEBUG
+const client = createNosanaClient(NosanaNetwork.MAINNET, {
+  logLevel: LogLevel.DEBUG,
 });
 
 // Access logger directly
@@ -795,27 +1177,32 @@ npm run generate-clients
 The SDK is written in TypeScript and provides complete type definitions. All types are exported for use in your applications:
 
 ```typescript
-import type { 
-  Job, 
-  Run, 
-  Market, 
+import type {
+  Job,
+  Run,
+  Market,
   JobState,
   MarketQueueType,
+  Stake,
+  MerkleDistributor,
+  ClaimStatus,
+  ClaimTarget,
   ClientConfig,
   NosanaClient,
-  KeyPairSigner,
-  Address
+  Wallet,
 } from '@nosana/kit';
+import type { Address } from '@solana/kit';
 ```
 
 ## Dependencies
 
 Core dependencies:
-- `gill` ^0.9.0 - Solana web3 library
-- `@solana-program/token` ^0.5.1 - Token program utilities
-- `axios` ^1.6.0 - HTTP client
-- `bs58` ^6.0.0 - Base58 encoding
-- `form-data` ^4.0.0 - Multipart form data
+
+- `@solana/kit` 5.0.0 - Solana web3 library
+- `@solana-program/token` 0.8.0 - Token program utilities
+- `@solana-program/system` 0.10.0 - System program utilities
+- `@solana-program/compute-budget` 0.11.0 - Compute budget utilities
+- `bs58` 6.0.0 - Base58 encoding
 
 ## License