@solana/kora 0.2.1 → 0.3.0-beta.2

package/dist/src/error.js

@@ -0,0 +1,54 @@
+/**
+ * Stable numeric error codes for RPC responses following JSON-RPC 2.0 spec (-32000 to -32099 for server errors).
+ */
+export var KoraErrorCode;
+(function (KoraErrorCode) {
+    // Validation errors (-32000 to -32019)
+    KoraErrorCode[KoraErrorCode["InvalidTransaction"] = -32000] = "InvalidTransaction";
+    KoraErrorCode[KoraErrorCode["ValidationError"] = -32001] = "ValidationError";
+    KoraErrorCode[KoraErrorCode["UnsupportedFeeToken"] = -32002] = "UnsupportedFeeToken";
+    KoraErrorCode[KoraErrorCode["InsufficientFunds"] = -32003] = "InsufficientFunds";
+    KoraErrorCode[KoraErrorCode["InvalidRequest"] = -32004] = "InvalidRequest";
+    KoraErrorCode[KoraErrorCode["FeeEstimationFailed"] = -32005] = "FeeEstimationFailed";
+    KoraErrorCode[KoraErrorCode["TransactionExecutionFailed"] = -32006] = "TransactionExecutionFailed";
+    // Signing errors (-32020 to -32029)
+    KoraErrorCode[KoraErrorCode["SigningError"] = -32020] = "SigningError";
+    // Auth / Rate limiting (-32030 to -32039)
+    KoraErrorCode[KoraErrorCode["RateLimitExceeded"] = -32030] = "RateLimitExceeded";
+    KoraErrorCode[KoraErrorCode["UsageLimitExceeded"] = -32031] = "UsageLimitExceeded";
+    KoraErrorCode[KoraErrorCode["Unauthorized"] = -32032] = "Unauthorized";
+    // Token / Swap (-32040 to -32049)
+    KoraErrorCode[KoraErrorCode["SwapError"] = -32040] = "SwapError";
+    KoraErrorCode[KoraErrorCode["TokenOperationError"] = -32041] = "TokenOperationError";
+    // Account errors (-32050 to -32059)
+    KoraErrorCode[KoraErrorCode["AccountNotFound"] = -32050] = "AccountNotFound";
+    // External services (-32060 to -32069)
+    KoraErrorCode[KoraErrorCode["JitoError"] = -32060] = "JitoError";
+    KoraErrorCode[KoraErrorCode["RecaptchaError"] = -32061] = "RecaptchaError";
+    // Internal errors (-32090 to -32099)
+    KoraErrorCode[KoraErrorCode["InternalServerError"] = -32090] = "InternalServerError";
+    KoraErrorCode[KoraErrorCode["ConfigError"] = -32091] = "ConfigError";
+    KoraErrorCode[KoraErrorCode["SerializationError"] = -32092] = "SerializationError";
+    KoraErrorCode[KoraErrorCode["RpcError"] = -32093] = "RpcError";
+})(KoraErrorCode || (KoraErrorCode = {}));
+/**
+ * Represents a structured error returned by the Kora paymaster service.
+ */
+export class KoraError extends Error {
+    /** The stable numeric error code */
+    code;
+    /** Optional structured data about the error */
+    data;
+    constructor(code, message, data) {
+        const finalCode = code ?? -32603;
+        const finalMessage = message ?? 'Unknown error';
+        super(`Kora Error ${finalCode}: ${finalMessage}`);
+        this.name = 'KoraError';
+        this.code = finalCode;
+        this.data = data;
+        // Ensure proper stack trace in environments that support Error.captureStackTrace
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, KoraError);
+        }
+    }
+}

package/dist/src/index.d.ts

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

package/dist/src/index.js

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

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

