npm package: @pauldevlee/sns-cnft-mint-sdk
Description: User SDK for cNFT minting and transfer operations
Author: SNS Team
Latest version: 1.0.3

# SNS cNFT Mint SDK

A user-friendly SDK for minting and transferring Core NFTs (cNFTs) on Solana. This SDK generates transaction instructions that can be signed by user wallets, ensuring security and user control.

## Features

- **Mint NFTs** from Core Candy Machine
- **Transfer NFTs** between wallets
- **Instruction-only approach** - No transaction signing within SDK
- **Type-safe** TypeScript implementation
- **User-controlled** - All sensitive operations handled by calling application

## Installation

```bash
npm install sns-cnft-mint-sdk
```

## Quick Start

```typescript
import { createMintSDK } from 'sns-cnft-mint-sdk';

// Initialize SDK
const sdk = createMintSDK({
  rpcUrl: 'https://api.devnet.solana.com'
});

// Mint NFT
const mintResult = await sdk.mintNft({
  candyMachineAddress: 'YOUR_CANDY_MACHINE_ADDRESS',
  userSigner: userWalletSigner, // From user's wallet
  collectionAddress: 'YOUR_COLLECTION_ADDRESS',
  candyGuardAddress: 'YOUR_CANDY_GUARD_ADDRESS',
  groupLabel: 'public',
  metadataUri: 'https://arweave.net/your-metadata',
  name: 'My NFT #1'
});

// Send instructions to user's wallet for signing
// await userWallet.sendTransaction(mintResult.instructions);
```

## API Reference

### SDK Configuration

```typescript
interface SDKConfig {
  rpcUrl: string; // Solana RPC endpoint
}
```

### Mint NFT

```typescript
interface MintNftParams {
  candyMachineAddress: string;  // Core Candy Machine address
  userSigner: any;              // User's wallet signer
  collectionAddress: string;    // Collection address
  candyGuardAddress: string;    // Candy Guard address
  groupLabel: string;           // Guard group label (e.g., 'public', 'whitelist')
  metadataUri: string;          // NFT metadata URI
  name: string;                 // NFT name
}

async mintNft(params: MintNftParams): Promise<MintResult>
```

### Transfer NFT

```typescript
interface TransferNftParams {
  assetAddress: string;         // NFT asset address
  newOwnerAddress: string;      // Recipient wallet address
  ownerSigner: any;             // Current owner's wallet signer
  collectionAddress: string;    // Collection address
}

async transferNft(params: TransferNftParams): Promise<TransferResult>
```

### Result Types

```typescript
interface MintResult {
  instructions: any[];          // Transaction instructions
  signers: any[];              // Required signers
  assetAddress: string;        // Generated NFT address
  metadataUri: string;         // Metadata URI
  name: string;                // NFT name
}

interface TransferResult {
  instructions: any[];          // Transaction instructions
  signers: any[];              // Required signers
  assetAddress: string;        // NFT address
  newOwnerAddress: string;     // New owner address
}
```

## Usage Examples

### Basic Minting

```typescript
import { createMintSDK } from 'sns-cnft-mint-sdk';

const sdk = createMintSDK({
  rpcUrl: 'https://api.devnet.solana.com'
});

// Mint single NFT
const result = await sdk.mintNft({
  candyMachineAddress: 'CM_ADDRESS',
  userSigner: userWalletSigner,
  collectionAddress: 'COLLECTION_ADDRESS',
  candyGuardAddress: 'GUARD_ADDRESS',
  groupLabel: 'public',
  metadataUri: 'https://arweave.net/metadata',
  name: 'My NFT'
});

console.log('NFT will be minted at:', result.assetAddress);
```

### Batch Minting

```typescript
// Mint multiple NFTs
const batchParams = [
  { /* mint params 1 */ },
  { /* mint params 2 */ },
  { /* mint params 3 */ }
];

const results = await Promise.all(
  batchParams.map(params => sdk.mintNft(params))
);

console.log(`Generated instructions for ${results.length} NFTs`);
```

### Transfer NFT

```typescript
// Transfer NFT to another wallet
const transferResult = await sdk.transferNft({
  assetAddress: 'NFT_ASSET_ADDRESS',
  newOwnerAddress: 'RECIPIENT_WALLET',
  ownerSigner: currentOwnerSigner,
  collectionAddress: 'COLLECTION_ADDRESS'
});

console.log('Transfer instructions generated');
```

## Security Considerations

- **No Private Keys**: This SDK never handles private keys or keypairs
- **User-Controlled Signing**: All transactions must be signed by user wallets
- **No Default Values**: All parameters must be explicitly provided
- **Instruction-Only**: SDK only generates instructions, never executes transactions

## Integration with Wallets

### Solana Wallet Adapter

```typescript
import { useWallet } from '@solana/wallet-adapter-react';

function MintButton() {
  const { publicKey, signTransaction } = useWallet();
  
  const handleMint = async () => {
    const result = await sdk.mintNft({
      // ... params
      userSigner: { publicKey, signTransaction }
    });
    
    // Send to wallet for signing
    const signedTx = await signTransaction(result.instructions);
    // Submit to blockchain
  };
}
```

### Phantom Wallet

```typescript
// With Phantom wallet
const result = await sdk.mintNft({
  // ... params
  userSigner: window.solana // Phantom wallet object
});
```

## Error Handling

```typescript
try {
  const result = await sdk.mintNft(params);
  // Handle success
} catch (error) {
  if (error.message.includes('required')) {
    // Handle missing parameter
  } else if (error.message.includes('invalid')) {
    // Handle invalid address
  } else {
    // Handle other errors
  }
}
```

## Development

```bash
# Install dependencies
npm install

# Build SDK
npm run build

# Run example
npm run example
```

## License

MIT

## Support

For support and questions, please contact the SNS Team.