@solana/kora 0.2.0-beta.4 → 0.2.0-beta.6

package/dist/src/index.d.ts

@@ -1,3 +1,4 @@
 export * from './types/index.js';
 export { KoraClient } from './client.js';
+export { createKitKoraClient, type KoraKitClient } from './kit/index.js';
 export { koraPlugin, type KoraApi } from './plugin.js';

package/dist/src/index.js

@@ -1,3 +1,4 @@
 export * from './types/index.js';
 export { KoraClient } from './client.js';
+export { createKitKoraClient } from './kit/index.js';
 export { koraPlugin } from './plugin.js';

package/dist/src/kit/executor.d.ts

@@ -0,0 +1,7 @@
+import { type Address, type TransactionMessage, type TransactionMessageWithFeePayer, type TransactionSigner } from '@solana/kit';
+import { KoraClient } from '../client.js';
+import type { KoraKitClientConfig } from '../types/index.js';
+export declare function createKoraTransactionPlanExecutor(koraClient: KoraClient, config: KoraKitClientConfig, payerSigner: TransactionSigner, payment: {
+    destinationTokenAccount: Address;
+    sourceTokenAccount: Address;
+} | undefined, resolveProvisoryComputeUnitLimit: (<T extends TransactionMessage & TransactionMessageWithFeePayer>(transactionMessage: T) => Promise<T>) | undefined): import("@solana/kit").TransactionPlanExecutor<import("@solana/kit").TransactionPlanResultContext>;

package/dist/src/kit/executor.js

@@ -0,0 +1,68 @@
+import { appendTransactionMessageInstructions, blockhash, createTransactionMessage, createTransactionPlanExecutor, getBase64EncodedWireTransaction, getBase64Encoder, getSignatureFromTransaction, getTransactionDecoder, partiallySignTransactionMessageWithSigners, pipe, setTransactionMessageFeePayerSigner, setTransactionMessageLifetimeUsingBlockhash, signature, } from '@solana/kit';
+import { removePaymentInstruction, updatePaymentInstructionAmount } from './payment.js';
+// TODO: Create a bundle-aware executor (e.g. `createKoraBundlePlanExecutor`) that collects
+// multiple planned transaction messages into a single `signAndSendBundle` call instead of
+// submitting each one individually via `signAndSendTransaction`. This would let users
+// compose Jito bundles through the Kit plan/execute pipeline rather than manually encoding
+// transactions and calling `client.kora.signAndSendBundle()`.
+export function createKoraTransactionPlanExecutor(koraClient, config, payerSigner, payment, resolveProvisoryComputeUnitLimit) {
+    return createTransactionPlanExecutor({
+        async executeTransactionMessage(_context, transactionMessage) {
+            // Kora manages blockhash validity; set max height to avoid premature client-side expiry checks
+            const { blockhash: bh } = await koraClient.getBlockhash();
+            const msgWithLifetime = setTransactionMessageLifetimeUsingBlockhash({
+                blockhash: blockhash(bh),
+                lastValidBlockHeight: BigInt(Number.MAX_SAFE_INTEGER),
+            }, transactionMessage);
+            const msgForEstimation = resolveProvisoryComputeUnitLimit
+                ? await resolveProvisoryComputeUnitLimit(msgWithLifetime)
+                : msgWithLifetime;
+            const prePaymentTx = getBase64EncodedWireTransaction(await partiallySignTransactionMessageWithSigners(msgForEstimation));
+            let finalTx;
+            if (payment) {
+                const { sourceTokenAccount, destinationTokenAccount } = payment;
+                const { fee_in_token } = await koraClient.estimateTransactionFee({
+                    fee_token: config.feeToken,
+                    transaction: prePaymentTx,
+                });
+                if (fee_in_token == null) {
+                    console.warn('[kora] fee_in_token is undefined — defaulting to 0. ' +
+                        'If paid pricing is expected, check that the fee token is correctly configured on the server.');
+                }
+                const feeInToken = fee_in_token ?? 0;
+                if (feeInToken < 0) {
+                    throw new Error(`Kora fee estimation returned a negative fee (${feeInToken}). This indicates a server-side error.`);
+                }
+                const currentIxs = 'instructions' in msgForEstimation
+                    ? msgForEstimation.instructions
+                    : undefined;
+                if (!currentIxs) {
+                    throw new Error('Cannot extract instructions from transaction message. ' +
+                        'The message structure may be incompatible with this version of the Kora SDK.');
+                }
+                // Replace placeholder with real fee amount, or strip it if fee is 0
+                const finalIxs = feeInToken > 0
+                    ? updatePaymentInstructionAmount(currentIxs, config.feePayerWallet, sourceTokenAccount, destinationTokenAccount, feeInToken, config.tokenProgramId)
+                    : removePaymentInstruction(currentIxs, sourceTokenAccount, destinationTokenAccount, config.feePayerWallet, config.tokenProgramId);
+                const resolvedMsg = pipe(createTransactionMessage({ version: 0 }), m => setTransactionMessageFeePayerSigner(payerSigner, m), m => setTransactionMessageLifetimeUsingBlockhash({
+                    blockhash: blockhash(bh),
+                    lastValidBlockHeight: BigInt(Number.MAX_SAFE_INTEGER),
+                }, m), m => appendTransactionMessageInstructions(finalIxs, m));
+                finalTx = getBase64EncodedWireTransaction(await partiallySignTransactionMessageWithSigners(resolvedMsg));
+            }
+            else {
+                finalTx = prePaymentTx;
+            }
+            const result = await koraClient.signAndSendTransaction({
+                transaction: finalTx,
+                user_id: config.userId,
+            });
+            if (result.signature) {
+                return signature(result.signature);
+            }
+            const signedTxBytes = getBase64Encoder().encode(result.signed_transaction);
+            const decodedTx = getTransactionDecoder().decode(signedTxBytes);
+            return getSignatureFromTransaction(decodedTx);
+        },
+    });
+}

