kaspa-mcp 0.1.0

package/dist/kaspa/wallet.test.js

@@ -0,0 +1,160 @@
+// ABOUTME: Unit tests for KaspaWallet key management
+// ABOUTME: Tests mnemonic derivation, private key handling, and address generation
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { KaspaWallet } from './wallet.js';
+// WARNING: These are PUBLIC TEST-ONLY credentials. DO NOT use on mainnet with real funds.
+// They are published in this repository and offer no security.
+// Valid test mnemonic (24 words)
+const TEST_MNEMONIC = 'matter client cigar north mixed hard rail kitten flat shrug view group diagram release goose thumb benefit fire confirm swamp skill merry genre visa';
+// Valid testnet private key (64 hex characters)
+const TEST_PRIVATE_KEY = 'a9f8d7e6c5b4a3029187654321fedcba9876543210fedcba9876543210fedcba';
+describe('KaspaWallet', () => {
+    describe('fromMnemonic', () => {
+        it('creates wallet from valid mnemonic for mainnet', () => {
+            const wallet = KaspaWallet.fromMnemonic(TEST_MNEMONIC, 'mainnet');
+            expect(wallet).toBeInstanceOf(KaspaWallet);
+            expect(wallet.getAddress()).toMatch(/^kaspa:/);
+        });
+        it('creates wallet from valid mnemonic for testnet-10', () => {
+            const wallet = KaspaWallet.fromMnemonic(TEST_MNEMONIC, 'testnet-10');
+            expect(wallet).toBeInstanceOf(KaspaWallet);
+            expect(wallet.getAddress()).toMatch(/^kaspatest:/);
+        });
+        it('creates wallet from valid mnemonic for testnet-11', () => {
+            const wallet = KaspaWallet.fromMnemonic(TEST_MNEMONIC, 'testnet-11');
+            expect(wallet).toBeInstanceOf(KaspaWallet);
+            expect(wallet.getAddress()).toMatch(/^kaspatest:/);
+        });
+        it('creates wallet with different account index', () => {
+            const wallet0 = KaspaWallet.fromMnemonic(TEST_MNEMONIC, 'mainnet', 0);
+            const wallet1 = KaspaWallet.fromMnemonic(TEST_MNEMONIC, 'mainnet', 1);
+            expect(wallet0.getAddress()).not.toBe(wallet1.getAddress());
+        });
+        it('throws error for empty mnemonic', () => {
+            expect(() => KaspaWallet.fromMnemonic('', 'mainnet')).toThrow('Mnemonic phrase is required');
+        });
+        it('throws error for invalid mnemonic', () => {
+            expect(() => KaspaWallet.fromMnemonic('invalid mnemonic words', 'mainnet')).toThrow('Invalid mnemonic phrase');
+        });
+        it('defaults to mainnet when no network specified', () => {
+            const wallet = KaspaWallet.fromMnemonic(TEST_MNEMONIC);
+            expect(wallet.getAddress()).toMatch(/^kaspa:/);
+        });
+    });
+    describe('fromPrivateKey', () => {
+        it('creates wallet from valid private key', () => {
+            const wallet = KaspaWallet.fromPrivateKey(TEST_PRIVATE_KEY, 'mainnet');
+            expect(wallet).toBeInstanceOf(KaspaWallet);
+            expect(wallet.getAddress()).toMatch(/^kaspa:/);
+        });
+        it('creates wallet for testnet-10', () => {
+            const wallet = KaspaWallet.fromPrivateKey(TEST_PRIVATE_KEY, 'testnet-10');
+            expect(wallet.getAddress()).toMatch(/^kaspatest:/);
+        });
+        it('throws error for empty private key', () => {
+            expect(() => KaspaWallet.fromPrivateKey('', 'mainnet')).toThrow('Private key is required');
+        });
+        it('throws error for invalid private key format', () => {
+            expect(() => KaspaWallet.fromPrivateKey('not-a-valid-key', 'mainnet')).toThrow('Invalid private key format');
+        });
+        it('defaults to mainnet when no network specified', () => {
+            const wallet = KaspaWallet.fromPrivateKey(TEST_PRIVATE_KEY);
+            expect(wallet.getAddress()).toMatch(/^kaspa:/);
+        });
+    });
+    describe('getAddress', () => {
+        it('returns consistent address for same wallet', () => {
+            const wallet = KaspaWallet.fromMnemonic(TEST_MNEMONIC, 'mainnet');
+            expect(wallet.getAddress()).toBe(wallet.getAddress());
+        });
+    });
+    describe('getPrivateKey', () => {
+        it('returns the private key object', () => {
+            const wallet = KaspaWallet.fromMnemonic(TEST_MNEMONIC, 'mainnet');
+            const pk = wallet.getPrivateKey();
+            expect(pk).toBeDefined();
+        });
+    });
+    describe('getNetworkType', () => {
+        it('returns Mainnet for mainnet wallet', () => {
+            const wallet = KaspaWallet.fromMnemonic(TEST_MNEMONIC, 'mainnet');
+            const networkType = wallet.getNetworkType();
+            expect(networkType).toBeDefined();
+        });
+        it('returns Testnet for testnet-10 wallet', () => {
+            const wallet = KaspaWallet.fromMnemonic(TEST_MNEMONIC, 'testnet-10');
+            const networkType = wallet.getNetworkType();
+            expect(networkType).toBeDefined();
+        });
+    });
+    describe('getNetworkId', () => {
+        it('returns mainnet for mainnet wallet', () => {
+            const wallet = KaspaWallet.fromMnemonic(TEST_MNEMONIC, 'mainnet');
+            expect(wallet.getNetworkId()).toBe('mainnet');
+        });
+        it('returns testnet-10 for testnet-10 wallet', () => {
+            const wallet = KaspaWallet.fromMnemonic(TEST_MNEMONIC, 'testnet-10');
+            expect(wallet.getNetworkId()).toBe('testnet-10');
+        });
+    });
+});
+describe('getWallet', () => {
+    const originalEnv = process.env;
+    beforeEach(() => {
+        // Reset module state by clearing the cached wallet
+        vi.resetModules();
+        process.env = { ...originalEnv };
+    });
+    afterEach(() => {
+        process.env = originalEnv;
+    });
+    it('creates wallet from KASPA_MNEMONIC environment variable', async () => {
+        process.env.KASPA_MNEMONIC = TEST_MNEMONIC;
+        process.env.KASPA_NETWORK = 'testnet-10';
+        delete process.env.KASPA_PRIVATE_KEY;
+        const { getWallet: freshGetWallet } = await import('./wallet.js');
+        const wallet = freshGetWallet();
+        expect(wallet.getAddress()).toMatch(/^kaspatest:/);
+    });
+    it('creates wallet from KASPA_PRIVATE_KEY when no mnemonic', async () => {
+        delete process.env.KASPA_MNEMONIC;
+        process.env.KASPA_PRIVATE_KEY = TEST_PRIVATE_KEY;
+        process.env.KASPA_NETWORK = 'mainnet';
+        const { getWallet: freshGetWallet } = await import('./wallet.js');
+        const wallet = freshGetWallet();
+        expect(wallet.getAddress()).toMatch(/^kaspa:/);
+    });
+    it('uses account index from KASPA_ACCOUNT_INDEX', async () => {
+        process.env.KASPA_MNEMONIC = TEST_MNEMONIC;
+        process.env.KASPA_NETWORK = 'mainnet';
+        process.env.KASPA_ACCOUNT_INDEX = '1';
+        delete process.env.KASPA_PRIVATE_KEY;
+        const { getWallet: freshGetWallet } = await import('./wallet.js');
+        const wallet = freshGetWallet();
+        // Use duck typing since module re-import creates different class reference
+        expect(wallet.getAddress()).toMatch(/^kaspa:/);
+        expect(wallet.getNetworkId()).toBe('mainnet');
+    });
+    it('defaults to mainnet when KASPA_NETWORK not set', async () => {
+        process.env.KASPA_MNEMONIC = TEST_MNEMONIC;
+        delete process.env.KASPA_NETWORK;
+        delete process.env.KASPA_PRIVATE_KEY;
+        const { getWallet: freshGetWallet } = await import('./wallet.js');
+        const wallet = freshGetWallet();
+        expect(wallet.getAddress()).toMatch(/^kaspa:/);
+    });
+    it('throws error when no credentials set', async () => {
+        delete process.env.KASPA_MNEMONIC;
+        delete process.env.KASPA_PRIVATE_KEY;
+        const { getWallet: freshGetWallet } = await import('./wallet.js');
+        expect(() => freshGetWallet()).toThrow('Either KASPA_MNEMONIC or KASPA_PRIVATE_KEY environment variable must be set');
+    });
+    it('returns cached wallet on subsequent calls', async () => {
+        process.env.KASPA_MNEMONIC = TEST_MNEMONIC;
+        process.env.KASPA_NETWORK = 'mainnet';
+        const { getWallet: freshGetWallet } = await import('./wallet.js');
+        const wallet1 = freshGetWallet();
+        const wallet2 = freshGetWallet();
+        expect(wallet1).toBe(wallet2);
+    });
+});

