npm package: @karma3labs/karmalaunch-solana
Description: TypeScript SDK for interacting with the KarmaLaunch Solana program
Author: Karma3Labs
Latest version: 0.1.1

# @karma3labs/karmalaunch-solana

TypeScript SDK for interacting with the KarmaLaunch Solana program.

## Installation

```bash
npm install @karma3labs/karmalaunch-solana
# or
yarn add @karma3labs/karmalaunch-solana
```

## Peer Dependencies

This SDK requires the following peer dependencies:

```bash
npm install @coral-xyz/anchor @solana/web3.js @solana/spl-token
```

## Quick Start

```typescript
import { KarmaLaunchClient, KARMALAUNCH_PROGRAM_ID } from '@karma3labs/karmalaunch-solana';
import { AnchorProvider } from '@coral-xyz/anchor';
import { Connection, Keypair, PublicKey } from '@solana/web3.js';

// Create a provider
const connection = new Connection('https://api.mainnet-beta.solana.com');
const wallet = // your wallet adapter or keypair
const provider = new AnchorProvider(connection, wallet, {});

// Create the client
const client = new KarmaLaunchClient(provider);

// Initialize a launch
await client.initializeLaunchIx({
  tokenName: 'MyToken',
  tokenSymbol: 'MTK',
  tokenUri: 'https://example.com/metadata.json',
  minimumRaiseAmount: new BN(1000_000000), // 1000 USDC
  secondsForLaunch: 60 * 60 * 24 * 7, // 1 week
  monthsUntilInsidersCanUnlock: 24,
  teamAddress: teamWallet,
  baseMint: tokenMint,
  quoteMint: MAINNET_USDC,
  launchAuthority: authority.publicKey,
}).rpc();
```

## Network Configuration

The SDK supports both mainnet and devnet. Use the appropriate USDC mint and Meteora config for your network:

```typescript
import {
  MAINNET_USDC,
  DEVNET_USDC,
  MAINNET_METEORA_CONFIG,
  getNetworkConfig,
} from '@karma3labs/karmalaunch-solana';

// Auto-detect network from provider endpoint
const config = getNetworkConfig(provider);
console.log(config.network); // 'mainnet' or 'devnet'
console.log(config.usdcMint); // Appropriate USDC mint

// Or use constants directly
const usdcMint = isDevnet ? DEVNET_USDC : MAINNET_USDC;
```

## API Reference

### KarmaLaunchClient

The main client for interacting with the KarmaLaunch program.

#### Constructor

```typescript
const client = new KarmaLaunchClient(provider: AnchorProvider);
```

#### Methods

All instruction methods return an Anchor `MethodsBuilder` that can be chained with `.accounts()`, `.preInstructions()`, `.signers()`, and `.rpc()`.

##### initializeLaunchIx(args)

Initialize a new token launch.

```typescript
client.initializeLaunchIx({
  tokenName: string,
  tokenSymbol: string,
  tokenUri: string,
  minimumRaiseAmount: BN | number | bigint,
  secondsForLaunch: number,
  monthsUntilInsidersCanUnlock: number,
  teamAddress: PublicKey,
  baseMint?: PublicKey,
  quoteMint?: PublicKey,
  launchAuthority?: PublicKey,
  additionalTokensAmount?: BN | number | bigint,
  additionalTokensRecipient?: PublicKey,
})
```

##### startLaunchIx({ launch, launchAuthority })

Start the funding period for a launch.

##### fundIx({ launch, amount, funder, quoteMint? })

Commit USDC to a launch.

##### closeLaunchIx({ launch })

Close the funding period.

##### setFundingRecordApprovalIx({ launch, funder, launchAuthority, approvedAmount })

Approve a funder's contribution (launch authority only).

##### completeLaunchIx({ launch, baseMint, launchAuthority, teamAddress, ... })

Complete the launch and create the liquidity pool.

##### claimIx({ launch, funder, baseMint })

Claim tokens after a successful launch.

##### refundIx(launch, funder, isDevnet?)

Refund USDC if the launch failed or was over-committed.

#### Fetch Methods

```typescript
// Fetch a Launch account
const launch = await client.fetchLaunch(launchAddress);

// Fetch a FundingRecord account
const record = await client.fetchFundingRecord(recordAddress);
```

#### PDA Helpers

```typescript
// Get Launch PDA
const launchAddress = client.getLaunchAddress({ baseMint });

// Get LaunchSigner PDA
const signerAddress = client.getLaunchSignerAddress({ launch });

// Get FundingRecord PDA
const recordAddress = client.getFundingRecordAddress({ launch, funder });
```

### PDA Utilities

Standalone PDA derivation functions:

```typescript
import {
  getLaunchAddr,
  getLaunchSignerAddr,
  getFundingRecordAddr,
  getMetadataAddr,
  getEventAuthorityAddr,
} from '@karma3labs/karmalaunch-solana';

const [launch, bump] = getLaunchAddr(programId, baseMint);
```

### Constants

```typescript
import {
  KARMALAUNCH_PROGRAM_ID,
  MAINNET_USDC,
  DEVNET_USDC,
  MAINNET_METEORA_CONFIG,
  DAMM_V2_PROGRAM_ID,
  MPL_TOKEN_METADATA_PROGRAM_ID,
  TOKEN_2022_PROGRAM_ID,
  TOKEN_SCALE,
  TOTAL_SUPPLY,
  TOKENS_TO_PARTICIPANTS,
  TOKENS_TO_LP,
  TOKENS_TO_TEAM,
} from '@karma3labs/karmalaunch-solana';
```

## Launch Lifecycle

1. **Initialize**: Create a launch with token metadata and parameters
2. **Start**: Authority starts the funding period
3. **Fund**: Users commit USDC during the live period
4. **Close**: Authority closes funding period
5. **Approve**: Authority approves individual funders (within 2 days)
6. **Complete**: Authority finalizes the launch (creates pool, DAO)
7. **Claim/Refund**: Users claim tokens or get refunds

## Types

The SDK exports all IDL-generated types:

```typescript
import type { Karmalaunch, Launch, FundingRecord, LaunchState } from '@karma3labs/karmalaunch-solana';
```

## License

MIT