package/dist/src/kit/index.d.ts

@@ -0,0 +1,53 @@
+import type { KoraKitClientConfig } from '../types/index.js';
+/** The type returned by {@link createKitKoraClient}. */
+export type KoraKitClient = Awaited<ReturnType<typeof createKitKoraClient>>;
+/**
+ * Creates a Kora Kit client composed from Kit plugins.
+ *
+ * The returned client satisfies `ClientWithPayer`, `ClientWithTransactionPlanning`,
+ * and `ClientWithTransactionSending`, making it composable with Kit program plugins.
+ *
+ * @beta This API is experimental and may change in future releases.
+ *
+ * @example
+ * ```typescript
+ * import { createKitKoraClient } from '@solana/kora';
+ * import { address } from '@solana/kit';
+ *
+ * const client = await createKitKoraClient({
+ *   endpoint: 'https://kora.example.com',
+ *   rpcUrl: 'https://api.mainnet-beta.solana.com',
+ *   feeToken: address('EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'),
+ *   feePayerWallet: userSigner,
+ * });
+ *
+ * const result = await client.sendTransaction([myInstruction]);
+ * ```
+ */
+export declare function createKitKoraClient(config: KoraKitClientConfig): Promise<import("@solana/kit").Client<import("@solana/kit").ClientWithTransactionPlanning & import("@solana/kit").ClientWithTransactionSending & object & {
+    rpc: import("@solana/kit").Rpc<import("@solana/kit").RequestAirdropApi & import("@solana/kit").GetAccountInfoApi & import("@solana/kit").GetBalanceApi & import("@solana/kit").GetBlockApi & import("@solana/kit").GetBlockCommitmentApi & import("@solana/kit").GetBlockHeightApi & import("@solana/kit").GetBlockProductionApi & import("@solana/kit").GetBlocksApi & import("@solana/kit").GetBlocksWithLimitApi & import("@solana/kit").GetBlockTimeApi & import("@solana/kit").GetClusterNodesApi & import("@solana/kit").GetEpochInfoApi & import("@solana/kit").GetEpochScheduleApi & import("@solana/kit").GetFeeForMessageApi & import("@solana/kit").GetFirstAvailableBlockApi & import("@solana/kit").GetGenesisHashApi & import("@solana/kit").GetHealthApi & import("@solana/kit").GetHighestSnapshotSlotApi & import("@solana/kit").GetIdentityApi & import("@solana/kit").GetInflationGovernorApi & import("@solana/kit").GetInflationRateApi & import("@solana/kit").GetInflationRewardApi & import("@solana/kit").GetLargestAccountsApi & import("@solana/kit").GetLatestBlockhashApi & import("@solana/kit").GetLeaderScheduleApi & import("@solana/kit").GetMaxRetransmitSlotApi & import("@solana/kit").GetMaxShredInsertSlotApi & import("@solana/kit").GetMinimumBalanceForRentExemptionApi & import("@solana/kit").GetMultipleAccountsApi & import("@solana/kit").GetProgramAccountsApi & import("@solana/kit").GetRecentPerformanceSamplesApi & import("@solana/kit").GetRecentPrioritizationFeesApi & import("@solana/kit").GetSignaturesForAddressApi & import("@solana/kit").GetSignatureStatusesApi & import("@solana/kit").GetSlotApi & import("@solana/kit").GetSlotLeaderApi & import("@solana/kit").GetSlotLeadersApi & import("@solana/kit").GetStakeMinimumDelegationApi & import("@solana/kit").GetSupplyApi & import("@solana/kit").GetTokenAccountBalanceApi & import("@solana/kit").GetTokenAccountsByDelegateApi & import("@solana/kit").GetTokenAccountsByOwnerApi & import("@solana/kit").GetTokenLargestAccountsApi & import("@solana/kit").GetTokenSupplyApi & import("@solana/kit").GetTransactionApi & import("@solana/kit").GetTransactionCountApi & import("@solana/kit").GetVersionApi & import("@solana/kit").GetVoteAccountsApi & import("@solana/kit").IsBlockhashValidApi & import("@solana/kit").MinimumLedgerSlotApi & import("@solana/kit").SendTransactionApi & import("@solana/kit").SimulateTransactionApi>;
+    rpcSubscriptions: import("@solana/kit").RpcSubscriptions<import("@solana/kit").SolanaRpcSubscriptionsApi>;
+} & {
+    kora: {
+        estimateBundleFee(request: import("../types/index.js").EstimateBundleFeeRequest): Promise<import("../types/index.js").KitEstimateBundleFeeResponse>;
+        estimateTransactionFee(request: import("../types/index.js").EstimateTransactionFeeRequest): Promise<import("../types/index.js").KitEstimateFeeResponse>;
+        getBlockhash(): Promise<import("../types/index.js").KitBlockhashResponse>;
+        getConfig(): Promise<import("../types/index.js").KitConfigResponse>;
+        getPayerSigner(): Promise<import("../types/index.js").KitPayerSignerResponse>;
+        getPaymentInstruction(request: import("../types/index.js").GetPaymentInstructionRequest): Promise<import("../types/index.js").KitPaymentInstructionResponse>;
+        getSupportedTokens(): Promise<import("../types/index.js").KitSupportedTokensResponse>;
+        getVersion(): Promise<import("../types/index.js").GetVersionResponse>;
+        signAndSendBundle(request: import("../types/index.js").SignAndSendBundleRequest): Promise<import("../types/index.js").KitSignAndSendBundleResponse>;
+        signAndSendTransaction(request: import("../types/index.js").SignAndSendTransactionRequest): Promise<import("../types/index.js").KitSignAndSendTransactionResponse>;
+        signBundle(request: import("../types/index.js").SignBundleRequest): Promise<import("../types/index.js").KitSignBundleResponse>;
+        signTransaction(request: import("../types/index.js").SignTransactionRequest): Promise<import("../types/index.js").KitSignTransactionResponse>;
+    };
+} & {
+    payer: import("@solana/kit").TransactionSigner;
+} & {
+    paymentAddress: import("@solana/kit").Address | undefined;
+} & {
+    transactionPlanner: import("@solana/kit").TransactionPlanner;
+} & {
+    transactionPlanExecutor: import("@solana/kit").TransactionPlanExecutor;
+}>>;

