@solana/kora 0.2.1 → 0.3.0-beta.2

package/dist/test/unit.test.js

@@ -1,5 +1,7 @@
+import { getTransferInstruction, TOKEN_PROGRAM_ADDRESS } from '@solana-program/token';
+import { appendTransactionMessageInstructions, createNoopSigner, createTransactionMessage, generateKeyPairSigner, partiallySignTransactionMessageWithSigners, setTransactionMessageFeePayerSigner, setTransactionMessageLifetimeUsingBlockhash, } from '@solana/kit';
 import { KoraClient } from '../src/client.js';
-import { TOKEN_PROGRAM_ADDRESS } from '@solana-program/token';
+import { KoraError } from '../src/error.js';
 import { getInstructionsFromBase64Message } from '../src/utils/transaction.js';
 // Mock fetch globally
 const mockFetch = jest.fn();
@@ -11,8 +13,8 @@ describe('KoraClient Unit Tests', () => {
     const mockSuccessfulResponse = (result) => {
         mockFetch.mockResolvedValueOnce({
             json: jest.fn().mockResolvedValueOnce({
-                jsonrpc: '2.0',
                 id: 1,
+                jsonrpc: '2.0',
                 result,
             }),
         });
@@ -20,9 +22,9 @@ describe('KoraClient Unit Tests', () => {
     const mockErrorResponse = (error) => {
         mockFetch.mockResolvedValueOnce({
             json: jest.fn().mockResolvedValueOnce({
-                jsonrpc: '2.0',
-                id: 1,
                 error,
+                id: 1,
+                jsonrpc: '2.0',
             }),
         });
     };
@@ -68,7 +70,7 @@ describe('KoraClient Unit Tests', () => {
         it('should handle RPC error responses', async () => {
             const mockError = { code: -32601, message: 'Method not found' };
             mockErrorResponse(mockError);
-            await expect(client.getConfig()).rejects.toThrow('RPC Error -32601: Method not found');
+            await expect(client.getConfig()).rejects.toThrow('Kora Error -32601: Method not found');
         });
         it('should handle network errors', async () => {
             mockFetch.mockRejectedValueOnce(new Error('Network error'));
@@ -78,70 +80,81 @@ describe('KoraClient Unit Tests', () => {
     describe('getConfig', () => {
         it('should return configuration', async () => {
             const mockConfig = {
+                enabled_methods: {
+                    estimate_bundle_fee: true,
+                    estimate_transaction_fee: true,
+                    get_blockhash: true,
+                    get_config: true,
+                    get_payer_signer: true,
+                    get_supported_tokens: true,
+                    get_version: true,
+                    liveness: true,
+                    sign_and_send_bundle: true,
+                    sign_and_send_transaction: true,
+                    sign_bundle: true,
+                    sign_transaction: true,
+                    transfer_transaction: true,
+                },
                 fee_payers: ['test_fee_payer_address'],
                 validation_config: {
-                    max_allowed_lamports: 1000000,
-                    max_signatures: 10,
-                    price_source: 'Jupiter',
                     allowed_programs: ['program1', 'program2'],
-                    allowed_tokens: ['token1', 'token2'],
                     allowed_spl_paid_tokens: ['spl_token1'],
+                    allowed_tokens: ['token1', 'token2'],
                     disallowed_accounts: ['account1'],
                     fee_payer_policy: {
-                        system: {
+                        spl_token: {
+                            allow_approve: true,
+                            allow_burn: true,
+                            allow_close_account: true,
+                            allow_freeze_account: true,
+                            allow_initialize_account: true,
+                            allow_initialize_mint: true,
+                            allow_initialize_multisig: true,
+                            allow_mint_to: true,
+                            allow_revoke: true,
+                            allow_set_authority: true,
+                            allow_thaw_account: true,
                             allow_transfer: true,
+                        },
+                        system: {
+                            allow_allocate: true,
                             allow_assign: true,
                             allow_create_account: true,
-                            allow_allocate: true,
+                            allow_transfer: true,
                             nonce: {
-                                allow_initialize: true,
                                 allow_advance: true,
                                 allow_authorize: true,
+                                allow_initialize: true,
                                 allow_withdraw: true,
                             },
                         },
-                        spl_token: {
-                            allow_transfer: true,
-                            allow_burn: true,
-                            allow_close_account: true,
-                            allow_approve: true,
-                            allow_revoke: true,
-                            allow_set_authority: true,
-                            allow_mint_to: true,
-                            allow_freeze_account: true,
-                            allow_thaw_account: true,
-                        },
                         token_2022: {
-                            allow_transfer: false,
+                            allow_approve: true,
                             allow_burn: true,
                             allow_close_account: true,
-                            allow_approve: true,
+                            allow_freeze_account: true,
+                            allow_initialize_account: true,
+                            allow_initialize_mint: true,
+                            allow_initialize_multisig: true,
+                            allow_mint_to: true,
                             allow_revoke: true,
                             allow_set_authority: true,
-                            allow_mint_to: true,
-                            allow_freeze_account: true,
                             allow_thaw_account: true,
+                            allow_transfer: false,
                         },
                     },
+                    max_allowed_lamports: 1000000,
+                    max_signatures: 10,
                     price: {
-                        type: 'margin',
                         margin: 0.1,
+                        type: 'margin',
                     },
+                    price_source: 'Jupiter',
                     token2022: {
-                        blocked_mint_extensions: ['extension1', 'extension2'],
                         blocked_account_extensions: ['account_extension1', 'account_extension2'],
+                        blocked_mint_extensions: ['extension1', 'extension2'],
                     },
                 },
-                enabled_methods: {
-                    liveness: true,
-                    estimate_transaction_fee: true,
-                    get_supported_tokens: true,
-                    sign_transaction: true,
-                    sign_and_send_transaction: true,
-                    transfer_transaction: true,
-                    get_blockhash: true,
-                    get_config: true,
-                },
             };
             await testSuccessfulRpcMethod('getConfig', () => client.getConfig(), mockConfig);
         });
@@ -154,6 +167,14 @@ describe('KoraClient Unit Tests', () => {
             await testSuccessfulRpcMethod('getBlockhash', () => client.getBlockhash(), mockResponse);
         });
     });
+    describe('getVersion', () => {
+        it('should return server version', async () => {
+            const mockResponse = {
+                version: '2.1.0-beta.0',
+            };
+            await testSuccessfulRpcMethod('getVersion', () => client.getVersion(), mockResponse);
+        });
+    });
     describe('getSupportedTokens', () => {
         it('should return supported tokens list', async () => {
             const mockResponse = {
@@ -165,15 +186,15 @@ describe('KoraClient Unit Tests', () => {
     describe('getPayerSigner', () => {
         it('should return payer signer and payment destination', async () => {
             const mockResponse = {
-                signer_address: 'DemoKMZWkk483QoFPLRPQ2XVKB7bWnuXwSjvDE1JsWk7',
                 payment_address: 'PayKMZWkk483QoFPLRPQ2XVKB7bWnuXwSjvDE1JsWk7',
+                signer_address: 'DemoKMZWkk483QoFPLRPQ2XVKB7bWnuXwSjvDE1JsWk7',
             };
             await testSuccessfulRpcMethod('getPayerSigner', () => client.getPayerSigner(), mockResponse);
         });
         it('should return same address for signer and payment_destination when no separate paymaster', async () => {
             const mockResponse = {
-                signer_address: 'DemoKMZWkk483QoFPLRPQ2XVKB7bWnuXwSjvDE1JsWk7',
                 payment_address: 'DemoKMZWkk483QoFPLRPQ2XVKB7bWnuXwSjvDE1JsWk7',
+                signer_address: 'DemoKMZWkk483QoFPLRPQ2XVKB7bWnuXwSjvDE1JsWk7',
             };
             await testSuccessfulRpcMethod('getPayerSigner', () => client.getPayerSigner(), mockResponse);
             expect(mockResponse.signer_address).toBe(mockResponse.payment_address);
@@ -182,14 +203,14 @@ describe('KoraClient Unit Tests', () => {
     describe('estimateTransactionFee', () => {
         it('should estimate transaction fee', async () => {
             const request = {
-                transaction: 'base64_encoded_transaction',
                 fee_token: 'SOL',
+                transaction: 'base64_encoded_transaction',
             };
             const mockResponse = {
                 fee_in_lamports: 5000,
                 fee_in_token: 25,
-                signer_pubkey: 'DemoKMZWkk483QoFPLRPQ2XVKB7bWnuXwSjvDE1JsWk7',
                 payment_address: 'PayKMZWkk483QoFPLRPQ2XVKB7bWnuXwSjvDE1JsWk7',
+                signer_pubkey: 'DemoKMZWkk483QoFPLRPQ2XVKB7bWnuXwSjvDE1JsWk7',
             };
             await testSuccessfulRpcMethod('estimateTransactionFee', () => client.estimateTransactionFee(request), mockResponse, request);
         });
@@ -218,149 +239,152 @@ describe('KoraClient Unit Tests', () => {
             };
             await testSuccessfulRpcMethod('signAndSendTransaction', () => client.signAndSendTransaction(request), mockResponse, request);
         });
-    });
-    describe('transferTransaction', () => {
-        it('should create transfer transaction', async () => {
+        it('should pass the respond_after milestone through to the RPC request', async () => {
             const request = {
-                amount: 1000000,
-                token: 'SOL',
-                source: 'source_address',
-                destination: 'destination_address',
+                transaction: 'base64_encoded_transaction',
+                respond_after: 'signed',
             };
             const mockResponse = {
-                transaction: 'base64_encoded_transaction',
-                message: 'Transfer transaction created',
-                blockhash: 'test_blockhash',
+                signature: 'transaction_signature',
+                signed_transaction: 'base64_signed_transaction',
                 signer_pubkey: 'test_signer_pubkey',
-                instructions: [],
             };
-            await testSuccessfulRpcMethod('transferTransaction', () => client.transferTransaction(request), mockResponse, request);
+            await testSuccessfulRpcMethod('signAndSendTransaction', () => client.signAndSendTransaction(request), mockResponse, request);
         });
-        it('should parse instructions from transfer transaction message', async () => {
+    });
+    describe('signBundle', () => {
+        it('should sign bundle of transactions', async () => {
             const request = {
-                amount: 1000000,
-                token: 'SOL',
-                source: 'source_address',
-                destination: 'destination_address',
+                transactions: ['base64_tx_1', 'base64_tx_2'],
             };
-            // This is a real base64 encoded message for testing
-            // In production, this would come from the RPC response
-            const mockMessage = 'AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAQABAwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIDAAEMAgAAAAEAAAAAAAAA';
             const mockResponse = {
-                transaction: 'base64_encoded_transaction',
-                message: mockMessage,
-                blockhash: 'test_blockhash',
+                signed_transactions: ['base64_signed_tx_1', 'base64_signed_tx_2'],
                 signer_pubkey: 'test_signer_pubkey',
-                instructions: [],
             };
-            mockSuccessfulResponse(mockResponse);
-            const result = await client.transferTransaction(request);
-            expect(result.instructions).toBeDefined();
-            expect(Array.isArray(result.instructions)).toBe(true);
-            // The instructions array should be populated from the parsed message
-            expect(result.instructions).not.toBeNull();
-        });
-        it('should handle transfer transaction with empty message gracefully', async () => {
+            await testSuccessfulRpcMethod('signBundle', () => client.signBundle(request), mockResponse, request);
+        });
+        it('should handle RPC error', async () => {
+            const request = {
+                transactions: ['base64_tx_1'],
+            };
+            const mockError = { code: -32000, message: 'Bundle validation failed' };
+            mockErrorResponse(mockError);
+            await expect(client.signBundle(request)).rejects.toThrow('Kora Error -32000: Bundle validation failed');
+        });
+    });
+    describe('signAndSendBundle', () => {
+        it('should sign and send bundle of transactions', async () => {
             const request = {
-                amount: 1000000,
-                token: 'SOL',
-                source: 'source_address',
-                destination: 'destination_address',
+                transactions: ['base64_tx_1', 'base64_tx_2'],
             };
             const mockResponse = {
-                transaction: 'base64_encoded_transaction',
-                message: '',
-                blockhash: 'test_blockhash',
+                bundle_uuid: 'test-bundle-uuid-123',
+                signed_transactions: ['base64_signed_tx_1', 'base64_signed_tx_2'],
                 signer_pubkey: 'test_signer_pubkey',
-                instructions: [],
             };
-            mockSuccessfulResponse(mockResponse);
-            const result = await client.transferTransaction(request);
-            // Should handle empty message gracefully
-            expect(result.instructions).toEqual([]);
+            await testSuccessfulRpcMethod('signAndSendBundle', () => client.signAndSendBundle(request), mockResponse, request);
+        });
+        it('should handle RPC error', async () => {
+            const request = {
+                transactions: ['base64_tx_1'],
+            };
+            const mockError = { code: -32000, message: 'Jito submission failed' };
+            mockErrorResponse(mockError);
+            await expect(client.signAndSendBundle(request)).rejects.toThrow('Kora Error -32000: Jito submission failed');
         });
     });
     describe('getPaymentInstruction', () => {
-        const mockConfig = {
+        const _mockConfig = {
+            enabled_methods: {
+                estimate_bundle_fee: true,
+                estimate_transaction_fee: true,
+                get_blockhash: true,
+                get_config: true,
+                get_payer_signer: true,
+                get_supported_tokens: true,
+                get_version: true,
+                liveness: true,
+                sign_and_send_bundle: true,
+                sign_and_send_transaction: true,
+                sign_bundle: true,
+                sign_transaction: true,
+                transfer_transaction: true,
+            },
             fee_payers: ['11111111111111111111111111111111'],
             validation_config: {
-                max_allowed_lamports: 1000000,
-                max_signatures: 10,
-                price_source: 'Jupiter',
                 allowed_programs: ['program1'],
-                allowed_tokens: ['token1'],
                 allowed_spl_paid_tokens: ['4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU'],
+                allowed_tokens: ['token1'],
                 disallowed_accounts: [],
                 fee_payer_policy: {
-                    system: {
+                    spl_token: {
+                        allow_approve: true,
+                        allow_burn: true,
+                        allow_close_account: true,
+                        allow_freeze_account: true,
+                        allow_initialize_account: true,
+                        allow_initialize_mint: true,
+                        allow_initialize_multisig: true,
+                        allow_mint_to: true,
+                        allow_revoke: true,
+                        allow_set_authority: true,
+                        allow_thaw_account: true,
                         allow_transfer: true,
+                    },
+                    system: {
+                        allow_allocate: true,
                         allow_assign: true,
                         allow_create_account: true,
-                        allow_allocate: true,
+                        allow_transfer: true,
                         nonce: {
-                            allow_initialize: true,
                             allow_advance: true,
                             allow_authorize: true,
+                            allow_initialize: true,
                             allow_withdraw: true,
                         },
                     },
-                    spl_token: {
-                        allow_transfer: true,
-                        allow_burn: true,
-                        allow_close_account: true,
-                        allow_approve: true,
-                        allow_revoke: true,
-                        allow_set_authority: true,
-                        allow_mint_to: true,
-                        allow_freeze_account: true,
-                        allow_thaw_account: true,
-                    },
                     token_2022: {
-                        allow_transfer: true,
+                        allow_approve: true,
                         allow_burn: true,
                         allow_close_account: true,
-                        allow_approve: true,
+                        allow_freeze_account: true,
+                        allow_initialize_account: true,
+                        allow_initialize_mint: true,
+                        allow_initialize_multisig: true,
+                        allow_mint_to: true,
                         allow_revoke: true,
                         allow_set_authority: true,
-                        allow_mint_to: true,
-                        allow_freeze_account: true,
                         allow_thaw_account: true,
+                        allow_transfer: true,
                     },
                 },
+                max_allowed_lamports: 1000000,
+                max_signatures: 10,
                 price: {
-                    type: 'margin',
                     margin: 0.1,
+                    type: 'margin',
                 },
+                price_source: 'Jupiter',
                 token2022: {
-                    blocked_mint_extensions: [],
                     blocked_account_extensions: [],
+                    blocked_mint_extensions: [],
                 },
             },
-            enabled_methods: {
-                liveness: true,
-                estimate_transaction_fee: true,
-                get_supported_tokens: true,
-                sign_transaction: true,
-                sign_and_send_transaction: true,
-                transfer_transaction: true,
-                get_blockhash: true,
-                get_config: true,
-            },
         };
         const mockFeeEstimate = {
             fee_in_lamports: 5000,
             fee_in_token: 50000,
-            signer_pubkey: 'DemoKMZWkk483QoFPLRPQ2XVKB7bWnuXwSjvDE1JsWk7',
             payment_address: 'PayKMZWkk483QoFPLRPQ2XVKB7bWnuXwSjvDE1JsWk7',
+            signer_pubkey: 'DemoKMZWkk483QoFPLRPQ2XVKB7bWnuXwSjvDE1JsWk7',
         };
         // Create a mock base64-encoded transaction
         // This is a minimal valid transaction structure
         const mockTransactionBase64 = 'Aoq7ymA5OGP+gmDXiY5m3cYXlY2Rz/a/gFjOgt9ZuoCS7UzuiGGaEnW2OOtvHvMQHkkD7Z4LRF5B63ftu+1oZwIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgECB1urjQEjgFgzqYhJ8IXJeSg4cJP1j1g2CJstOQTDchOKUzqH3PxgGW3c4V3vZV05A5Y30/MggOBs0Kd00s1JEwg5TaEeaV4+KL2y7fXIAuf6cN0ZQitbhY+G9ExtBSChspOXPgNcy9pYpETe4bmB+fg4bfZx1tnicA/kIyyubczAmbcIKIuniNOOQYG2ggKCz8NjEsHVezrWMatndu1wk6J5miGP26J6Vwp31AljiAajAFuP0D9mWJwSeFuA7J5rPwbd9uHXZaGT2cvhRs7reawctIXtX1s3kTqM9YV+/wCpd/O36SW02zRtNtqk6GFeip2+yBQsVTeSbLL4rWJRkd4CBgQCBQQBCgxAQg8AAAAAAAYGBAIFAwEKDBAnAAAAAAAABg==';
         const validRequest = {
-            transaction: mockTransactionBase64,
             fee_token: '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU',
             source_wallet: '11111111111111111111111111111111',
             token_program_id: 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA',
+            transaction: mockTransactionBase64,
         };
         beforeEach(() => {
             // Mock console.log to avoid noise in tests
@@ -373,16 +397,17 @@ describe('KoraClient Unit Tests', () => {
             // Mock estimateTransactionFee call
             mockFetch.mockResolvedValueOnce({
                 json: jest.fn().mockResolvedValueOnce({
-                    jsonrpc: '2.0',
                     id: 1,
+                    jsonrpc: '2.0',
                     result: mockFeeEstimate,
                 }),
             });
             const result = await client.getPaymentInstruction(validRequest);
             expect(result).toEqual({
                 original_transaction: validRequest.transaction,
+                payment_address: mockFeeEstimate.payment_address,
+                payment_amount: mockFeeEstimate.fee_in_token,
                 payment_instruction: expect.objectContaining({
-                    programAddress: TOKEN_PROGRAM_ADDRESS,
                     accounts: [
                         expect.objectContaining({
                             role: 1, // writable
@@ -391,15 +416,15 @@ describe('KoraClient Unit Tests', () => {
                             role: 1, // writable
                         }), // Destination token account
                         expect.objectContaining({
-                            role: 0, // readonly (plain address, no signer attached)
+                            // readonly (plain address, no signer attached)
                             address: validRequest.source_wallet,
+                            role: 0,
                         }), // Authority
                     ],
                     data: expect.any(Uint8Array),
+                    programAddress: TOKEN_PROGRAM_ADDRESS,
                 }),
-                payment_amount: mockFeeEstimate.fee_in_token,
                 payment_token: validRequest.fee_token,
-                payment_address: mockFeeEstimate.payment_address,
                 signer_address: mockFeeEstimate.signer_pubkey,
             });
             // Verify only estimateTransactionFee was called
@@ -424,8 +449,8 @@ describe('KoraClient Unit Tests', () => {
             // Mock estimateTransactionFee call
             mockFetch.mockResolvedValueOnce({
                 json: jest.fn().mockResolvedValueOnce({
-                    jsonrpc: '2.0',
                     id: 1,
+                    jsonrpc: '2.0',
                     result: mockFeeEstimate,
                 }),
             });
@@ -448,32 +473,96 @@ describe('KoraClient Unit Tests', () => {
             const mockError = { code: -32602, message: 'Invalid transaction' };
             mockFetch.mockResolvedValueOnce({
                 json: jest.fn().mockResolvedValueOnce({
-                    jsonrpc: '2.0',
-                    id: 1,
                     error: mockError,
+                    id: 1,
+                    jsonrpc: '2.0',
                 }),
             });
-            await expect(client.getPaymentInstruction(validRequest)).rejects.toThrow('RPC Error -32602: Invalid transaction');
+            await expect(client.getPaymentInstruction(validRequest)).rejects.toThrow('Kora Error -32602: Invalid transaction');
         });
         it('should handle network errors', async () => {
             mockFetch.mockRejectedValueOnce(new Error('Network error'));
             await expect(client.getPaymentInstruction(validRequest)).rejects.toThrow('Network error');
         });
+        it('should produce a payment instruction compatible with a real signer for the same address', async () => {
+            // Generate a real KeyPairSigner (simulates a user's wallet)
+            const userSigner = await generateKeyPairSigner();
+            // Mock estimateTransactionFee to return the user's address as source_wallet context
+            const feeEstimate = {
+                fee_in_lamports: 5000,
+                fee_in_token: 50000,
+                payment_address: 'PayKMZWkk483QoFPLRPQ2XVKB7bWnuXwSjvDE1JsWk7',
+                signer_pubkey: 'DemoKMZWkk483QoFPLRPQ2XVKB7bWnuXwSjvDE1JsWk7',
+            };
+            mockSuccessfulResponse(feeEstimate);
+            // Get payment instruction — authority is a plain address (no signer attached)
+            const result = await client.getPaymentInstruction({
+                ...validRequest,
+                source_wallet: userSigner.address,
+            });
+            // Build another instruction that references the same address with the REAL signer
+            // (simulates a program instruction like makePurchase where the user is a signer)
+            const userOwnedIx = getTransferInstruction({
+                amount: 1000n,
+                authority: userSigner, // <-- real KeyPairSigner
+                destination: 'PayKMZWkk483QoFPLRPQ2XVKB7bWnuXwSjvDE1JsWk7',
+                source: '11111111111111111111111111111111',
+            });
+            // Combine both instructions in a transaction — previously this would throw
+            // "Multiple distinct signers" because the payment instruction had a NoopSigner.
+            // Now the payment instruction uses a plain address, so no conflict.
+            const feePayer = createNoopSigner('DemoKMZWkk483QoFPLRPQ2XVKB7bWnuXwSjvDE1JsWk7');
+            const txMessage = appendTransactionMessageInstructions([userOwnedIx, result.payment_instruction], setTransactionMessageLifetimeUsingBlockhash({ blockhash: '11111111111111111111111111111111', lastValidBlockHeight: 0n }, setTransactionMessageFeePayerSigner(feePayer, createTransactionMessage({ version: 0 }))));
+            // This should NOT throw "Multiple distinct signers"
+            await expect(partiallySignTransactionMessageWithSigners(txMessage)).resolves.toBeDefined();
+        });
+        it('should accept a TransactionSigner as source_wallet and preserve signer identity', async () => {
+            const userSigner = await generateKeyPairSigner();
+            const feeEstimate = {
+                fee_in_lamports: 5000,
+                fee_in_token: 50000,
+                payment_address: 'PayKMZWkk483QoFPLRPQ2XVKB7bWnuXwSjvDE1JsWk7',
+                signer_pubkey: 'DemoKMZWkk483QoFPLRPQ2XVKB7bWnuXwSjvDE1JsWk7',
+            };
+            mockSuccessfulResponse(feeEstimate);
+            // Pass the signer directly as source_wallet
+            const result = await client.getPaymentInstruction({
+                ...validRequest,
+                source_wallet: userSigner,
+            });
+            // The authority account meta should carry the signer
+            const authorityMeta = result.payment_instruction.accounts?.[2];
+            expect(authorityMeta).toEqual(expect.objectContaining({
+                address: userSigner.address,
+                role: 2, // readonly-signer
+                signer: userSigner,
+            }));
+            // Combining with another instruction using the same signer should work
+            const userOwnedIx = getTransferInstruction({
+                amount: 1000n,
+                authority: userSigner,
+                destination: 'PayKMZWkk483QoFPLRPQ2XVKB7bWnuXwSjvDE1JsWk7',
+                source: '11111111111111111111111111111111',
+            });
+            const feePayer = createNoopSigner('DemoKMZWkk483QoFPLRPQ2XVKB7bWnuXwSjvDE1JsWk7');
+            const txMessage = appendTransactionMessageInstructions([userOwnedIx, result.payment_instruction], setTransactionMessageLifetimeUsingBlockhash({ blockhash: '11111111111111111111111111111111', lastValidBlockHeight: 0n }, setTransactionMessageFeePayerSigner(feePayer, createTransactionMessage({ version: 0 }))));
+            await expect(partiallySignTransactionMessageWithSigners(txMessage)).resolves.toBeDefined();
+        });
         it('should return correct payment details in response', async () => {
             mockFetch.mockResolvedValueOnce({
                 json: jest.fn().mockResolvedValueOnce({
-                    jsonrpc: '2.0',
                     id: 1,
+                    jsonrpc: '2.0',
                     result: mockFeeEstimate,
                 }),
             });
             const result = await client.getPaymentInstruction(validRequest);
             expect(result).toMatchObject({
                 original_transaction: validRequest.transaction,
-                payment_instruction: expect.any(Object),
+                payment_address: mockFeeEstimate.payment_address,
                 payment_amount: mockFeeEstimate.fee_in_token,
+                payment_instruction: expect.any(Object),
                 payment_token: validRequest.fee_token,
-                payment_address: mockFeeEstimate.payment_address,
                 signer_address: mockFeeEstimate.signer_pubkey,
             });
         });
@@ -488,35 +577,150 @@ describe('KoraClient Unit Tests', () => {
         it('should handle responses with an error object', async () => {
             const mockError = { code: -32602, message: 'Invalid params' };
             mockErrorResponse(mockError);
-            await expect(client.getConfig()).rejects.toThrow('RPC Error -32602: Invalid params');
+            await expect(client.getConfig()).rejects.toThrow('Kora Error -32602: Invalid params');
         });
-        it('should handle empty error object', async () => {
+        it('should handle empty error object gracefully', async () => {
             mockErrorResponse({});
-            await expect(client.getConfig()).rejects.toThrow('RPC Error undefined: undefined');
+            try {
+                await client.getConfig();
+                throw new Error('Should have thrown KoraError');
+            }
+            catch (e) {
+                expect(e).toBeInstanceOf(KoraError);
+                expect(e.code).toBe(-32603);
+                expect(e.message).toBe('Kora Error -32603: Unknown error');
+                expect(e.data).toBeUndefined();
+            }
+        });
+        it('should populate KoraError properties (code and data)', async () => {
+            const mockError = {
+                code: -32050,
+                data: {
+                    error_type: 'AccountNotFound',
+                },
+                message: 'Account not found message',
+            };
+            mockErrorResponse(mockError);
+            try {
+                await client.getConfig();
+                throw new Error('Should have thrown KoraError');
+            }
+            catch (e) {
+                expect(e).toBeInstanceOf(KoraError);
+                expect(e.code).toBe(-32050);
+                expect(e.data).toEqual({
+                    error_type: 'AccountNotFound',
+                });
+                expect(e.message).toBe('Kora Error -32050: Account not found message');
+            }
+        });
+    });
+    describe('reCAPTCHA Authentication', () => {
+        it('should include x-recaptcha-token header when getRecaptchaToken callback is provided (sync)', async () => {
+            const recaptchaClient = new KoraClient({
+                getRecaptchaToken: () => 'test-recaptcha-token',
+                rpcUrl: mockRpcUrl,
+            });
+            mockSuccessfulResponse({ version: '1.0.0' });
+            await recaptchaClient.getVersion();
+            expect(mockFetch).toHaveBeenCalledWith(mockRpcUrl, {
+                body: JSON.stringify({
+                    id: 1,
+                    jsonrpc: '2.0',
+                    method: 'getVersion',
+                    params: undefined,
+                }),
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-recaptcha-token': 'test-recaptcha-token',
+                },
+                method: 'POST',
+            });
+        });
+        it('should include x-recaptcha-token header when getRecaptchaToken callback returns Promise', async () => {
+            const recaptchaClient = new KoraClient({
+                getRecaptchaToken: () => Promise.resolve('async-recaptcha-token'),
+                rpcUrl: mockRpcUrl,
+            });
+            mockSuccessfulResponse({ version: '1.0.0' });
+            await recaptchaClient.getVersion();
+            expect(mockFetch).toHaveBeenCalledWith(mockRpcUrl, {
+                body: JSON.stringify({
+                    id: 1,
+                    jsonrpc: '2.0',
+                    method: 'getVersion',
+                    params: undefined,
+                }),
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-recaptcha-token': 'async-recaptcha-token',
+                },
+                method: 'POST',
+            });
+        });
+        it('should NOT include x-recaptcha-token header when getRecaptchaToken is not provided', async () => {
+            mockSuccessfulResponse({ version: '1.0.0' });
+            await client.getVersion();
+            expect(mockFetch).toHaveBeenCalledWith(mockRpcUrl, {
+                body: JSON.stringify({
+                    id: 1,
+                    jsonrpc: '2.0',
+                    method: 'getVersion',
+                    params: undefined,
+                }),
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                method: 'POST',
+            });
+        });
+        it('should include x-recaptcha-token along with other auth headers', async () => {
+            const combinedAuthClient = new KoraClient({
+                apiKey: 'test-api-key',
+                getRecaptchaToken: () => 'test-recaptcha-token',
+                rpcUrl: mockRpcUrl,
+            });
+            mockSuccessfulResponse({ version: '1.0.0' });
+            await combinedAuthClient.getVersion();
+            const callArgs = mockFetch.mock.calls[0][1];
+            expect(callArgs.headers).toMatchObject({
+                'Content-Type': 'application/json',
+                'x-api-key': 'test-api-key',
+                'x-recaptcha-token': 'test-recaptcha-token',
+            });
+        });
+        it('should call getRecaptchaToken callback for each request', async () => {
+            let callCount = 0;
+            const recaptchaClient = new KoraClient({
+                getRecaptchaToken: () => `token-${++callCount}`,
+                rpcUrl: mockRpcUrl,
+            });
+            mockSuccessfulResponse({ version: '1.0.0' });
+            await recaptchaClient.getVersion();
+            mockSuccessfulResponse({ blockhash: 'test-blockhash' });
+            await recaptchaClient.getBlockhash();
+            expect(callCount).toBe(2);
+            const calls = mockFetch.mock.calls;
+            expect(calls[0][1].headers['x-recaptcha-token']).toBe('token-1');
+            expect(calls[1][1].headers['x-recaptcha-token']).toBe('token-2');
+        });
+        it('should propagate errors when getRecaptchaToken callback throws', async () => {
+            const recaptchaClient = new KoraClient({
+                getRecaptchaToken: () => {
+                    throw new Error('reCAPTCHA failed to load');
+                },
+                rpcUrl: mockRpcUrl,
+            });
+            await expect(recaptchaClient.getVersion()).rejects.toThrow('reCAPTCHA failed to load');
+        });
+        it('should propagate errors when getRecaptchaToken returns rejected Promise', async () => {
+            const recaptchaClient = new KoraClient({
+                getRecaptchaToken: () => Promise.reject(new Error('Token generation failed')),
+                rpcUrl: mockRpcUrl,
+            });
+            await expect(recaptchaClient.getVersion()).rejects.toThrow('Token generation failed');
         });
     });
-    // TODO: Add Authentication Tests (separate PR)
-    //
-    // describe('Authentication', () => {
-    //     describe('API Key Authentication', () => {
-    //         - Test that x-api-key header is included when apiKey is provided
-    //         - Test requests work without apiKey when not provided
-    //         - Test all RPC methods include the header
-    //     });
-    //
-    //     describe('HMAC Authentication', () => {
-    //         - Test x-timestamp and x-hmac-signature headers are included when hmacSecret is provided
-    //         - Test HMAC signature calculation is correct (SHA256 of timestamp + body)
-    //         - Test timestamp is current (within reasonable bounds)
-    //         - Test requests work without HMAC when not provided
-    //         - Test all RPC methods include the headers
-    //     });
-    //
-    //     describe('Combined Authentication', () => {
-    //         - Test both API key and HMAC headers are included when both are provided
-    //         - Test headers are correctly combined
-    //     });
-    // });
 });
 describe('Transaction Utils', () => {
     describe('getInstructionsFromBase64Message', () => {