@naclac/client

The official TypeScript SDK for the Naclac framework. @naclac/client provides a fluent, highly intuitive developer experience for interacting with Naclac programs on Solana.

Built on top of modern Solana libraries, this SDK empowers developers to rapidly integrate with on-chain programs, send transactions, fetch parsed account state, and listen to program events in a type-safe and zero-copy environment.

🚀 Features

• Fluent API Router: Effortlessly call instructions (program.methods.initialize().rpc()) and fetch accounts (program.account.Counter.fetch(address)).
• Type-Safe: Full TypeScript support driven by your IDL.
• Auto-Generated SDKs: First-class support for fully typed, project-specific SDKs generated by the Naclac framework CLI.
• Event Listeners: Real-time on-chain event listening with addEventListener and waitForEvent patterns.
• Modern Stack: Built on @solana/kit and @solana/codecs via gill for a fast, modern developer experience.
• PDA Resolution: Simple, automatic Program Derived Address resolution using IDL definitions.

📦 Installation

npm install @naclac/client
# or
yarn add @naclac/client
# or
pnpm add @naclac/client

🛠️ Usage

The @naclac/client SDK is highly versatile and supports multiple ways to interact with Solana programs depending on your setup.

Option A: Using Auto-Generated SDK Clients (Recommended)

If you are building your smart contract using the Naclac framework, you can automatically generate a custom, strongly-typed SDK for your specific project. This is the recommended approach for the best developer experience.

Here is an example of how to use an auto-generated client (e.g., NaclacCounterClient):

import * as naclac from "@naclac/client";
import { NaclacCounterClient } from "./clients/src/generated/naclac_counter";

// 1. Setup provider and client
const payer = await naclac.loadNodeWallet();
const client = new NaclacCounterClient("devnet", payer);

// 2. Resolve Program Derived Addresses (PDAs) automatically
const counterPda = await client.getCounterAccountPda({});

// 3. Fetch strongly-typed accounts
const counterState = await client.fetchCounter(counterPda);
console.log(`Current Count: ${counterState.count}`);

// 4. Listen to events with dedicated methods
const eventPromise = client.waitForCounterIncremented({ timeoutMs: 10000 });

// 5. Send transactions
await client
  .increment({})
  .accounts({ authority: payer.address, counterAccount: counterPda })
  .rpc();

// Wait for event
const event = await eventPromise;
console.log("Event captured:", event);

Option B: Using a Raw IDL (For Any Framework)

You do not need an auto-generated client to use @naclac/client. As long as you have a standard JSON IDL, you can use the core Program class dynamically. This means developers using other frameworks can also utilize @naclac/client for a superior frontend experience by just dropping in their IDL.

import * as naclac from "@naclac/client";
import { IDL } from "../target/types/my_program";

// 1. Create a provider
const provider = naclac.createProvider("devnet", wallet);

// 2. Initialize the dynamic program with the raw IDL
const program = new naclac.Program(IDL, provider);

// 3. Call instructions dynamically
const sig = await program.methods
  .initialize()
  .accounts({ 
    payer: wallet.address, 
    systemProgram: naclac.SYSTEM_PROGRAM_ID 
  })
  .rpc();

// 4. Fetch accounts dynamically
const data = await program.account.MyAccount.fetch(pdaAddress);
console.log(data);

// 5. Use dynamic event listeners
const listenerId = program.addEventListener("MyEvent", (event) => {
  console.log("Event detected:", event);
});

Option C: Without an IDL

Even if you don't have an IDL or a generated SDK, @naclac/client bundles and re-exports powerful primitives from gill and @solana/kit. You can use it as a robust base layer for general Solana interactions:

import * as naclac from "@naclac/client";

// Get base providers and wallets
const provider = naclac.createProvider("mainnet-beta");
const wallet = await naclac.loadNodeWallet();

// Use re-exported @solana/kit functions directly
const address = naclac.address("So11111111111111111111111111111111111111112");
const ata = await naclac.getAssociatedTokenAddress(address, wallet.address);

📚 API Reference

Program<TIdl>

The core class of the SDK for raw IDL usage.

• program.methods.[instructionName]: Dynamic namespace for building transactions.
• program.account.[accountName]: Dynamic namespace for fetching deserialized accounts.
• program.pda(accountName, seeds): Resolves PDAs based on the IDL schema.
• program.addEventListener(eventName, callback): Listens for a specific event.
• program.waitForEvent(eventName, options): Returns a promise that resolves when a specific event occurs.
• program.constants: Provides access to IDL-defined constants.

Shared Utilities

The SDK re-exports several primitives from gill and @solana/kit so you don't need separate imports for common Solana tasks:

• address()
• createKeyPairSignerFromBytes()
• getAssociatedTokenAddress()