package/dist/src/kit/index.js

@@ -0,0 +1,75 @@
+import { address, createEmptyClient, createNoopSigner, createSolanaRpc } from '@solana/kit';
+import { planAndSendTransactions, transactionPlanExecutor as transactionPlanExecutorPlugin, transactionPlanner as transactionPlannerPlugin, } from '@solana/kit-plugin-instruction-plan';
+import { payer } from '@solana/kit-plugin-payer';
+import { rpc } from '@solana/kit-plugin-rpc';
+import { estimateAndUpdateProvisoryComputeUnitLimitFactory, estimateComputeUnitLimitFactory, } from '@solana-program/compute-budget';
+import { KoraClient } from '../client.js';
+import { koraPlugin } from '../plugin.js';
+import { createKoraTransactionPlanExecutor } from './executor.js';
+import { buildPlaceholderPaymentInstruction, koraPaymentAddress } from './payment.js';
+import { buildComputeBudgetInstructions, createKoraTransactionPlanner } from './planner.js';
+/**
+ * Creates a Kora Kit client composed from Kit plugins.
+ *
+ * The returned client satisfies `ClientWithPayer`, `ClientWithTransactionPlanning`,
+ * and `ClientWithTransactionSending`, making it composable with Kit program plugins.
+ *
+ * @beta This API is experimental and may change in future releases.
+ *
+ * @example
+ * ```typescript
+ * import { createKitKoraClient } from '@solana/kora';
+ * import { address } from '@solana/kit';
+ *
+ * const client = await createKitKoraClient({
+ *   endpoint: 'https://kora.example.com',
+ *   rpcUrl: 'https://api.mainnet-beta.solana.com',
+ *   feeToken: address('EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'),
+ *   feePayerWallet: userSigner,
+ * });
+ *
+ * const result = await client.sendTransaction([myInstruction]);
+ * ```
+ */
+// TODO: Bundle support — the plan/execute pipeline currently handles single transactions only.
+// For Jito bundles, users must manually encode transactions and call `client.kora.signAndSendBundle()`.
+// A future `createKitKoraBundleClient` (or a bundle-aware executor plugin) could extend this to
+// plan multiple transaction messages and submit them as a single bundle.
+export async function createKitKoraClient(config) {
+    const koraClient = new KoraClient({
+        apiKey: config.apiKey,
+        getRecaptchaToken: config.getRecaptchaToken,
+        hmacSecret: config.hmacSecret,
+        rpcUrl: config.endpoint,
+    });
+    const { signer_address, payment_address } = await koraClient.getPayerSigner();
+    const paymentAddr = payment_address ? address(payment_address) : undefined;
+    const payerSigner = createNoopSigner(address(signer_address));
+    const computeBudgetIxs = buildComputeBudgetInstructions(config);
+    const solanaRpc = createSolanaRpc(config.rpcUrl);
+    const hasCuEstimation = config.computeUnitLimit === undefined;
+    const resolveProvisoryComputeUnitLimit = hasCuEstimation
+        ? estimateAndUpdateProvisoryComputeUnitLimitFactory(estimateComputeUnitLimitFactory({ rpc: solanaRpc }))
+        : undefined;
+    const payment = paymentAddr
+        ? await buildPlaceholderPaymentInstruction(config.feePayerWallet, paymentAddr, config.feeToken, config.tokenProgramId)
+        : undefined;
+    const koraTransactionPlanner = createKoraTransactionPlanner(payerSigner, computeBudgetIxs, payment?.instruction, hasCuEstimation);
+    const koraTransactionPlanExecutor = createKoraTransactionPlanExecutor(koraClient, config, payerSigner, payment
+        ? {
+            destinationTokenAccount: payment.destinationTokenAccount,
+            sourceTokenAccount: payment.sourceTokenAccount,
+        }
+        : undefined, resolveProvisoryComputeUnitLimit);
+    return createEmptyClient()
+        .use(rpc(config.rpcUrl))
+        .use(koraPlugin({
+        endpoint: config.endpoint,
+        koraClient,
+    }))
+        .use(payer(payerSigner))
+        .use(koraPaymentAddress(paymentAddr))
+        .use(transactionPlannerPlugin(koraTransactionPlanner))
+        .use(transactionPlanExecutorPlugin(koraTransactionPlanExecutor))
+        .use(planAndSendTransactions());
+}

