@solana/kora 0.2.0 → 0.3.0-beta.0

package/dist/src/kit/index.js

@@ -4,10 +4,10 @@ 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';
-import { koraPlugin } from './plugin.js';
 /**
  * Creates a Kora Kit client composed from Kit plugins.
  *
@@ -31,9 +31,14 @@ import { koraPlugin } from './plugin.js';
  * 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,
     });
@@ -58,7 +63,10 @@ export async function createKitKoraClient(config) {
         : undefined, resolveProvisoryComputeUnitLimit);
     return createEmptyClient()
         .use(rpc(config.rpcUrl))
-        .use(koraPlugin({ apiKey: config.apiKey, endpoint: config.endpoint, hmacSecret: config.hmacSecret }))
+        .use(koraPlugin({
+        endpoint: config.endpoint,
+        koraClient,
+    }))
         .use(payer(payerSigner))
         .use(koraPaymentAddress(paymentAddr))
         .use(transactionPlannerPlugin(koraTransactionPlanner))

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/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 `createEmptyClient().use()` requires `@solana/kit` v5.4.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 { createEmptyClient } from '@solana/kit';
+ * import { koraPlugin } from '@solana/kora';
+ *
+ * const client = createEmptyClient()
+ *   .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'];

package/dist/src/{kit/plugin.js → plugin.js}

@@ -1,29 +1,61 @@
 import { address, blockhash, signature } from '@solana/kit';
-import { KoraClient } from '../client.js';
+import { KoraClient } from './client.js';
 /**
- * Kit plugin that adds `.kora` namespace with all Kora RPC methods.
- * Responses are cast to Kit types (Address, Blockhash, Signature).
+ * Creates a Kora Kit plugin that adds Kora paymaster functionality to a Kit client.
  *
- * Requires `@solana/kit` v5.4.0+ for the `createEmptyClient().use()` pattern.
+ * The plugin exposes all Kora RPC methods with Kit-typed responses (Address, Blockhash).
+ *
+ * **Note:** The plugin pattern with `createEmptyClient().use()` requires `@solana/kit` v5.4.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 { createEmptyClient } from '@solana/kit';
+ * import { koraPlugin } from '@solana/kora';
+ *
  * const client = createEmptyClient()
  *   .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 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: {
+            /**
+             * Estimates the bundle fee with Kit-typed addresses.
+             */
+            async estimateBundleFee(request) {
+                const result = await client.estimateBundleFee(request);
+                return {
+                    fee_in_lamports: result.fee_in_lamports,
+                    fee_in_token: result.fee_in_token,
+                    payment_address: address(result.payment_address),
+                    signer_pubkey: address(result.signer_pubkey),
+                };
+            },
+            /**
+             * Estimates the transaction fee with Kit-typed addresses.
+             */
             async estimateTransactionFee(request) {
                 const result = await client.estimateTransactionFee(request);
                 return {
@@ -33,12 +65,18 @@ export function koraPlugin(config) {
                     signer_pubkey: address(result.signer_pubkey),
                 };
             },
+            /**
+             * Gets the latest blockhash with Kit Blockhash type.
+             */
             async getBlockhash() {
                 const result = await client.getBlockhash();
                 return {
                     blockhash: blockhash(result.blockhash),
                 };
             },
+            /**
+             * Retrieves the current Kora server configuration with Kit-typed addresses.
+             */
             async getConfig() {
                 const result = await client.getConfig();
                 return {
@@ -53,6 +91,9 @@ export function koraPlugin(config) {
                     },
                 };
             },
+            /**
+             * Retrieves the payer signer and payment destination with Kit-typed addresses.
+             */
             async getPayerSigner() {
                 const result = await client.getPayerSigner();
                 return {
@@ -60,6 +101,9 @@ export function koraPlugin(config) {
                     signer_address: address(result.signer_address),
                 };
             },
+            /**
+             * Creates a payment instruction with Kit-typed response.
+             */
             async getPaymentInstruction(request) {
                 const result = await client.getPaymentInstruction(request);
                 return {
@@ -71,12 +115,35 @@ export function koraPlugin(config) {
                     signer_address: address(result.signer_address),
                 };
             },
+            /**
+             * Retrieves the list of tokens supported for fee payment with Kit-typed addresses.
+             */
             async getSupportedTokens() {
                 const result = await client.getSupportedTokens();
                 return {
                     tokens: result.tokens.map(addr => address(addr)),
                 };
             },
+            /**
+             * Gets the version of the Kora server.
+             */
+            async getVersion() {
+                return await client.getVersion();
+            },
+            /**
+             * Signs and sends a bundle of transactions via Jito with Kit-typed response.
+             */
+            async signAndSendBundle(request) {
+                const result = await client.signAndSendBundle(request);
+                return {
+                    bundle_uuid: result.bundle_uuid,
+                    signed_transactions: result.signed_transactions,
+                    signer_pubkey: address(result.signer_pubkey),
+                };
+            },
+            /**
+             * Signs and sends a transaction with Kit-typed response.
+             */
             async signAndSendTransaction(request) {
                 const result = await client.signAndSendTransaction(request);
                 return {
@@ -85,21 +152,24 @@ export function koraPlugin(config) {
                     signer_pubkey: address(result.signer_pubkey),
                 };
             },
-            async signTransaction(request) {
-                const result = await client.signTransaction(request);
+            /**
+             * Signs a bundle of transactions with Kit-typed response.
+             */
+            async signBundle(request) {
+                const result = await client.signBundle(request);
                 return {
-                    signed_transaction: result.signed_transaction,
+                    signed_transactions: result.signed_transactions,
                     signer_pubkey: address(result.signer_pubkey),
                 };
             },
-            async transferTransaction(request) {
-                const result = await client.transferTransaction(request);
+            /**
+             * Signs a transaction with Kit-typed response.
+             */
+            async signTransaction(request) {
+                const result = await client.signTransaction(request);
                 return {
-                    blockhash: blockhash(result.blockhash),
-                    instructions: result.instructions,
-                    message: result.message,
+                    signed_transaction: result.signed_transaction,
                     signer_pubkey: address(result.signer_pubkey),
-                    transaction: result.transaction,
                 };
             },
         },