@@ -1,7 +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: {
+import type { KoraBundleConfig } from '../types/index.js';
+export declare function createKoraTransactionPlanExecutor(koraClient: KoraClient, config: KoraBundleConfig, userSigner: TransactionSigner, 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

@@ -1,6 +1,11 @@
 import { appendTransactionMessageInstructions, blockhash, createTransactionMessage, createTransactionPlanExecutor, getBase64EncodedWireTransaction, getBase64Encoder, getSignatureFromTransaction, getTransactionDecoder, partiallySignTransactionMessageWithSigners, pipe, setTransactionMessageFeePayerSigner, setTransactionMessageLifetimeUsingBlockhash, signature, } from '@solana/kit';
 import { removePaymentInstruction, updatePaymentInstructionAmount } from './payment.js';
-export function createKoraTransactionPlanExecutor(koraClient, config, payerSigner, payment, resolveProvisoryComputeUnitLimit) {
+// 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, userSigner, payerSigner, payment, resolveProvisoryComputeUnitLimit) {
     return createTransactionPlanExecutor({
         async executeTransactionMessage(_context, transactionMessage) {
             // Kora manages blockhash validity; set max height to avoid premature client-side expiry checks
@@ -20,8 +25,13 @@ export function createKoraTransactionPlanExecutor(koraClient, config, payerSigne
                     fee_token: config.feeToken,
                     transaction: prePaymentTx,
                 });
-                if (fee_in_token < 0) {
-                    throw new Error(`Kora fee estimation returned a negative fee (${fee_in_token}). This indicates a server-side error.`);
+                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
@@ -31,9 +41,9 @@ export function createKoraTransactionPlanExecutor(koraClient, config, payerSigne
                         '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 = fee_in_token > 0
-                    ? updatePaymentInstructionAmount(currentIxs, config.feePayerWallet, sourceTokenAccount, destinationTokenAccount, fee_in_token, config.tokenProgramId)
-                    : removePaymentInstruction(currentIxs, sourceTokenAccount, destinationTokenAccount, config.feePayerWallet, config.tokenProgramId);
+                const finalIxs = feeInToken > 0
+                    ? updatePaymentInstructionAmount(currentIxs, userSigner, sourceTokenAccount, destinationTokenAccount, feeInToken, config.tokenProgramId)
+                    : removePaymentInstruction(currentIxs, sourceTokenAccount, destinationTokenAccount, userSigner, config.tokenProgramId);
                 const resolvedMsg = pipe(createTransactionMessage({ version: 0 }), m => setTransactionMessageFeePayerSigner(payerSigner, m), m => setTransactionMessageLifetimeUsingBlockhash({
                     blockhash: blockhash(bh),
                     lastValidBlockHeight: BigInt(Number.MAX_SAFE_INTEGER),
@@ -43,7 +53,10 @@ export function createKoraTransactionPlanExecutor(koraClient, config, payerSigne
             else {
                 finalTx = prePaymentTx;
             }
-            const result = await koraClient.signAndSendTransaction({ transaction: finalTx });
+            const result = await koraClient.signAndSendTransaction({
+                transaction: finalTx,
+                user_id: config.userId,
+            });
             if (result.signature) {
                 return signature(result.signature);
             }

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

@@ -1,50 +1,110 @@
-import type { KoraKitClientConfig } from '../types/index.js';
-/** The type returned by {@link createKitKoraClient}. */
-export type KoraKitClient = Awaited<ReturnType<typeof createKitKoraClient>>;
+import { type ClientWithIdentity } from '@solana/kit';
+import type { KoraBundleConfig, KoraKitClientConfig } from '../types/index.js';
 /**
- * Creates a Kora Kit client composed from Kit plugins.
+ * Kora bundle plugin.
+ *
+ * Composes RPC + payer + Kora RPC methods + transaction planning/execution into a single
+ * plugin that mirrors the shape of `solanaRpc` from `@solana/kit-plugin-rpc`.
  *
- * The returned client satisfies `ClientWithPayer`, `ClientWithTransactionPlanning`,
- * and `ClientWithTransactionSending`, making it composable with Kit program plugins.
+ * The caller's signer is read from `client.identity` — install `identity()` (or `signer()`)
+ * from `@solana/kit-plugin-signer` before this plugin. The fee payer (Kora's address) is
+ * fetched from the Kora node and installed internally as a noop signer, overriding any
+ * `payer` already on the client.
  *
  * @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]);
+ * ```ts
+ * import { createClient } from '@solana/kit';
+ * import { identity } from '@solana/kit-plugin-signer';
+ * import { kora } from '@solana/kora';
+ *
+ * const client = await createClient()
+ *   .use(identity(userSigner))
+ *   .use(kora({
+ *     endpoint: 'https://kora.example.com',
+ *     rpcUrl: 'https://api.mainnet-beta.solana.com',
+ *     feeToken: address('EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'),
+ *   }));
+ *
+ * const signature = await client.sendTransaction([myInstruction]);
  * ```
  */
-export declare function createKitKoraClient(config: KoraKitClientConfig): Promise<import("@solana/kit").Client<import("@solana/kit").ClientWithTransactionPlanning & import("@solana/kit").ClientWithTransactionSending & object & {
+export declare function kora(config: KoraBundleConfig): <T extends ClientWithIdentity>(client: T) => Promise<Omit<Omit<Omit<Omit<Omit<T, "payer"> & {
+    payer: import("@solana/kit").NoopSigner<string>;
+}, "rpc"> & {
     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>;
-        transferTransaction(request: import("../types/index.js").TransferTransactionRequest): Promise<import("../types/index.js").KitTransferTransactionResponse>;
     };
-} & {
-    payer: import("@solana/kit").TransactionSigner;
 } & {
     paymentAddress: import("@solana/kit").Address | undefined;
-} & {
+}, "transactionPlanner"> & {
     transactionPlanner: import("@solana/kit").TransactionPlanner;
+}, "transactionPlanExecutor"> & {
+    transactionPlanExecutor: import("@solana/kit").TransactionPlanExecutor;
+}, keyof import("@solana/kit").ClientWithTransactionPlanning | keyof import("@solana/kit").ClientWithTransactionSending> & import("@solana/kit").ClientWithTransactionPlanning & import("@solana/kit").ClientWithTransactionSending>;
+/**
+ * The type returned by {@link createKitKoraClient}.
+ *
+ * @deprecated Derive the client type from your own `createClient().use(...).use(kora(...))`
+ * composition instead. Will be removed in 0.4.0.
+ */
+export type KoraKitClient = Awaited<ReturnType<typeof createKitKoraClient>>;
+/**
+ * Creates a Kora Kit client composed from Kit plugins.
+ *
+ * @beta This API is experimental and may change in future releases.
+ *
+ * @deprecated Compose with the {@link kora} plugin instead:
+ * ```ts
+ * import { createClient } from '@solana/kit';
+ * import { identity } from '@solana/kit-plugin-signer';
+ * import { kora } from '@solana/kora';
+ *
+ * const client = await createClient()
+ *   .use(identity(userSigner))
+ *   .use(kora({ endpoint, rpcUrl, feeToken }));
+ * ```
+ * Will be removed in 0.4.0.
+ */
+export declare function createKitKoraClient(config: KoraKitClientConfig): Promise<import("@solana/kit").Client<Omit<Omit<Omit<Omit<Omit<Omit<object, "identity"> & {
+    identity: import("@solana/kit").TransactionSigner;
+}, "payer"> & {
+    payer: import("@solana/kit").NoopSigner<string>;
+}, "rpc"> & {
+    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>;
 } & {
+    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>;
+    };
+} & {
+    paymentAddress: import("@solana/kit").Address | undefined;
+}, "transactionPlanner"> & {
+    transactionPlanner: import("@solana/kit").TransactionPlanner;
+}, "transactionPlanExecutor"> & {
     transactionPlanExecutor: import("@solana/kit").TransactionPlanExecutor;
-}>>;
+}, keyof import("@solana/kit").ClientWithTransactionPlanning | keyof import("@solana/kit").ClientWithTransactionSending> & import("@solana/kit").ClientWithTransactionPlanning & import("@solana/kit").ClientWithTransactionSending>>;

package/dist/src/kit/index.js

@@ -1,67 +1,97 @@
-import { address, createEmptyClient, createNoopSigner, createSolanaRpc } from '@solana/kit';
+import { address, createClient, createNoopSigner, createSolanaRpc, pipe } 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 { solanaRpcConnection } from '@solana/kit-plugin-rpc';
+import { identity, payer } from '@solana/kit-plugin-signer';
 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';
-import { koraPlugin } from './plugin.js';
 /**
- * Creates a Kora Kit client composed from Kit plugins.
+ * Kora bundle plugin.
+ *
+ * Composes RPC + payer + Kora RPC methods + transaction planning/execution into a single
+ * plugin that mirrors the shape of `solanaRpc` from `@solana/kit-plugin-rpc`.
  *
- * The returned client satisfies `ClientWithPayer`, `ClientWithTransactionPlanning`,
- * and `ClientWithTransactionSending`, making it composable with Kit program plugins.
+ * The caller's signer is read from `client.identity` — install `identity()` (or `signer()`)
+ * from `@solana/kit-plugin-signer` before this plugin. The fee payer (Kora's address) is
+ * fetched from the Kora node and installed internally as a noop signer, overriding any
+ * `payer` already on the client.
  *
  * @beta This API is experimental and may change in future releases.
  *
  * @example
- * ```typescript
- * import { createKitKoraClient } from '@solana/kora';
- * import { address } from '@solana/kit';
+ * ```ts
+ * import { createClient } from '@solana/kit';
+ * import { identity } from '@solana/kit-plugin-signer';
+ * import { kora } from '@solana/kora';
+ *
+ * const client = await createClient()
+ *   .use(identity(userSigner))
+ *   .use(kora({
+ *     endpoint: 'https://kora.example.com',
+ *     rpcUrl: 'https://api.mainnet-beta.solana.com',
+ *     feeToken: address('EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'),
+ *   }));
+ *
+ * const signature = await client.sendTransaction([myInstruction]);
+ * ```
+ */
+export function kora(config) {
+    return async (client) => {
+        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 userSigner = client.identity;
+        const payment = paymentAddr
+            ? await buildPlaceholderPaymentInstruction(userSigner, paymentAddr, config.feeToken, config.tokenProgramId)
+            : undefined;
+        const koraTransactionPlanner = createKoraTransactionPlanner(payerSigner, computeBudgetIxs, payment?.instruction, hasCuEstimation);
+        const koraTransactionPlanExecutor = createKoraTransactionPlanExecutor(koraClient, config, userSigner, payerSigner, payment
+            ? {
+                destinationTokenAccount: payment.destinationTokenAccount,
+                sourceTokenAccount: payment.sourceTokenAccount,
+            }
+            : undefined, resolveProvisoryComputeUnitLimit);
+        return pipe(client, payer(payerSigner), solanaRpcConnection(config.rpcUrl), koraPlugin({
+            endpoint: config.endpoint,
+            koraClient,
+        }), koraPaymentAddress(paymentAddr), transactionPlannerPlugin(koraTransactionPlanner), transactionPlanExecutorPlugin(koraTransactionPlanExecutor), planAndSendTransactions());
+    };
+}
+/**
+ * Creates a Kora Kit client composed from Kit plugins.
+ *
+ * @beta This API is experimental and may change in future releases.
  *
- * const client = await createKitKoraClient({
- *   endpoint: 'https://kora.example.com',
- *   rpcUrl: 'https://api.mainnet-beta.solana.com',
- *   feeToken: address('EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'),
- *   feePayerWallet: userSigner,
- * });
+ * @deprecated Compose with the {@link kora} plugin instead:
+ * ```ts
+ * import { createClient } from '@solana/kit';
+ * import { identity } from '@solana/kit-plugin-signer';
+ * import { kora } from '@solana/kora';
  *
- * const result = await client.sendTransaction([myInstruction]);
+ * const client = await createClient()
+ *   .use(identity(userSigner))
+ *   .use(kora({ endpoint, rpcUrl, feeToken }));
  * ```
+ * Will be removed in 0.4.0.
  */
+// 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()`.
 export async function createKitKoraClient(config) {
-    const koraClient = new KoraClient({
-        apiKey: config.apiKey,
-        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({ apiKey: config.apiKey, endpoint: config.endpoint, hmacSecret: config.hmacSecret }))
-        .use(payer(payerSigner))
-        .use(koraPaymentAddress(paymentAddr))
-        .use(transactionPlannerPlugin(koraTransactionPlanner))
-        .use(transactionPlanExecutorPlugin(koraTransactionPlanExecutor))
-        .use(planAndSendTransactions());
+    const { feePayerWallet, ...bundleConfig } = config;
+    return await createClient().use(identity(feePayerWallet)).use(kora(bundleConfig));
 }

package/dist/src/kit/payment.js

@@ -27,7 +27,7 @@ export async function buildPlaceholderPaymentInstruction(feePayerWallet, payment
         authority: feePayerWallet,
         destination: destinationTokenAccount,
         source: sourceTokenAccount,
-    });
+    }, { programAddress: tokenProgram });
     return { destinationTokenAccount, instruction, sourceTokenAccount };
 }
 function isPlaceholderPaymentInstruction(ix, sourceTokenAccount, destinationTokenAccount, feePayerWallet, tokenProgramId) {
@@ -50,12 +50,13 @@ export function updatePaymentInstructionAmount(instructions, feePayerWallet, sou
             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. ' +

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

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

package/dist/src/plugin.d.ts

@@ -0,0 +1,85 @@
+import type { EstimateBundleFeeRequest, EstimateTransactionFeeRequest, GetPaymentInstructionRequest, GetVersionResponse, KitBlockhashResponse, KitConfigResponse, KitEstimateBundleFeeResponse, KitEstimateFeeResponse, KitPayerSignerResponse, KitPaymentInstructionResponse, KitSignAndSendBundleResponse, KitSignAndSendTransactionResponse, KitSignBundleResponse, KitSignTransactionResponse, KitSupportedTokensResponse, KoraPluginConfig, SignAndSendBundleRequest, SignAndSendTransactionRequest, SignBundleRequest, SignTransactionRequest } from './types/index.js';
+/**
+ * Creates a Kora Kit plugin that adds Kora paymaster functionality to a Kit client.
+ *
+ * The plugin exposes all Kora RPC methods with Kit-typed responses (Address, Blockhash).
+ *
+ * **Note:** The plugin pattern with `createClient().use()` requires `@solana/kit` v6.8.0+.
+ * For older kit versions, use `KoraClient` directly instead.
+ *
+ * @param config - Plugin configuration
+ * @param config.endpoint - Kora RPC endpoint URL
+ * @param config.apiKey - Optional API key for authentication
+ * @param config.hmacSecret - Optional HMAC secret for signature-based authentication
+ * @returns A Kit plugin function that adds `.kora` to the client
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@solana/kit';
+ * import { koraPlugin } from '@solana/kora';
+ *
+ * const client = createClient()
+ *   .use(koraPlugin({ endpoint: 'https://kora.example.com' }));
+ *
+ * // All responses have Kit-typed fields
+ * const config = await client.kora.getConfig();
+ * // config.fee_payers is Address[] not string[]
+ *
+ * const { signer_pubkey } = await client.kora.signTransaction({ transaction: tx });
+ * // signer_pubkey is Address not string
+ * ```
+ */
+export declare function koraPlugin(config: KoraPluginConfig): <T extends object>(c: T) => T & {
+    kora: {
+        /**
+         * Estimates the bundle fee with Kit-typed addresses.
+         */
+        estimateBundleFee(request: EstimateBundleFeeRequest): Promise<KitEstimateBundleFeeResponse>;
+        /**
+         * Estimates the transaction fee with Kit-typed addresses.
+         */
+        estimateTransactionFee(request: EstimateTransactionFeeRequest): Promise<KitEstimateFeeResponse>;
+        /**
+         * Gets the latest blockhash with Kit Blockhash type.
+         */
+        getBlockhash(): Promise<KitBlockhashResponse>;
+        /**
+         * Retrieves the current Kora server configuration with Kit-typed addresses.
+         */
+        getConfig(): Promise<KitConfigResponse>;
+        /**
+         * Retrieves the payer signer and payment destination with Kit-typed addresses.
+         */
+        getPayerSigner(): Promise<KitPayerSignerResponse>;
+        /**
+         * Creates a payment instruction with Kit-typed response.
+         */
+        getPaymentInstruction(request: GetPaymentInstructionRequest): Promise<KitPaymentInstructionResponse>;
+        /**
+         * Retrieves the list of tokens supported for fee payment with Kit-typed addresses.
+         */
+        getSupportedTokens(): Promise<KitSupportedTokensResponse>;
+        /**
+         * Gets the version of the Kora server.
+         */
+        getVersion(): Promise<GetVersionResponse>;
+        /**
+         * Signs and sends a bundle of transactions via Jito with Kit-typed response.
+         */
+        signAndSendBundle(request: SignAndSendBundleRequest): Promise<KitSignAndSendBundleResponse>;
+        /**
+         * Signs and sends a transaction with Kit-typed response.
+         */
+        signAndSendTransaction(request: SignAndSendTransactionRequest): Promise<KitSignAndSendTransactionResponse>;
+        /**
+         * Signs a bundle of transactions with Kit-typed response.
+         */
+        signBundle(request: SignBundleRequest): Promise<KitSignBundleResponse>;
+        /**
+         * Signs a transaction with Kit-typed response.
+         */
+        signTransaction(request: SignTransactionRequest): Promise<KitSignTransactionResponse>;
+    };
+};
+/** Type representing the Kora API exposed by the plugin */
+export type KoraApi = ReturnType<ReturnType<typeof koraPlugin>>['kora'];