package/dist/src/kit/payment.d.ts

@@ -0,0 +1,18 @@
+import { type Address, type Instruction, type TransactionSigner } from '@solana/kit';
+/** Plugin that adds a `paymentAddress` to the client. */
+export declare function koraPaymentAddress(paymentAddress?: Address): <T extends object>(client: T) => T & {
+    paymentAddress: Address | undefined;
+};
+/**
+ * Builds a placeholder payment instruction (amount=0) to reserve transaction space
+ * during planning. The executor later replaces it with the real fee amount.
+ */
+export declare function buildPlaceholderPaymentInstruction(feePayerWallet: TransactionSigner, paymentAddress: Address, feeToken: Address, tokenProgramId?: Address): Promise<{
+    destinationTokenAccount: Address;
+    instruction: Instruction;
+    sourceTokenAccount: Address;
+}>;
+/** Replaces the placeholder (amount=0) with the estimated fee amount. */
+export declare function updatePaymentInstructionAmount(instructions: readonly Instruction[], feePayerWallet: TransactionSigner, sourceTokenAccount: Address, destinationTokenAccount: Address, amount: bigint | number, tokenProgramId?: Address): Instruction[];
+/** Removes the placeholder payment instruction (used when fee is 0). */
+export declare function removePaymentInstruction(instructions: readonly Instruction[], sourceTokenAccount: Address, destinationTokenAccount: Address, feePayerWallet: TransactionSigner, tokenProgramId?: Address): Instruction[];

