kaspa-mcp 0.1.0

package/dist/kaspa/api.test.js

@@ -0,0 +1,177 @@
+// ABOUTME: Unit tests for KaspaApi REST client
+// ABOUTME: Tests API methods with mocked fetch responses
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { KaspaApi, getApi } from './api.js';
+describe('KaspaApi', () => {
+    const mockFetch = vi.fn();
+    const originalFetch = globalThis.fetch;
+    beforeEach(() => {
+        globalThis.fetch = mockFetch;
+        mockFetch.mockReset();
+    });
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+    });
+    describe('constructor', () => {
+        it('uses mainnet endpoint by default', () => {
+            const api = new KaspaApi();
+            expect(api).toBeInstanceOf(KaspaApi);
+        });
+        it('uses testnet-10 endpoint when specified', () => {
+            const api = new KaspaApi('testnet-10');
+            expect(api).toBeInstanceOf(KaspaApi);
+        });
+        it('uses testnet-11 endpoint when specified', () => {
+            const api = new KaspaApi('testnet-11');
+            expect(api).toBeInstanceOf(KaspaApi);
+        });
+        it('falls back to mainnet for unknown network', () => {
+            const api = new KaspaApi('unknown-network');
+            expect(api).toBeInstanceOf(KaspaApi);
+        });
+    });
+    describe('getBalance', () => {
+        it('fetches balance for an address', async () => {
+            const mockResponse = { address: 'kaspa:test', balance: '1000000000' };
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: () => Promise.resolve(mockResponse),
+            });
+            const api = new KaspaApi();
+            const result = await api.getBalance('kaspa:test');
+            expect(result).toEqual(mockResponse);
+            expect(mockFetch).toHaveBeenCalledWith('https://api.kaspa.org/addresses/kaspa:test/balance', expect.objectContaining({
+                headers: { 'Content-Type': 'application/json' },
+            }));
+        });
+        it('throws error on API failure', async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: false,
+                status: 404,
+                text: () => Promise.resolve('Not found'),
+            });
+            const api = new KaspaApi();
+            await expect(api.getBalance('kaspa:invalid')).rejects.toThrow('API error 404: Not found');
+        });
+    });
+    describe('getUtxos', () => {
+        it('fetches UTXOs for an address', async () => {
+            const mockResponse = [
+                {
+                    address: 'kaspa:test',
+                    outpoint: { transactionId: 'abc123', index: 0 },
+                    utxoEntry: {
+                        amount: '1000000000',
+                        scriptPublicKey: { scriptPublicKey: '20abc' },
+                        blockDaaScore: '12345',
+                        isCoinbase: false,
+                    },
+                },
+            ];
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: () => Promise.resolve(mockResponse),
+            });
+            const api = new KaspaApi();
+            const result = await api.getUtxos('kaspa:test');
+            expect(result).toEqual(mockResponse);
+            expect(mockFetch).toHaveBeenCalledWith('https://api.kaspa.org/addresses/kaspa:test/utxos', expect.any(Object));
+        });
+        it('throws error on API failure', async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: false,
+                status: 500,
+                text: () => Promise.resolve('Server error'),
+            });
+            const api = new KaspaApi();
+            await expect(api.getUtxos('kaspa:test')).rejects.toThrow('API error 500');
+        });
+    });
+    describe('getFeeEstimate', () => {
+        it('fetches fee estimates', async () => {
+            const mockResponse = {
+                priorityBucket: { feerate: 1.5, estimatedSeconds: 10 },
+                normalBuckets: [{ feerate: 1.0, estimatedSeconds: 30 }],
+                lowBuckets: [{ feerate: 0.5, estimatedSeconds: 60 }],
+            };
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: () => Promise.resolve(mockResponse),
+            });
+            const api = new KaspaApi();
+            const result = await api.getFeeEstimate();
+            expect(result).toEqual(mockResponse);
+            expect(mockFetch).toHaveBeenCalledWith('https://api.kaspa.org/info/fee-estimate', expect.any(Object));
+        });
+        it('throws error on API failure', async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: false,
+                status: 503,
+                text: () => Promise.resolve('Service unavailable'),
+            });
+            const api = new KaspaApi();
+            await expect(api.getFeeEstimate()).rejects.toThrow('API error 503');
+        });
+    });
+    describe('getTransaction', () => {
+        it('fetches transaction details', async () => {
+            const mockResponse = {
+                transaction_id: 'abc123',
+                block_hash: ['block1'],
+                block_time: 1234567890,
+                is_accepted: true,
+                inputs: [],
+                outputs: [],
+            };
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: () => Promise.resolve(mockResponse),
+            });
+            const api = new KaspaApi();
+            const result = await api.getTransaction('abc123');
+            expect(result).toEqual(mockResponse);
+            expect(mockFetch).toHaveBeenCalledWith('https://api.kaspa.org/transactions/abc123', expect.any(Object));
+        });
+        it('throws error on API failure', async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: false,
+                status: 404,
+                text: () => Promise.resolve('Not found'),
+            });
+            const api = new KaspaApi();
+            await expect(api.getTransaction('notfound')).rejects.toThrow('API error 404');
+        });
+    });
+    describe('uses correct endpoints for different networks', () => {
+        it('uses testnet-10 endpoint', async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: () => Promise.resolve({ priorityBucket: { feerate: 1 }, normalBuckets: [], lowBuckets: [] }),
+            });
+            const api = new KaspaApi('testnet-10');
+            await api.getFeeEstimate();
+            expect(mockFetch).toHaveBeenCalledWith('https://api-tn10.kaspa.org/info/fee-estimate', expect.any(Object));
+        });
+        it('uses testnet-11 endpoint', async () => {
+            mockFetch.mockResolvedValueOnce({
+                ok: true,
+                json: () => Promise.resolve({ priorityBucket: { feerate: 1 }, normalBuckets: [], lowBuckets: [] }),
+            });
+            const api = new KaspaApi('testnet-11');
+            await api.getFeeEstimate();
+            expect(mockFetch).toHaveBeenCalledWith('https://api-tn11.kaspa.org/info/fee-estimate', expect.any(Object));
+        });
+    });
+});
+describe('getApi', () => {
+    it('returns cached instance for same network', () => {
+        const api1 = getApi('mainnet');
+        const api2 = getApi('mainnet');
+        expect(api1).toBe(api2);
+    });
+    it('returns new instance for different network', () => {
+        const api1 = getApi('mainnet');
+        const api2 = getApi('testnet-10');
+        expect(api1).not.toBe(api2);
+    });
+});

