@solana/kora 0.2.0-beta.4 → 0.2.0

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

@@ -0,0 +1,50 @@
+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: {
+        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>;
+        signAndSendTransaction(request: import("../types/index.js").SignAndSendTransactionRequest): Promise<import("../types/index.js").KitSignAndSendTransactionResponse>;
+        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: import("@solana/kit").TransactionPlanner;
+} & {
+    transactionPlanExecutor: import("@solana/kit").TransactionPlanExecutor;
+}>>;

package/dist/src/kit/index.js

@@ -0,0 +1,67 @@
+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 { 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.
+ *
+ * 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 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());
+}

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,69 @@
+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,
+    });
+    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;
+        return getTransferInstruction({
+            amount,
+            authority: feePayerWallet,
+            destination: destinationTokenAccount,
+            source: sourceTokenAccount,
+        });
+    });
+    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/kit/plugin.d.ts

@@ -0,0 +1,31 @@
+import type { EstimateTransactionFeeRequest, GetPaymentInstructionRequest, KitBlockhashResponse, KitConfigResponse, KitEstimateFeeResponse, KitPayerSignerResponse, KitPaymentInstructionResponse, KitSignAndSendTransactionResponse, KitSignTransactionResponse, KitSupportedTokensResponse, KitTransferTransactionResponse, KoraPluginConfig, SignAndSendTransactionRequest, SignTransactionRequest, TransferTransactionRequest } from '../types/index.js';
+/**
+ * Kit plugin that adds `.kora` namespace with all Kora RPC methods.
+ * Responses are cast to Kit types (Address, Blockhash, Signature).
+ *
+ * Requires `@solana/kit` v5.4.0+ for the `createEmptyClient().use()` pattern.
+ *
+ * @example
+ * ```typescript
+ * const client = createEmptyClient()
+ *   .use(koraPlugin({ endpoint: 'https://kora.example.com' }));
+ *
+ * const config = await client.kora.getConfig();
+ * const { signer_pubkey } = await client.kora.signTransaction({ transaction: tx });
+ * ```
+ */
+export declare function koraPlugin(config: KoraPluginConfig): <T extends object>(c: T) => T & {
+    kora: {
+        estimateTransactionFee(request: EstimateTransactionFeeRequest): Promise<KitEstimateFeeResponse>;
+        getBlockhash(): Promise<KitBlockhashResponse>;
+        getConfig(): Promise<KitConfigResponse>;
+        getPayerSigner(): Promise<KitPayerSignerResponse>;
+        getPaymentInstruction(request: GetPaymentInstructionRequest): Promise<KitPaymentInstructionResponse>;
+        getSupportedTokens(): Promise<KitSupportedTokensResponse>;
+        signAndSendTransaction(request: SignAndSendTransactionRequest): Promise<KitSignAndSendTransactionResponse>;
+        signTransaction(request: SignTransactionRequest): Promise<KitSignTransactionResponse>;
+        transferTransaction(request: TransferTransactionRequest): Promise<KitTransferTransactionResponse>;
+    };
+};
+/** Type representing the Kora plugin namespace on the client. */
+export type KoraPlugin = ReturnType<ReturnType<typeof koraPlugin>>['kora'];

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

@@ -1,60 +1,29 @@
 import { address, blockhash, signature } from '@solana/kit';
-import { KoraClient } from './client.js';
+import { KoraClient } from '../client.js';
 /**
- * Creates a Kora Kit plugin that adds Kora paymaster functionality to a Kit client.
+ * Kit plugin that adds `.kora` namespace with all Kora RPC methods.
+ * Responses are cast to Kit types (Address, Blockhash, Signature).
  *
- * 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
+ * Requires `@solana/kit` v5.4.0+ for the `createEmptyClient().use()` pattern.
  *
  * @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,
-        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 {
@@ -64,18 +33,12 @@ 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 {
@@ -90,9 +53,6 @@ export function koraPlugin(config) {
                     },
                 };
             },
-            /**
-             * Retrieves the payer signer and payment destination with Kit-typed addresses.
-             */
             async getPayerSigner() {
                 const result = await client.getPayerSigner();
                 return {
@@ -100,9 +60,6 @@ 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 {
@@ -114,35 +71,12 @@ 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 {
@@ -151,24 +85,21 @@ export function koraPlugin(config) {
                     signer_pubkey: address(result.signer_pubkey),
                 };
             },
-            /**
-             * Signs a bundle of transactions with Kit-typed response.
-             */
-            async signBundle(request) {
-                const result = await client.signBundle(request);
+            async signTransaction(request) {
+                const result = await client.signTransaction(request);
                 return {
-                    signed_transactions: result.signed_transactions,
+                    signed_transaction: result.signed_transaction,
                     signer_pubkey: address(result.signer_pubkey),
                 };
             },
-            /**
-             * Signs a transaction with Kit-typed response.
-             */
-            async signTransaction(request) {
-                const result = await client.signTransaction(request);
+            async transferTransaction(request) {
+                const result = await client.transferTransaction(request);
                 return {
-                    signed_transaction: result.signed_transaction,
+                    blockhash: blockhash(result.blockhash),
+                    instructions: result.instructions,
+                    message: result.message,
                     signer_pubkey: address(result.signer_pubkey),
+                    transaction: result.transaction,
                 };
             },
         },