package/dist/src/kit/payment.js

@@ -0,0 +1,70 @@
+import { findAssociatedTokenPda, getTransferInstruction, parseTransferInstruction, TOKEN_PROGRAM_ADDRESS, TRANSFER_DISCRIMINATOR, } from '@solana-program/token';
+/** Plugin that adds a `paymentAddress` to the client. */
+export function koraPaymentAddress(paymentAddress) {
+    return (client) => ({
+        ...client,
+        paymentAddress,
+    });
+}
+/**
+ * Builds a placeholder payment instruction (amount=0) to reserve transaction space
+ * during planning. The executor later replaces it with the real fee amount.
+ */
+export async function buildPlaceholderPaymentInstruction(feePayerWallet, paymentAddress, feeToken, tokenProgramId) {
+    const tokenProgram = tokenProgramId ?? TOKEN_PROGRAM_ADDRESS;
+    const [sourceTokenAccount] = await findAssociatedTokenPda({
+        mint: feeToken,
+        owner: feePayerWallet.address,
+        tokenProgram,
+    });
+    const [destinationTokenAccount] = await findAssociatedTokenPda({
+        mint: feeToken,
+        owner: paymentAddress,
+        tokenProgram,
+    });
+    const instruction = getTransferInstruction({
+        amount: 0,
+        authority: feePayerWallet,
+        destination: destinationTokenAccount,
+        source: sourceTokenAccount,
+    }, { programAddress: tokenProgram });
+    return { destinationTokenAccount, instruction, sourceTokenAccount };
+}
+function isPlaceholderPaymentInstruction(ix, sourceTokenAccount, destinationTokenAccount, feePayerWallet, tokenProgramId) {
+    const tokenProgram = tokenProgramId ?? TOKEN_PROGRAM_ADDRESS;
+    if (ix.programAddress !== tokenProgram)
+        return false;
+    if (ix.data?.[0] !== TRANSFER_DISCRIMINATOR)
+        return false;
+    const parsed = parseTransferInstruction(ix);
+    return (parsed.accounts.source.address === sourceTokenAccount &&
+        parsed.accounts.destination.address === destinationTokenAccount &&
+        parsed.accounts.authority.address === feePayerWallet.address &&
+        parsed.data.amount === 0n);
+}
+/** Replaces the placeholder (amount=0) with the estimated fee amount. */
+export function updatePaymentInstructionAmount(instructions, feePayerWallet, sourceTokenAccount, destinationTokenAccount, amount, tokenProgramId) {
+    let replaced = false;
+    const result = instructions.map(ix => {
+        if (!isPlaceholderPaymentInstruction(ix, sourceTokenAccount, destinationTokenAccount, feePayerWallet, tokenProgramId)) {
+            return ix;
+        }
+        replaced = true;
+        const tokenProgram = tokenProgramId ?? TOKEN_PROGRAM_ADDRESS;
+        return getTransferInstruction({
+            amount,
+            authority: feePayerWallet,
+            destination: destinationTokenAccount,
+            source: sourceTokenAccount,
+        }, { programAddress: tokenProgram });
+    });
+    if (!replaced) {
+        throw new Error('Failed to update payment instruction: no matching placeholder transfer instruction found. ' +
+            'This is a Kora SDK internal error — the transaction message may have been modified between planning and execution.');
+    }
+    return result;
+}
+/** Removes the placeholder payment instruction (used when fee is 0). */
+export function removePaymentInstruction(instructions, sourceTokenAccount, destinationTokenAccount, feePayerWallet, tokenProgramId) {
+    return instructions.filter(ix => !isPlaceholderPaymentInstruction(ix, sourceTokenAccount, destinationTokenAccount, feePayerWallet, tokenProgramId));
+}