package/dist/kaspa/setup.d.ts

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

package/dist/kaspa/setup.js

@@ -0,0 +1,4 @@
+// ABOUTME: WebSocket polyfill setup for Node.js environment
+// ABOUTME: Must be imported before any kaspa-wasm usage
+import WebSocket from 'isomorphic-ws';
+globalThis.WebSocket = WebSocket;

package/dist/kaspa/transaction.d.ts

@@ -0,0 +1,5 @@
+export interface SendResult {
+    txId: string;
+    fee: string;
+}
+export declare function sendKaspa(to: string, amountSompi: bigint, priorityFee?: bigint): Promise<SendResult>;

package/dist/kaspa/transaction.js

@@ -0,0 +1,60 @@
+// ABOUTME: Transaction building and submission module
+// ABOUTME: Uses kaspa-wasm Generator for KIP-9 compliant transaction creation
+import * as kaspa from 'kaspa-wasm';
+import { getApi } from './api.js';
+import { getWallet } from './wallet.js';
+const { Generator, RpcClient, Resolver, Encoding, sompiToKaspaString, Address, } = kaspa;
+export async function sendKaspa(to, amountSompi, priorityFee = 0n) {
+    const wallet = getWallet();
+    const senderAddress = wallet.getAddress();
+    const api = getApi(wallet.getNetworkId());
+    const rpc = new RpcClient({
+        resolver: new Resolver(),
+        encoding: Encoding.Borsh,
+        networkId: wallet.getNetworkId(),
+    });
+    await rpc.connect({});
+    try {
+        const { isSynced } = await rpc.getServerInfo();
+        if (!isSynced) {
+            throw new Error('RPC node is not synced');
+        }
+        // Fetch UTXOs via RPC - returns properly formatted UtxoEntry objects
+        const { entries } = await rpc.getUtxosByAddresses([new Address(senderAddress)]);
+        if (!entries || entries.length === 0) {
+            throw new Error('No UTXOs available');
+        }
+        // Check balance
+        const feeEstimate = await api.getFeeEstimate();
+        const totalBalance = entries.reduce((sum, e) => sum + e.amount, 0n);
+        const estimatedFee = BigInt(Math.ceil(feeEstimate.priorityBucket.feerate * 3000));
+        const totalRequired = amountSompi + estimatedFee + priorityFee;
+        if (totalBalance < totalRequired) {
+            throw new Error(`Insufficient balance: have ${sompiToKaspaString(totalBalance)} KAS, need ~${sompiToKaspaString(totalRequired)} KAS (including estimated fees)`);
+        }
+        // Sort UTXOs by amount (smallest first for efficient UTXO consolidation)
+        entries.sort((a, b) => (a.amount > b.amount ? 1 : -1));
+        // Create generator with RPC-provided UTXOs
+        const generator = new Generator({
+            entries,
+            outputs: [{ address: to, amount: amountSompi }],
+            priorityFee,
+            changeAddress: senderAddress,
+            networkId: wallet.getNetworkId(),
+        });
+        let pending;
+        let lastTxId = '';
+        while ((pending = await generator.next())) {
+            await pending.sign([wallet.getPrivateKey()]);
+            lastTxId = await pending.submit(rpc);
+        }
+        const summary = generator.summary();
+        return {
+            txId: lastTxId,
+            fee: sompiToKaspaString(summary.fees).toString(),
+        };
+    }
+    finally {
+        await rpc.disconnect();
+    }
+}

