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

package/README.md

@@ -1,8 +1,35 @@
 # Kora TypeScript SDK
 
-A TypeScript SDK for interacting with the Kora RPC server. This SDK provides a type-safe interface to all Kora RPC methods.
+A TypeScript SDK for interacting with the Kora RPC server. This SDK provides a type-safe interface to all Kora RPC methods (requires a Kora RPC server to be running).
 
-## Development
+
+## Installation
+
+```bash
+pnpm install @solana/kora
+```
+
+## Quick Start
+
+```typescript
+import { KoraClient } from '@solana/kora';
+
+// Initialize the client with your RPC endpoint
+const client = new KoraClient({ rpcUrl: 'http://localhost:8080' });
+
+// Example: Get Kora to sign a transaction
+const result = await client.signTransaction({
+  transaction: 'myBase64EncodedTransaction'
+});
+
+// Access the signed transaction (base64 encoded)
+console.log('Signed transaction:', result.signed_transaction);
+```
+
+**[→ API Reference](https://launch.solana.com/docs/kora/json-rpc-api)**
+**[→ Quick Start](https://launch.solana.com/docs/kora/getting-started/quick-start)**
+
+## Local Development
 
 ### Building from Source
 
@@ -33,28 +60,3 @@ pnpm test:ci:integration
 
 This will start a local test validator and run all tests.
 
-
-## Quick Start
-
-```typescript
-import { KoraClient } from '@solana/kora';
-
-// Initialize the client with your RPC endpoint
-const client = new KoraClient({ rpcUrl: 'http://localhost:8080' });
-
-// Example: Transfer tokens
-const result = await client.transferTransaction({
-  amount: 1000000, // 1 USDC (6 decimals)
-  token: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // USDC mint
-  source: "sourceAddress",
-  destination: "destinationAddress"
-});
-
-// Access the base64 encoded transaction, base64 encoded message, and parsed instructions directly
-console.log('Transaction:', result.transaction);
-console.log('Message:', result.message);
-console.log('Instructions:', result.instructions);
-```
-
-**[→ API Reference](https://launch.solana.com/docs/kora/json-rpc-api)**
-**[→ Quick Start](https://launch.solana.com/docs/kora/getting-started/quick-start)**

package/dist/src/client.d.ts

@@ -23,14 +23,16 @@ export declare class KoraClient {
     private rpcUrl;
     private apiKey?;
     private hmacSecret?;
+    private getRecaptchaToken?;
     /**
      * Creates a new Kora client instance.
      * @param options - Client configuration options
      * @param options.rpcUrl - The Kora RPC server URL
      * @param options.apiKey - Optional API key for authentication
      * @param options.hmacSecret - Optional HMAC secret for signature-based authentication
+     * @param options.getRecaptchaToken - Optional callback to get reCAPTCHA token for bot protection
      */
-    constructor({ rpcUrl, apiKey, hmacSecret }: KoraClientOptions);
+    constructor({ rpcUrl, apiKey, hmacSecret, getRecaptchaToken }: KoraClientOptions);
     private getHmacSignature;
     private getHeaders;
     private rpcRequest;

package/dist/src/client.js

@@ -25,17 +25,20 @@ export class KoraClient {
     rpcUrl;
     apiKey;
     hmacSecret;
+    getRecaptchaToken;
     /**
      * Creates a new Kora client instance.
      * @param options - Client configuration options
      * @param options.rpcUrl - The Kora RPC server URL
      * @param options.apiKey - Optional API key for authentication
      * @param options.hmacSecret - Optional HMAC secret for signature-based authentication
+     * @param options.getRecaptchaToken - Optional callback to get reCAPTCHA token for bot protection
      */
-    constructor({ rpcUrl, apiKey, hmacSecret }) {
+    constructor({ rpcUrl, apiKey, hmacSecret, getRecaptchaToken }) {
         this.rpcUrl = rpcUrl;
         this.apiKey = apiKey;
         this.hmacSecret = hmacSecret;
+        this.getRecaptchaToken = getRecaptchaToken;
     }
     getHmacSignature({ timestamp, body }) {
         if (!this.hmacSecret) {
@@ -44,7 +47,7 @@ export class KoraClient {
         const message = timestamp + body;
         return crypto.createHmac('sha256', this.hmacSecret).update(message).digest('hex');
     }
-    getHeaders({ body }) {
+    async getHeaders({ body }) {
         const headers = {};
         if (this.apiKey) {
             headers['x-api-key'] = this.apiKey;
@@ -55,6 +58,10 @@ export class KoraClient {
             headers['x-timestamp'] = timestamp;
             headers['x-hmac-signature'] = signature;
         }
+        if (this.getRecaptchaToken) {
+            const token = await Promise.resolve(this.getRecaptchaToken());
+            headers['x-recaptcha-token'] = token;
+        }
         return headers;
     }
     async rpcRequest(method, params) {
@@ -64,7 +71,7 @@ export class KoraClient {
             method,
             params,
         });
-        const headers = this.getHeaders({ body });
+        const headers = await this.getHeaders({ body });
         const response = await fetch(this.rpcUrl, {
             body,
             headers: { ...headers, 'Content-Type': 'application/json' },

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,11 +31,13 @@ import { KoraClient } from './client.js';
  * ```
  */
 export function koraPlugin(config) {
-    const client = new KoraClient({
-        apiKey: config.apiKey,
-        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
  */
@@ -452,6 +452,8 @@ export interface AuthenticationHeaders {
     'x-api-key'?: string;
     /** HMAC SHA256 signature of timestamp + body */
     'x-hmac-signature'?: string;
+    /** reCAPTCHA v3 token for bot protection */
+    'x-recaptcha-token'?: string;
     /** Unix timestamp for HMAC authentication */
     'x-timestamp'?: string;
 }
@@ -461,6 +463,13 @@ export interface AuthenticationHeaders {
 export interface KoraClientOptions {
     /** Optional API key for authentication */
     apiKey?: string;
+    /**
+     * Optional callback to get a reCAPTCHA v3 token for bot protection.
+     * Called for every request when provided; server determines which methods require it.
+     * @example Browser: `() => grecaptcha.execute('site-key', { action: 'sign' })`
+     * @example Testing: `() => 'test-token'`
+     */
+    getRecaptchaToken?: () => Promise<string> | string;
     /** Optional HMAC secret for signature-based authentication */
     hmacSecret?: string;
     /** URL of the Kora RPC server */
@@ -470,14 +479,24 @@ 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 */
     apiKey?: string;
     /** Kora RPC endpoint URL */
     endpoint: string;
+    /**
+     * Optional callback to get a reCAPTCHA v3 token for bot protection.
+     * Called for every request when provided; server determines which methods require it.
+     * @example Browser: `() => grecaptcha.execute('site-key', { action: 'sign' })`
+     * @example Testing: `() => 'test-token'`
+     */
+    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 {
@@ -597,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;
+}