package/dist/test-setup.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test-setup.js

@@ -0,0 +1,4 @@
+// ABOUTME: Test setup file for vitest
+// ABOUTME: Configures WebSocket polyfill and common mocks
+import WebSocket from 'isomorphic-ws';
+globalThis.WebSocket = WebSocket;

package/dist/tools/get-balance.d.ts

@@ -0,0 +1,9 @@
+export interface GetBalanceParams {
+    address?: string;
+}
+export interface GetBalanceResult {
+    address: string;
+    balance: string;
+    utxoCount: number;
+}
+export declare function getBalance(params: GetBalanceParams): Promise<GetBalanceResult>;

package/dist/tools/get-balance.js

@@ -0,0 +1,21 @@
+// ABOUTME: MCP tool to get balance for a Kaspa address
+// ABOUTME: Returns balance in KAS and UTXO count
+import * as kaspa from 'kaspa-wasm';
+import { getApi } from '../kaspa/api.js';
+import { getWallet } from '../kaspa/wallet.js';
+const { sompiToKaspaString } = kaspa;
+export async function getBalance(params) {
+    const wallet = getWallet();
+    const address = params.address || wallet.getAddress();
+    const api = getApi(wallet.getNetworkId());
+    const [balanceResponse, utxos] = await Promise.all([
+        api.getBalance(address),
+        api.getUtxos(address),
+    ]);
+    const balanceKas = sompiToKaspaString(BigInt(balanceResponse.balance));
+    return {
+        address,
+        balance: balanceKas,
+        utxoCount: utxos.length,
+    };
+}