package/dist/src/kit/planner.d.ts

@@ -0,0 +1,4 @@
+import { type Instruction, type TransactionSigner } from '@solana/kit';
+import type { KoraKitClientConfig } from '../types/index.js';
+export declare function buildComputeBudgetInstructions(config: KoraKitClientConfig): Instruction[];
+export declare function createKoraTransactionPlanner(payerSigner: TransactionSigner, computeBudgetIxs: Instruction[], paymentInstruction: Instruction | undefined, hasCuEstimation: boolean): import("@solana/kit").TransactionPlanner;

package/dist/src/kit/planner.js

@@ -0,0 +1,23 @@
+import { appendTransactionMessageInstructions, createTransactionMessage, createTransactionPlanner, pipe, setTransactionMessageFeePayerSigner, } from '@solana/kit';
+import { fillProvisorySetComputeUnitLimitInstruction, getSetComputeUnitLimitInstruction, getSetComputeUnitPriceInstruction, } from '@solana-program/compute-budget';
+export function buildComputeBudgetInstructions(config) {
+    const instructions = [];
+    if (config.computeUnitLimit !== undefined) {
+        instructions.push(getSetComputeUnitLimitInstruction({ units: config.computeUnitLimit }));
+    }
+    if (config.computeUnitPrice !== undefined) {
+        instructions.push(getSetComputeUnitPriceInstruction({ microLamports: config.computeUnitPrice }));
+    }
+    return instructions;
+}
+export function createKoraTransactionPlanner(payerSigner, computeBudgetIxs, paymentInstruction, hasCuEstimation) {
+    return createTransactionPlanner({
+        createTransactionMessage: () => {
+            const allIxs = [...computeBudgetIxs];
+            if (paymentInstruction) {
+                allIxs.push(paymentInstruction);
+            }
+            return pipe(createTransactionMessage({ version: 0 }), m => setTransactionMessageFeePayerSigner(payerSigner, m), m => appendTransactionMessageInstructions(allIxs, m), m => (hasCuEstimation ? fillProvisorySetComputeUnitLimitInstruction(m) : m));
+        },
+    });
+}

package/dist/src/plugin.js