package/dist/kaspa/transaction.test.d.ts

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

package/dist/kaspa/transaction.test.js

@@ -0,0 +1,170 @@
+// ABOUTME: Unit tests for transaction module
+// ABOUTME: Tests transaction building, signing, and submission
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+const mockRpcClient = {
+    connect: vi.fn(),
+    disconnect: vi.fn(),
+    getServerInfo: vi.fn(),
+    getUtxosByAddresses: vi.fn(),
+};
+const mockPendingTransaction = {
+    sign: vi.fn(),
+    submit: vi.fn(),
+};
+const mockGenerator = {
+    next: vi.fn(),
+    summary: vi.fn(),
+};
+vi.mock('kaspa-wasm', () => {
+    class MockAddress {
+        address;
+        constructor(addr) {
+            this.address = addr;
+        }
+    }
+    class MockResolver {
+    }
+    class MockRpcClient {
+        constructor() {
+            return mockRpcClient;
+        }
+    }
+    class MockGenerator {
+        constructor() {
+            return mockGenerator;
+        }
+    }
+    return {
+        Address: MockAddress,
+        Resolver: MockResolver,
+        RpcClient: MockRpcClient,
+        Generator: MockGenerator,
+        Encoding: { Borsh: 'borsh' },
+        sompiToKaspaString: (sompi) => {
+            const kas = Number(sompi) / 100_000_000;
+            return kas.toString();
+        },
+    };
+});
+vi.mock('./wallet.js', () => ({
+    getWallet: vi.fn(),
+}));
+vi.mock('./api.js', () => ({
+    getApi: vi.fn(),
+}));
+import { sendKaspa } from './transaction.js';
+import { getWallet } from './wallet.js';
+import { getApi } from './api.js';
+describe('sendKaspa', () => {
+    const mockWallet = {
+        getAddress: vi.fn(),
+        getNetworkId: vi.fn(),
+        getPrivateKey: vi.fn(),
+    };
+    const mockApi = {
+        getFeeEstimate: vi.fn(),
+    };
+    beforeEach(() => {
+        vi.mocked(getWallet).mockReturnValue(mockWallet);
+        vi.mocked(getApi).mockReturnValue(mockApi);
+        mockWallet.getAddress.mockReturnValue('kaspa:qpwallet123');
+        mockWallet.getNetworkId.mockReturnValue('testnet-10');
+        mockWallet.getPrivateKey.mockReturnValue({ key: 'privatekey' });
+        mockApi.getFeeEstimate.mockResolvedValue({
+            priorityBucket: { feerate: 1.0 },
+        });
+        mockRpcClient.connect.mockResolvedValue(undefined);
+        mockRpcClient.disconnect.mockResolvedValue(undefined);
+        mockRpcClient.getServerInfo.mockResolvedValue({ isSynced: true });
+        mockRpcClient.getUtxosByAddresses.mockResolvedValue({
+            entries: [{ amount: 1000000000n }],
+        });
+        mockPendingTransaction.sign.mockResolvedValue(undefined);
+        mockPendingTransaction.submit.mockResolvedValue('txid123');
+        mockGenerator.next
+            .mockResolvedValueOnce(mockPendingTransaction)
+            .mockResolvedValueOnce(undefined);
+        mockGenerator.summary.mockReturnValue({ fees: 1000n });
+    });
+    afterEach(() => {
+        vi.clearAllMocks();
+    });
+    it('sends transaction successfully', async () => {
+        const result = await sendKaspa('kaspa:qprecipient', 100000000n, 0n);
+        expect(result).toEqual({
+            txId: 'txid123',
+            fee: '0.00001',
+        });
+        expect(mockRpcClient.connect).toHaveBeenCalledWith({});
+        expect(mockRpcClient.getServerInfo).toHaveBeenCalled();
+        expect(mockRpcClient.disconnect).toHaveBeenCalled();
+    });
+    it('throws error when RPC is not synced', async () => {
+        mockRpcClient.getServerInfo.mockResolvedValue({ isSynced: false });
+        await expect(sendKaspa('kaspa:qprecipient', 100000000n)).rejects.toThrow('RPC node is not synced');
+        expect(mockRpcClient.disconnect).toHaveBeenCalled();
+    });
+    it('throws error when no UTXOs available', async () => {
+        mockRpcClient.getUtxosByAddresses.mockResolvedValue({ entries: [] });
+        await expect(sendKaspa('kaspa:qprecipient', 100000000n)).rejects.toThrow('No UTXOs available');
+    });
+    it('throws error when entries is undefined', async () => {
+        mockRpcClient.getUtxosByAddresses.mockResolvedValue({ entries: undefined });
+        await expect(sendKaspa('kaspa:qprecipient', 100000000n)).rejects.toThrow('No UTXOs available');
+    });
+    it('throws error for insufficient balance', async () => {
+        mockRpcClient.getUtxosByAddresses.mockResolvedValue({
+            entries: [{ amount: 1000n }],
+        });
+        await expect(sendKaspa('kaspa:qprecipient', 100000000n)).rejects.toThrow(/Insufficient balance/);
+    });
+    it('uses priority fee when provided', async () => {
+        mockRpcClient.getUtxosByAddresses.mockResolvedValue({
+            entries: [{ amount: 2000000000n }],
+        });
+        await sendKaspa('kaspa:qprecipient', 100000000n, 1000n);
+        expect(mockPendingTransaction.sign).toHaveBeenCalled();
+    });
+    it('disconnects RPC even on error', async () => {
+        mockRpcClient.getServerInfo.mockRejectedValue(new Error('Connection failed'));
+        await expect(sendKaspa('kaspa:qprecipient', 100000000n)).rejects.toThrow('Connection failed');
+        expect(mockRpcClient.disconnect).toHaveBeenCalled();
+    });
+    it('handles multiple pending transactions', async () => {
+        const mockPending1 = { sign: vi.fn(), submit: vi.fn().mockResolvedValue('tx1') };
+        const mockPending2 = { sign: vi.fn(), submit: vi.fn().mockResolvedValue('tx2') };
+        mockGenerator.next
+            .mockReset()
+            .mockResolvedValueOnce(mockPending1)
+            .mockResolvedValueOnce(mockPending2)
+            .mockResolvedValueOnce(undefined);
+        mockRpcClient.getUtxosByAddresses.mockResolvedValue({
+            entries: [{ amount: 5000000000n }],
+        });
+        const result = await sendKaspa('kaspa:qprecipient', 100000000n);
+        expect(result.txId).toBe('tx2');
+        expect(mockPending1.sign).toHaveBeenCalled();
+        expect(mockPending2.sign).toHaveBeenCalled();
+    });
+    it('sorts UTXOs by amount (smallest first)', async () => {
+        const entries = [
+            { amount: 3000000000n },
+            { amount: 1000000000n },
+            { amount: 2000000000n },
+        ];
+        mockRpcClient.getUtxosByAddresses.mockResolvedValue({ entries });
+        await sendKaspa('kaspa:qprecipient', 100000000n);
+        expect(entries[0].amount).toBe(1000000000n);
+        expect(entries[1].amount).toBe(2000000000n);
+        expect(entries[2].amount).toBe(3000000000n);
+    });
+    it('uses correct API for network', async () => {
+        mockWallet.getNetworkId.mockReturnValue('mainnet');
+        await sendKaspa('kaspa:qprecipient', 100000000n);
+        expect(getApi).toHaveBeenCalledWith('mainnet');
+    });
+    it('defaults priority fee to 0', async () => {
+        const result = await sendKaspa('kaspa:qprecipient', 100000000n);
+        expect(result).toBeDefined();
+    });
+});