package/dist/tools/get-balance.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/get-balance.test.js

@@ -0,0 +1,93 @@
+// ABOUTME: Unit tests for get-balance MCP tool
+// ABOUTME: Tests balance retrieval with sompi conversion
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+vi.mock('../kaspa/wallet.js', () => ({
+    getWallet: vi.fn(),
+}));
+vi.mock('../kaspa/api.js', () => ({
+    getApi: vi.fn(),
+}));
+vi.mock('kaspa-wasm', () => ({
+    sompiToKaspaString: vi.fn((sompi) => {
+        const kas = Number(sompi) / 100_000_000;
+        return kas.toString();
+    }),
+}));
+import { getBalance } from './get-balance.js';
+import { getWallet } from '../kaspa/wallet.js';
+import { getApi } from '../kaspa/api.js';
+describe('getBalance', () => {
+    const mockWallet = {
+        getAddress: vi.fn(),
+        getNetworkId: vi.fn(),
+    };
+    const mockApi = {
+        getBalance: vi.fn(),
+        getUtxos: vi.fn(),
+    };
+    beforeEach(() => {
+        vi.mocked(getWallet).mockReturnValue(mockWallet);
+        vi.mocked(getApi).mockReturnValue(mockApi);
+        mockWallet.getAddress.mockReset();
+        mockWallet.getNetworkId.mockReset();
+        mockApi.getBalance.mockReset();
+        mockApi.getUtxos.mockReset();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('returns balance for wallet address when no address provided', async () => {
+        mockWallet.getAddress.mockReturnValue('kaspa:qpwallet123');
+        mockWallet.getNetworkId.mockReturnValue('mainnet');
+        mockApi.getBalance.mockResolvedValue({ balance: '1000000000' });
+        mockApi.getUtxos.mockResolvedValue([{ utxo: 1 }, { utxo: 2 }]);
+        const result = await getBalance({});
+        expect(result).toEqual({
+            address: 'kaspa:qpwallet123',
+            balance: '10',
+            utxoCount: 2,
+        });
+        expect(getApi).toHaveBeenCalledWith('mainnet');
+    });
+    it('returns balance for specified address', async () => {
+        mockWallet.getAddress.mockReturnValue('kaspa:qpwallet123');
+        mockWallet.getNetworkId.mockReturnValue('testnet-10');
+        mockApi.getBalance.mockResolvedValue({ balance: '500000000' });
+        mockApi.getUtxos.mockResolvedValue([{ utxo: 1 }]);
+        const result = await getBalance({ address: 'kaspatest:qpother456' });
+        expect(result).toEqual({
+            address: 'kaspatest:qpother456',
+            balance: '5',
+            utxoCount: 1,
+        });
+    });
+    it('returns zero balance with no UTXOs', async () => {
+        mockWallet.getAddress.mockReturnValue('kaspa:qpempty');
+        mockWallet.getNetworkId.mockReturnValue('mainnet');
+        mockApi.getBalance.mockResolvedValue({ balance: '0' });
+        mockApi.getUtxos.mockResolvedValue([]);
+        const result = await getBalance({});
+        expect(result).toEqual({
+            address: 'kaspa:qpempty',
+            balance: '0',
+            utxoCount: 0,
+        });
+    });
+    it('handles large balance amounts', async () => {
+        mockWallet.getAddress.mockReturnValue('kaspa:qprich');
+        mockWallet.getNetworkId.mockReturnValue('mainnet');
+        mockApi.getBalance.mockResolvedValue({ balance: '100000000000000' });
+        mockApi.getUtxos.mockResolvedValue(new Array(100).fill({ utxo: 1 }));
+        const result = await getBalance({});
+        expect(result.utxoCount).toBe(100);
+        expect(result.address).toBe('kaspa:qprich');
+    });
+    it('calls API with correct network', async () => {
+        mockWallet.getAddress.mockReturnValue('kaspatest:qptest');
+        mockWallet.getNetworkId.mockReturnValue('testnet-11');
+        mockApi.getBalance.mockResolvedValue({ balance: '1000000' });
+        mockApi.getUtxos.mockResolvedValue([]);
+        await getBalance({});
+        expect(getApi).toHaveBeenCalledWith('testnet-11');
+    });
+});

package/dist/tools/get-fee-estimate.d.ts

@@ -0,0 +1,6 @@
+export interface GetFeeEstimateResult {
+    priorityFee: string;
+    normalFee: string;
+    lowFee: string;
+}
+export declare function getFeeEstimate(): Promise<GetFeeEstimateResult>;

package/dist/tools/get-fee-estimate.js

@@ -0,0 +1,13 @@
+// ABOUTME: MCP tool to get current fee estimates from the Kaspa network
+// ABOUTME: Returns priority and normal fee rates in sompi/gram
+import { getApi } from '../kaspa/api.js';
+import { getWallet } from '../kaspa/wallet.js';
+export async function getFeeEstimate() {
+    const api = getApi(getWallet().getNetworkId());
+    const feeEstimate = await api.getFeeEstimate();
+    return {
+        priorityFee: feeEstimate.priorityBucket.feerate.toString(),
+        normalFee: feeEstimate.normalBuckets[0]?.feerate.toString() || '0',
+        lowFee: feeEstimate.lowBuckets[0]?.feerate.toString() || '0',
+    };
+}

package/dist/tools/get-fee-estimate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/get-fee-estimate.test.js

@@ -0,0 +1,74 @@
+// ABOUTME: Unit tests for get-fee-estimate MCP tool
+// ABOUTME: Tests fee estimate retrieval and formatting
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+vi.mock('../kaspa/wallet.js', () => ({
+    getWallet: vi.fn(),
+}));
+vi.mock('../kaspa/api.js', () => ({
+    getApi: vi.fn(),
+}));
+import { getFeeEstimate } from './get-fee-estimate.js';
+import { getWallet } from '../kaspa/wallet.js';
+import { getApi } from '../kaspa/api.js';
+describe('getFeeEstimate', () => {
+    const mockWallet = {
+        getNetworkId: vi.fn(),
+    };
+    const mockApi = {
+        getFeeEstimate: vi.fn(),
+    };
+    beforeEach(() => {
+        vi.mocked(getWallet).mockReturnValue(mockWallet);
+        vi.mocked(getApi).mockReturnValue(mockApi);
+        mockWallet.getNetworkId.mockReset();
+        mockApi.getFeeEstimate.mockReset();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('returns fee estimates from API', async () => {
+        mockWallet.getNetworkId.mockReturnValue('mainnet');
+        mockApi.getFeeEstimate.mockResolvedValue({
+            priorityBucket: { feerate: 1.5 },
+            normalBuckets: [{ feerate: 1.0 }],
+            lowBuckets: [{ feerate: 0.5 }],
+        });
+        const result = await getFeeEstimate();
+        expect(result).toEqual({
+            priorityFee: '1.5',
+            normalFee: '1',
+            lowFee: '0.5',
+        });
+        expect(getApi).toHaveBeenCalledWith('mainnet');
+    });
+    it('returns 0 for normal fee when normalBuckets is empty', async () => {
+        mockWallet.getNetworkId.mockReturnValue('testnet-10');
+        mockApi.getFeeEstimate.mockResolvedValue({
+            priorityBucket: { feerate: 2.0 },
+            normalBuckets: [],
+            lowBuckets: [{ feerate: 0.5 }],
+        });
+        const result = await getFeeEstimate();
+        expect(result.normalFee).toBe('0');
+    });
+    it('returns 0 for low fee when lowBuckets is empty', async () => {
+        mockWallet.getNetworkId.mockReturnValue('testnet-11');
+        mockApi.getFeeEstimate.mockResolvedValue({
+            priorityBucket: { feerate: 2.0 },
+            normalBuckets: [{ feerate: 1.0 }],
+            lowBuckets: [],
+        });
+        const result = await getFeeEstimate();
+        expect(result.lowFee).toBe('0');
+    });
+    it('uses correct network from wallet', async () => {
+        mockWallet.getNetworkId.mockReturnValue('testnet-10');
+        mockApi.getFeeEstimate.mockResolvedValue({
+            priorityBucket: { feerate: 1.0 },
+            normalBuckets: [{ feerate: 0.5 }],
+            lowBuckets: [{ feerate: 0.25 }],
+        });
+        await getFeeEstimate();
+        expect(getApi).toHaveBeenCalledWith('testnet-10');
+    });
+});

package/dist/tools/get-my-address.d.ts

@@ -0,0 +1,4 @@
+export interface GetMyAddressResult {
+    address: string;
+}
+export declare function getMyAddress(): Promise<GetMyAddressResult>;

package/dist/tools/get-my-address.js

@@ -0,0 +1,9 @@
+// ABOUTME: MCP tool to get the wallet address derived from the configured private key
+// ABOUTME: Returns the Kaspa address for the current wallet
+import { getWallet } from '../kaspa/wallet.js';
+export async function getMyAddress() {
+    const wallet = getWallet();
+    return {
+        address: wallet.getAddress(),
+    };
+}

package/dist/tools/get-my-address.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/get-my-address.test.js

@@ -0,0 +1,32 @@
+// ABOUTME: Unit tests for get-my-address MCP tool
+// ABOUTME: Tests wallet address retrieval functionality
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+vi.mock('../kaspa/wallet.js', () => ({
+    getWallet: vi.fn(),
+}));
+import { getMyAddress } from './get-my-address.js';
+import { getWallet } from '../kaspa/wallet.js';
+describe('getMyAddress', () => {
+    const mockWallet = {
+        getAddress: vi.fn(),
+    };
+    beforeEach(() => {
+        vi.mocked(getWallet).mockReturnValue(mockWallet);
+        mockWallet.getAddress.mockReset();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('returns the wallet address', async () => {
+        mockWallet.getAddress.mockReturnValue('kaspa:qptest123');
+        const result = await getMyAddress();
+        expect(result).toEqual({ address: 'kaspa:qptest123' });
+        expect(getWallet).toHaveBeenCalled();
+        expect(mockWallet.getAddress).toHaveBeenCalled();
+    });
+    it('returns testnet address when wallet is on testnet', async () => {
+        mockWallet.getAddress.mockReturnValue('kaspatest:qptest456');
+        const result = await getMyAddress();
+        expect(result).toEqual({ address: 'kaspatest:qptest456' });
+    });
+});

package/dist/tools/get-transaction.d.ts

@@ -0,0 +1,21 @@
+export interface GetTransactionParams {
+    txId: string;
+}
+export interface TransactionOutput {
+    index: number;
+    amount: string;
+    address: string;
+}
+export interface TransactionInput {
+    transactionId: string;
+    index: number;
+}
+export interface GetTransactionResult {
+    txId: string;
+    accepted: boolean;
+    blockHash?: string;
+    blockTime?: number;
+    inputs: TransactionInput[];
+    outputs: TransactionOutput[];
+}
+export declare function getTransaction(params: GetTransactionParams): Promise<GetTransactionResult>;

package/dist/tools/get-transaction.js

@@ -0,0 +1,36 @@
+// ABOUTME: MCP tool to get transaction status and details
+// ABOUTME: Returns transaction details including inputs, outputs, and acceptance status
+import * as kaspa from 'kaspa-wasm';
+import { getApi } from '../kaspa/api.js';
+import { getWallet } from '../kaspa/wallet.js';
+const { sompiToKaspaString } = kaspa;
+export async function getTransaction(params) {
+    if (!params.txId) {
+        throw new Error('Transaction ID (txId) is required');
+    }
+    const api = getApi(getWallet().getNetworkId());
+    try {
+        const tx = await api.getTransaction(params.txId);
+        return {
+            txId: tx.transaction_id,
+            accepted: tx.is_accepted,
+            blockHash: tx.block_hash?.[0],
+            blockTime: tx.block_time,
+            inputs: tx.inputs.map((input) => ({
+                transactionId: input.previous_outpoint_hash,
+                index: input.previous_outpoint_index,
+            })),
+            outputs: tx.outputs.map((output, idx) => ({
+                index: idx,
+                amount: sompiToKaspaString(BigInt(output.amount)),
+                address: output.script_public_key_address,
+            })),
+        };
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.includes('404')) {
+            throw new Error(`Transaction not found: ${params.txId}`);
+        }
+        throw error;
+    }
+}

package/dist/tools/get-transaction.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/get-transaction.test.js

@@ -0,0 +1,119 @@
+// ABOUTME: Unit tests for get-transaction MCP tool
+// ABOUTME: Tests transaction retrieval and error handling
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+vi.mock('kaspa-wasm', () => ({
+    sompiToKaspaString: (sompi) => (Number(sompi) / 100_000_000).toString(),
+}));
+vi.mock('../kaspa/wallet.js', () => ({
+    getWallet: vi.fn(),
+}));
+vi.mock('../kaspa/api.js', () => ({
+    getApi: vi.fn(),
+}));
+import { getTransaction } from './get-transaction.js';
+import { getWallet } from '../kaspa/wallet.js';
+import { getApi } from '../kaspa/api.js';
+describe('getTransaction', () => {
+    const mockWallet = {
+        getNetworkId: vi.fn(),
+    };
+    const mockApi = {
+        getTransaction: vi.fn(),
+    };
+    beforeEach(() => {
+        vi.mocked(getWallet).mockReturnValue(mockWallet);
+        vi.mocked(getApi).mockReturnValue(mockApi);
+        mockWallet.getNetworkId.mockReset();
+        mockApi.getTransaction.mockReset();
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('returns transaction details for accepted tx', async () => {
+        mockWallet.getNetworkId.mockReturnValue('mainnet');
+        mockApi.getTransaction.mockResolvedValue({
+            transaction_id: 'abc123',
+            is_accepted: true,
+            block_hash: ['blockhash1'],
+            block_time: 1234567890,
+            inputs: [
+                { previous_outpoint_hash: 'input_tx_1', previous_outpoint_index: 0 },
+            ],
+            outputs: [
+                { amount: '10000000000', script_public_key_address: 'kaspa:qprecipient' },
+                { amount: '5000000000', script_public_key_address: 'kaspa:qpchange' },
+            ],
+        });
+        const result = await getTransaction({ txId: 'abc123' });
+        expect(result).toEqual({
+            txId: 'abc123',
+            accepted: true,
+            blockHash: 'blockhash1',
+            blockTime: 1234567890,
+            inputs: [{ transactionId: 'input_tx_1', index: 0 }],
+            outputs: [
+                { index: 0, amount: '100', address: 'kaspa:qprecipient' },
+                { index: 1, amount: '50', address: 'kaspa:qpchange' },
+            ],
+        });
+        expect(getApi).toHaveBeenCalledWith('mainnet');
+        expect(mockApi.getTransaction).toHaveBeenCalledWith('abc123');
+    });
+    it('returns transaction details for pending tx', async () => {
+        mockWallet.getNetworkId.mockReturnValue('testnet-10');
+        mockApi.getTransaction.mockResolvedValue({
+            transaction_id: 'def456',
+            is_accepted: false,
+            block_hash: null,
+            block_time: undefined,
+            inputs: [],
+            outputs: [],
+        });
+        const result = await getTransaction({ txId: 'def456' });
+        expect(result).toEqual({
+            txId: 'def456',
+            accepted: false,
+            blockHash: undefined,
+            blockTime: undefined,
+            inputs: [],
+            outputs: [],
+        });
+    });
+    it('throws error when txId is not provided', async () => {
+        await expect(getTransaction({ txId: '' })).rejects.toThrow('Transaction ID (txId) is required');
+    });
+    it('throws error when transaction is not found (404)', async () => {
+        mockWallet.getNetworkId.mockReturnValue('mainnet');
+        mockApi.getTransaction.mockRejectedValue(new Error('API error 404: Not found'));
+        await expect(getTransaction({ txId: 'notfound' })).rejects.toThrow('Transaction not found: notfound');
+    });
+    it('rethrows other errors', async () => {
+        mockWallet.getNetworkId.mockReturnValue('mainnet');
+        mockApi.getTransaction.mockRejectedValue(new Error('Network error'));
+        await expect(getTransaction({ txId: 'abc123' })).rejects.toThrow('Network error');
+    });
+    it('handles block_hash being undefined', async () => {
+        mockWallet.getNetworkId.mockReturnValue('mainnet');
+        mockApi.getTransaction.mockResolvedValue({
+            transaction_id: 'ghi789',
+            is_accepted: true,
+            block_hash: undefined,
+            inputs: [],
+            outputs: [],
+        });
+        const result = await getTransaction({ txId: 'ghi789' });
+        expect(result.blockHash).toBeUndefined();
+    });
+    it('handles empty block_hash array', async () => {
+        mockWallet.getNetworkId.mockReturnValue('mainnet');
+        mockApi.getTransaction.mockResolvedValue({
+            transaction_id: 'jkl012',
+            is_accepted: true,
+            block_hash: [],
+            inputs: [],
+            outputs: [],
+        });
+        const result = await getTransaction({ txId: 'jkl012' });
+        expect(result.blockHash).toBeUndefined();
+    });
+});

package/dist/tools/send-kaspa.d.ts

@@ -0,0 +1,10 @@
+export interface SendKaspaParams {
+    to: string;
+    amount: string;
+    priorityFee?: number;
+}
+export interface SendKaspaResult {
+    txId: string;
+    fee: string;
+}
+export declare function sendKaspa(params: SendKaspaParams): Promise<SendKaspaResult>;