@@ -31,12 +31,13 @@ import { KoraClient } from './client.js';
  * ```
  */
 export function koraPlugin(config) {
-    const client = new KoraClient({
-        apiKey: config.apiKey,
-        getRecaptchaToken: config.getRecaptchaToken,
-        hmacSecret: config.hmacSecret,
-        rpcUrl: config.endpoint,
-    });
+    const client = config.koraClient ??
+        new KoraClient({
+            apiKey: config.apiKey,
+            getRecaptchaToken: config.getRecaptchaToken,
+            hmacSecret: config.hmacSecret,
+            rpcUrl: config.endpoint,
+        });
     return (c) => ({
         ...c,
         kora: {

package/dist/src/types/index.d.ts

@@ -1,4 +1,4 @@
-import { Instruction } from '@solana/kit';
+import { Instruction, type MicroLamports, type TransactionSigner } from '@solana/kit';
 /**
  * Request Types
  */
@@ -479,6 +479,7 @@ export interface KoraClientOptions {
  * Plugin Types - Kit-typed responses for the Kora plugin
  */
 import type { Address, Base64EncodedWireTransaction, Blockhash, Instruction as KitInstruction, Signature } from '@solana/kit';
+import { KoraClient } from '../client.js';
 /** Configuration options for the Kora Kit plugin */
 export interface KoraPluginConfig {
     /** Optional API key for authentication */
@@ -494,6 +495,8 @@ export interface KoraPluginConfig {
     getRecaptchaToken?: () => Promise<string> | string;
     /** Optional HMAC secret for signature-based authentication */
     hmacSecret?: string;
+    /** Existing Kora Client for reusing existing instance */
+    koraClient?: KoraClient;
 }
 /** Plugin response for getPayerSigner with Kit Address types */
 export interface KitPayerSignerResponse {
@@ -613,3 +616,20 @@ export interface KitValidationConfig {
     /** Token2022 configuration */
     token2022: Token2022Config;
 }
+/**
+ * Kit Client Types
+ */
+/** Configuration for {@link createKitKoraClient}. */
+export interface KoraKitClientConfig {
+    readonly apiKey?: string;
+    readonly computeUnitLimit?: number;
+    readonly computeUnitPrice?: MicroLamports;
+    readonly endpoint: string;
+    readonly feePayerWallet: TransactionSigner;
+    readonly feeToken: Address;
+    readonly getRecaptchaToken?: () => Promise<string> | string;
+    readonly hmacSecret?: string;
+    readonly rpcUrl: string;
+    readonly tokenProgramId?: Address;
+    readonly userId?: string;
+}

package/dist/test/integration.test.js

@@ -1,5 +1,7 @@
-import { appendTransactionMessageInstruction, compileTransaction, createTransactionMessage, getBase64Decoder, getBase64EncodedWireTransaction, getBase64Encoder, getTransactionDecoder, getTransactionEncoder, partiallySignTransaction, pipe, setTransactionMessageFeePayerSigner, setTransactionMessageLifetimeUsingBlockhash, } from '@solana/kit';
+import { address, appendTransactionMessageInstruction, compileTransaction, createTransactionMessage, getBase64Decoder, getBase64EncodedWireTransaction, getBase64Encoder, getTransactionDecoder, getTransactionEncoder, partiallySignTransaction, pipe, setTransactionMessageFeePayerSigner, setTransactionMessageLifetimeUsingBlockhash, } from '@solana/kit';
+import { getTransferSolInstruction } from '@solana-program/system';
 import { findAssociatedTokenPda, getTransferInstruction, TOKEN_PROGRAM_ADDRESS } from '@solana-program/token';
+import { createKitKoraClient } from '../src/index.js';
 import { runAuthenticationTests } from './auth-setup.js';
 import setupTestSuite from './setup.js';
 function transactionFromBase64(base64) {
@@ -54,6 +56,7 @@ async function buildTokenTransferTransaction(params) {
     return { blockhash: blockhash, transaction: base64Transaction };
 }
 const AUTH_ENABLED = process.env.ENABLE_AUTH === 'true';
+const FREE_PRICING = process.env.FREE_PRICING === 'true';
 const KORA_SIGNER_TYPE = process.env.KORA_SIGNER_TYPE || 'memory';
 describe(`KoraClient Integration Tests (${AUTH_ENABLED ? 'with auth' : 'without auth'} | signer type: ${KORA_SIGNER_TYPE})`, () => {
     let client;
@@ -172,9 +175,12 @@ describe(`KoraClient Integration Tests (${AUTH_ENABLED ? 'with auth' : 'without
             const fee = await client.estimateTransactionFee({ fee_token: usdcMint, transaction });
             expect(fee).toBeDefined();
             expect(typeof fee.fee_in_lamports).toBe('number');
-            expect(fee.fee_in_lamports).toBeGreaterThan(0);
+            expect(fee.fee_in_lamports).toBeGreaterThanOrEqual(0);
             expect(typeof fee.fee_in_token).toBe('number');
-            expect(fee.fee_in_token).toBeGreaterThan(0);
+            if (!FREE_PRICING) {
+                expect(fee.fee_in_lamports).toBeGreaterThan(0);
+                expect(fee.fee_in_token).toBeGreaterThan(0);
+            }
         });
         it('should sign transaction', async () => {
             const { transaction } = await buildTokenTransferTransaction({
@@ -246,7 +252,8 @@ describe(`KoraClient Integration Tests (${AUTH_ENABLED ? 'with auth' : 'without
             expect(original_transaction).toBe(transaction);
         });
     });
-    describe('Bundle Operations', () => {
+    // Bundle tests require bundle.enabled = true in the Kora config
+    (FREE_PRICING ? describe.skip : describe)('Bundle Operations', () => {
         it('should sign bundle of transactions', async () => {
             // Create two transfer transactions for the bundle
             const { transaction: tx1String } = await buildTokenTransferTransaction({
@@ -324,17 +331,37 @@ describe(`KoraClient Integration Tests (${AUTH_ENABLED ? 'with auth' : 'without
             await expect(client.estimateTransactionFee({ fee_token: usdcMint, transaction: 'invalid_transaction' })).rejects.toThrow();
         });
     });
-    describe('End-to-End Flows', () => {
-        it('should handle transfer and sign flow', async () => {
-            const { transaction } = await buildTokenTransferTransaction({
-                amount: 1000000n,
-                client,
-                destinationWallet: koraAddress,
-                mint: usdcMint,
-                sourceWallet: testWallet,
-            });
-            const signResult = await client.signTransaction({ transaction });
-            expect(signResult.signed_transaction).toBeDefined();
+    if (FREE_PRICING) {
+        describe('Kit Client (free pricing)', () => {
+            let freeClient;
+            beforeAll(async () => {
+                const koraRpcUrl = process.env.KORA_RPC_URL || 'http://127.0.0.1:8080';
+                freeClient = await createKitKoraClient({
+                    endpoint: koraRpcUrl,
+                    rpcUrl: process.env.SOLANA_RPC_URL || 'http://127.0.0.1:8899',
+                    feeToken: usdcMint,
+                    feePayerWallet: testWallet,
+                });
+            }, 30000);
+            it('should send transaction without payment instruction when fee is 0', async () => {
+                const ix = getTransferSolInstruction({
+                    source: testWallet,
+                    destination: address(koraAddress),
+                    amount: 1000,
+                });
+                const result = await freeClient.sendTransaction([ix]);
+                expect(result.status).toBe('successful');
+                expect(result.context.signature).toBeDefined();
+            }, 30000);
+            it('should strip placeholder from planned message when fee is 0', async () => {
+                const ix = getTransferSolInstruction({
+                    source: testWallet,
+                    destination: address(koraAddress),
+                    amount: 1000,
+                });
+                const result = await freeClient.sendTransaction([ix]);
+                expect(result.status).toBe('successful');
+            }, 30000);
         });
-    });
+    }
 });

package/dist/test/kit-client.test.d.ts

@@ -0,0 +1 @@
+export {};