package/dist/kaspa/wallet.d.ts

@@ -0,0 +1,15 @@
+import * as kaspa from 'kaspa-wasm';
+export type NetworkTypeName = 'mainnet' | 'testnet-10' | 'testnet-11';
+export declare class KaspaWallet {
+    private privateKey;
+    private keypair;
+    private network;
+    private constructor();
+    static fromPrivateKey(privateKeyHex: string, network?: NetworkTypeName): KaspaWallet;
+    static fromMnemonic(phrase: string, network?: NetworkTypeName, accountIndex?: number): KaspaWallet;
+    getAddress(): string;
+    getPrivateKey(): kaspa.PrivateKey;
+    getNetworkType(): kaspa.NetworkType;
+    getNetworkId(): string;
+}
+export declare function getWallet(): KaspaWallet;

package/dist/kaspa/wallet.js

@@ -0,0 +1,97 @@
+// ABOUTME: Wallet module for key management and address derivation
+// ABOUTME: Supports both mnemonic (BIP39) and raw private key
+import * as kaspa from 'kaspa-wasm';
+const { PrivateKey, NetworkType, Mnemonic, XPrv, PrivateKeyGenerator } = kaspa;
+function getNetworkType(network) {
+    switch (network) {
+        case 'mainnet':
+            return NetworkType.Mainnet;
+        case 'testnet-10':
+        case 'testnet-11':
+            return NetworkType.Testnet;
+        /* c8 ignore next 2 */
+        default:
+            return NetworkType.Mainnet;
+    }
+}
+function derivePrivateKeyFromMnemonic(phrase, accountIndex = 0) {
+    const mnemonic = new Mnemonic(phrase);
+    const seed = mnemonic.toSeed();
+    const xprv = new XPrv(seed);
+    // BIP44 path: m/44'/111111'/account'
+    // 44' = purpose (BIP44)
+    // 111111' = Kaspa coin type
+    const derived = xprv
+        .deriveChild(44, true)
+        .deriveChild(111111, true)
+        .deriveChild(accountIndex, true);
+    const xprvString = derived.intoString('xprv');
+    const privateKeyGenerator = new PrivateKeyGenerator(xprvString, false, BigInt(accountIndex));
+    return privateKeyGenerator.receiveKey(0);
+}
+export class KaspaWallet {
+    privateKey;
+    keypair;
+    network;
+    constructor(privateKey, network) {
+        this.privateKey = privateKey;
+        this.keypair = privateKey.toKeypair();
+        this.network = network;
+    }
+    static fromPrivateKey(privateKeyHex, network = 'mainnet') {
+        if (!privateKeyHex) {
+            throw new Error('Private key is required');
+        }
+        try {
+            const privateKey = new PrivateKey(privateKeyHex);
+            return new KaspaWallet(privateKey, network);
+        }
+        catch {
+            throw new Error('Invalid private key format');
+        }
+    }
+    static fromMnemonic(phrase, network = 'mainnet', accountIndex = 0) {
+        if (!phrase) {
+            throw new Error('Mnemonic phrase is required');
+        }
+        try {
+            const privateKey = derivePrivateKeyFromMnemonic(phrase, accountIndex);
+            return new KaspaWallet(privateKey, network);
+        }
+        catch {
+            throw new Error('Invalid mnemonic phrase');
+        }
+    }
+    getAddress() {
+        const networkType = getNetworkType(this.network);
+        return this.keypair.toAddress(networkType).toString();
+    }
+    getPrivateKey() {
+        return this.privateKey;
+    }
+    getNetworkType() {
+        return getNetworkType(this.network);
+    }
+    getNetworkId() {
+        return this.network;
+    }
+}
+let walletInstance = null;
+export function getWallet() {
+    if (!walletInstance) {
+        const mnemonic = process.env.KASPA_MNEMONIC;
+        const privateKey = process.env.KASPA_PRIVATE_KEY;
+        const network = process.env.KASPA_NETWORK || 'mainnet';
+        const accountIndex = parseInt(process.env.KASPA_ACCOUNT_INDEX || '0', 10);
+        if (mnemonic) {
+            walletInstance = KaspaWallet.fromMnemonic(mnemonic, network, accountIndex);
+        }
+        else if (privateKey) {
+            walletInstance = KaspaWallet.fromPrivateKey(privateKey, network);
+        }
+        else {
+            throw new Error('Either KASPA_MNEMONIC or KASPA_PRIVATE_KEY environment variable must be set');
+        }
+    }
+    return walletInstance;
+}

package/dist/kaspa/wallet.test.d.ts

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