kasia-mcp 0.1.0

package/README.md

@@ -0,0 +1 @@
+# kasia-mcp

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import 'kaspa-mcp/kaspa/setup';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+declare const server: McpServer;
+export { server };

package/dist/index.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// ABOUTME: MCP server entry point for Kasia encrypted messaging
+// ABOUTME: Registers all tools and starts the stdio transport
+import 'kaspa-mcp/kaspa/setup';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { getWallet } from 'kaspa-mcp/kaspa/wallet';
+import { wrapToolHandler } from 'kaspa-mcp/wrap-tool-handler';
+import { sendHandshake } from './tools/send-handshake.js';
+import { acceptHandshake } from './tools/accept-handshake.js';
+import { sendMessage } from './tools/send-message.js';
+import { writeSelfStash } from './tools/write-self-stash.js';
+import { getConversations } from './tools/get-conversations.js';
+import { getRequests } from './tools/get-requests.js';
+import { getMessages } from './tools/get-messages.js';
+import { readSelfStash } from './tools/read-self-stash.js';
+const server = new McpServer({
+    name: 'kasia-mcp',
+    version: '0.1.0',
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Write tools — return KasiaWriteResult with payload for send_kaspa delegation
+server.tool('kasia_send_handshake', 'Start a Kasia encrypted conversation with a Kaspa address. Returns a transaction payload — use send_kaspa to broadcast it.', {
+    address: z.string().describe('Recipient Kaspa address to start a conversation with'),
+}, async (params) => wrapToolHandler(() => sendHandshake({ address: params.address })));
+server.tool('kasia_accept_handshake', 'Accept an incoming Kasia handshake request. Returns a transaction payload — use send_kaspa to broadcast it.', {
+    address: z.string().describe('Address of the person who sent the handshake'),
+}, async (params) => wrapToolHandler(() => acceptHandshake({ address: params.address })));
+server.tool('kasia_send_message', 'Send an encrypted message in a Kasia conversation. Returns a transaction payload — use send_kaspa to broadcast it.', {
+    address: z.string().describe('Contact Kaspa address to send the message to'),
+    message: z.string().describe('Message text to encrypt and send'),
+}, async (params) => wrapToolHandler(() => sendMessage({ address: params.address, message: params.message })));
+server.tool('kasia_write_self_stash', 'Store encrypted data on-chain for yourself. Returns a transaction payload — use send_kaspa to broadcast it.', {
+    data: z.string().describe('Data to encrypt and store'),
+    scope: z.string().describe('Scope/category for the stash entry (e.g. "saved_handshake", "notes")'),
+}, async (params) => wrapToolHandler(() => writeSelfStash({ data: params.data, scope: params.scope })));
+// Read tools — query indexer and decrypt
+server.tool('kasia_get_conversations', 'List all Kasia conversations with their status (pending_outgoing, pending_incoming, active).', async () => wrapToolHandler(() => getConversations()));
+server.tool('kasia_get_requests', 'List pending incoming handshake requests that need to be accepted.', async () => wrapToolHandler(() => getRequests()));
+server.tool('kasia_get_messages', 'Read decrypted messages in a Kasia conversation, sorted by time.', {
+    address: z.string().describe('Contact Kaspa address to read messages from'),
+}, async (params) => wrapToolHandler(() => getMessages({ address: params.address })));
+server.tool('kasia_read_self_stash', 'Read your encrypted self-stash entries by scope.', {
+    scope: z.string().describe('Scope/category to read (e.g. "saved_handshake", "notes")'),
+}, async (params) => wrapToolHandler(() => readSelfStash({ scope: params.scope })));
+async function main() {
+    const wallet = getWallet();
+    if (wallet.getNetworkId() !== 'mainnet') {
+        throw new Error('Kasia messaging is only available on mainnet');
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Kasia MCP server started');
+}
+main().catch((error) => {
+    const safeMessage = error instanceof Error ? error.message : 'Unknown error';
+    console.error('Fatal error:', safeMessage);
+    process.exit(1);
+});
+export { server };

package/dist/kasia/alias.d.ts

@@ -0,0 +1,5 @@
+export interface Aliases {
+    myAlias: string;
+    theirAlias: string;
+}
+export declare function deriveAliases(myPrivateKeyHex: string, theirAddress: string): Promise<Aliases>;

package/dist/kasia/alias.js

@@ -0,0 +1,46 @@
+// ABOUTME: Deterministic alias derivation for Kasia conversations
+// ABOUTME: ECDH + HKDF with asymmetric context pubkeys (68-byte info: "chat" || shared_secret || context_pubkey)
+import * as crypto from 'node:crypto';
+import { extractXOnlyPubkeyFromAddress } from './crypto.js';
+const ALIAS_BYTE_LENGTH = 6;
+export async function deriveAliases(myPrivateKeyHex, theirAddress) {
+    const ecdh = crypto.createECDH('secp256k1');
+    ecdh.setPrivateKey(Buffer.from(myPrivateKeyHex, 'hex'));
+    const myXOnlyPubkey = ecdh.getPublicKey(null, 'compressed').subarray(1); // strip prefix
+    const theirXOnlyPubkey = extractXOnlyPubkeyFromAddress(theirAddress);
+    const theirCompressed = Buffer.concat([Buffer.from([0x02]), theirXOnlyPubkey]);
+    const sharedSecret = ecdh.computeSecret(theirCompressed);
+    const myAlias = deriveAlias(sharedSecret, myXOnlyPubkey);
+    const theirAlias = deriveAlias(sharedSecret, theirXOnlyPubkey);
+    return { myAlias, theirAlias };
+}
+function deriveAlias(sharedSecret, contextPubkey) {
+    // HKDF-Extract: PRK = HMAC-SHA256(salt=empty, ikm=shared_secret)
+    const prk = crypto.createHmac('sha256', Buffer.alloc(0))
+        .update(sharedSecret)
+        .digest();
+    // Construct info: "chat" (4) || shared_secret (32) || context_pubkey (32) = 68 bytes
+    const info = Buffer.alloc(68);
+    info.set(Buffer.from('chat', 'utf-8'), 0);
+    info.set(sharedSecret, 4);
+    info.set(contextPubkey, 36);
+    // HKDF-Expand: output 6 bytes
+    const aliasBytes = hkdfExpand(prk, info, ALIAS_BYTE_LENGTH);
+    return aliasBytes.toString('hex');
+}
+function hkdfExpand(prk, info, length) {
+    // RFC 5869 HKDF-Expand
+    const hashLen = 32; // SHA-256
+    const n = Math.ceil(length / hashLen);
+    const output = Buffer.alloc(n * hashLen);
+    let prev = Buffer.alloc(0);
+    for (let i = 1; i <= n; i++) {
+        const hmac = crypto.createHmac('sha256', prk);
+        hmac.update(prev);
+        hmac.update(info);
+        hmac.update(Buffer.from([i]));
+        prev = Buffer.from(hmac.digest());
+        prev.copy(output, (i - 1) * hashLen);
+    }
+    return output.subarray(0, length);
+}

package/dist/kasia/alias.test.d.ts

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

package/dist/kasia/alias.test.js

@@ -0,0 +1,27 @@
+// ABOUTME: Tests for deterministic alias derivation
+// ABOUTME: Verifies 12-char hex format, asymmetric outputs, and determinism
+import { describe, it, expect } from 'vitest';
+import { deriveAliases } from './alias.js';
+describe('alias', () => {
+    // Two keypairs for testing asymmetric property
+    const alicePrivateKey = 'e8f32e723decf4051aefac8e2c93c9c5b214313817cdb01a1494b917c8436b35';
+    // Bob's address must be different from Alice's to produce distinct aliases
+    const bobAddress = 'kaspa:qq258y97v6uc26jqhztw49v9xh6wa85fc8sd5zqxz9jmhkky4pnvvgc3z08eq';
+    it('derives 12-character hex aliases', async () => {
+        const { myAlias, theirAlias } = await deriveAliases(alicePrivateKey, bobAddress);
+        expect(myAlias).toHaveLength(12);
+        expect(theirAlias).toHaveLength(12);
+        expect(myAlias).toMatch(/^[0-9a-f]{12}$/);
+        expect(theirAlias).toMatch(/^[0-9a-f]{12}$/);
+    });
+    it('produces different myAlias and theirAlias', async () => {
+        const { myAlias, theirAlias } = await deriveAliases(alicePrivateKey, bobAddress);
+        expect(myAlias).not.toBe(theirAlias);
+    });
+    it('is deterministic', async () => {
+        const result1 = await deriveAliases(alicePrivateKey, bobAddress);
+        const result2 = await deriveAliases(alicePrivateKey, bobAddress);
+        expect(result1.myAlias).toBe(result2.myAlias);
+        expect(result1.theirAlias).toBe(result2.theirAlias);
+    });
+});

package/dist/kasia/crypto.d.ts

@@ -0,0 +1,3 @@
+export declare function extractXOnlyPubkeyFromAddress(address: string): Buffer;
+export declare function encrypt(plaintext: string, recipientAddress: string): Promise<Buffer>;
+export declare function decrypt(encrypted: Buffer, privateKeyHex: string): Promise<string>;

package/dist/kasia/crypto.js

@@ -0,0 +1,127 @@
+// ABOUTME: Kasia message encryption and decryption using Node.js crypto
+// ABOUTME: ECDH on secp256k1, HKDF-SHA256, ChaCha20-Poly1305 AEAD
+import * as crypto from 'node:crypto';
+const NONCE_LENGTH = 12;
+const COMPRESSED_PUBKEY_LENGTH = 33;
+const X_ONLY_PUBKEY_LENGTH = 32;
+const MAC_LENGTH = 16;
+const HKDF_KEY_LENGTH = 32;
+const BECH32_CHECKSUM_LENGTH = 8;
+// Kaspa bech32 character set for address encoding
+const BECH32_CHARSET = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l';
+function convertBits(data, fromBits, toBits) {
+    let acc = 0;
+    let bits = 0;
+    const result = [];
+    const maxv = (1 << toBits) - 1;
+    for (const value of data) {
+        /* v8 ignore next -- @preserve */
+        if (value < 0 || (value >> fromBits) !== 0)
+            return null;
+        acc = (acc << fromBits) | value;
+        bits += fromBits;
+        while (bits >= toBits) {
+            bits -= toBits;
+            result.push((acc >> bits) & maxv);
+        }
+    }
+    if (bits >= fromBits || ((acc << (toBits - bits)) & maxv)) {
+        return null;
+    }
+    return result;
+}
+export function extractXOnlyPubkeyFromAddress(address) {
+    const colonIndex = address.indexOf(':');
+    if (colonIndex === -1) {
+        throw new Error('Invalid Kaspa address: missing prefix separator');
+    }
+    const payload = address.substring(colonIndex + 1);
+    if (payload.length < BECH32_CHECKSUM_LENGTH + 2) {
+        throw new Error('Invalid Kaspa address: payload too short');
+    }
+    const data5bit = [];
+    for (const c of payload) {
+        const idx = BECH32_CHARSET.indexOf(c);
+        if (idx === -1) {
+            throw new Error(`Invalid Kaspa address: invalid character '${c}'`);
+        }
+        data5bit.push(idx);
+    }
+    // Strip the 8-character bech32 checksum
+    const dataWithoutChecksum = data5bit.slice(0, -BECH32_CHECKSUM_LENGTH);
+    const bytes = convertBits(dataWithoutChecksum, 5, 8);
+    if (!bytes || bytes.length < 2) {
+        throw new Error('Invalid Kaspa address: failed to decode payload');
+    }
+    // First byte is the version (0 = PubKey), rest is the x-only pubkey
+    const pubkeyBytes = bytes.slice(1);
+    if (pubkeyBytes.length !== X_ONLY_PUBKEY_LENGTH) {
+        throw new Error(`Invalid Kaspa address: expected ${X_ONLY_PUBKEY_LENGTH} byte pubkey, got ${pubkeyBytes.length}`);
+    }
+    return Buffer.from(pubkeyBytes);
+}
+export async function encrypt(plaintext, recipientAddress) {
+    const xOnlyPubkey = extractXOnlyPubkeyFromAddress(recipientAddress);
+    const recipientCompressed = Buffer.concat([Buffer.from([0x02]), xOnlyPubkey]);
+    const ephemeral = crypto.createECDH('secp256k1');
+    ephemeral.generateKeys();
+    const ephemeralPubkey = ephemeral.getPublicKey(null, 'compressed');
+    const sharedSecret = ephemeral.computeSecret(recipientCompressed);
+    const key = crypto.hkdfSync('sha256', sharedSecret, Buffer.alloc(0), Buffer.alloc(0), HKDF_KEY_LENGTH);
+    const nonce = crypto.randomBytes(NONCE_LENGTH);
+    const cipher = crypto.createCipheriv('chacha20-poly1305', Buffer.from(key), nonce, { authTagLength: MAC_LENGTH });
+    const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf-8'), cipher.final()]);
+    const mac = cipher.getAuthTag();
+    return Buffer.concat([nonce, ephemeralPubkey, ciphertext, mac]);
+}
+export async function decrypt(encrypted, privateKeyHex) {
+    const minLength = NONCE_LENGTH + X_ONLY_PUBKEY_LENGTH + 1 + MAC_LENGTH;
+    if (encrypted.length < minLength) {
+        throw new Error(`Encrypted payload too short: ${encrypted.length} bytes (minimum ${minLength})`);
+    }
+    const nonce = encrypted.subarray(0, NONCE_LENGTH);
+    const possiblePrefix = encrypted[NONCE_LENGTH];
+    const isCompressed = possiblePrefix === 0x02 || possiblePrefix === 0x03;
+    let ephemeralPubkey;
+    let ciphertextAndMac;
+    if (isCompressed && encrypted.length >= NONCE_LENGTH + COMPRESSED_PUBKEY_LENGTH + 1 + MAC_LENGTH) {
+        ephemeralPubkey = Buffer.from(encrypted.subarray(NONCE_LENGTH, NONCE_LENGTH + COMPRESSED_PUBKEY_LENGTH));
+        ciphertextAndMac = encrypted.subarray(NONCE_LENGTH + COMPRESSED_PUBKEY_LENGTH);
+    }
+    else {
+        ephemeralPubkey = Buffer.concat([
+            Buffer.from([0x02]),
+            encrypted.subarray(NONCE_LENGTH, NONCE_LENGTH + X_ONLY_PUBKEY_LENGTH),
+        ]);
+        ciphertextAndMac = encrypted.subarray(NONCE_LENGTH + X_ONLY_PUBKEY_LENGTH);
+    }
+    const ciphertext = ciphertextAndMac.subarray(0, ciphertextAndMac.length - MAC_LENGTH);
+    const mac = ciphertextAndMac.subarray(ciphertextAndMac.length - MAC_LENGTH);
+    try {
+        return decryptWithPubkey(nonce, ephemeralPubkey, ciphertext, mac, privateKeyHex);
+    }
+    catch (e) {
+        // ECDH shared secrets are identical regardless of y-parity in secp256k1 (Node.js
+        // computeSecret returns the x-coordinate only), so this fallback is a defensive
+        // guard that cannot be reached in practice with standard ECDH implementations.
+        /* v8 ignore next 6 -- @preserve */
+        if (!isCompressed) {
+            const oddPubkey = Buffer.concat([
+                Buffer.from([0x03]),
+                encrypted.subarray(NONCE_LENGTH, NONCE_LENGTH + X_ONLY_PUBKEY_LENGTH),
+            ]);
+            return decryptWithPubkey(nonce, oddPubkey, ciphertext, mac, privateKeyHex);
+        }
+        throw e;
+    }
+}
+function decryptWithPubkey(nonce, ephemeralPubkey, ciphertext, mac, privateKeyHex) {
+    const ecdh = crypto.createECDH('secp256k1');
+    ecdh.setPrivateKey(Buffer.from(privateKeyHex, 'hex'));
+    const sharedSecret = ecdh.computeSecret(ephemeralPubkey);
+    const key = crypto.hkdfSync('sha256', sharedSecret, Buffer.alloc(0), Buffer.alloc(0), HKDF_KEY_LENGTH);
+    const decipher = crypto.createDecipheriv('chacha20-poly1305', Buffer.from(key), nonce, { authTagLength: MAC_LENGTH });
+    decipher.setAuthTag(mac);
+    const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    return decrypted.toString('utf-8');
+}

package/dist/kasia/crypto.test.d.ts

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

package/dist/kasia/crypto.test.js

@@ -0,0 +1,93 @@
+// ABOUTME: Tests for Kasia encryption/decryption using Node.js crypto
+// ABOUTME: Verifies round-trip encrypt/decrypt, ephemeral key uniqueness, parity fallback
+import { describe, it, expect } from 'vitest';
+import { encrypt, decrypt, extractXOnlyPubkeyFromAddress } from './crypto.js';
+describe('crypto', () => {
+    // Use a known secp256k1 keypair for deterministic testing
+    const privateKeyHex = 'e8f32e723decf4051aefac8e2c93c9c5b214313817cdb01a1494b917c8436b35';
+    // Address derived from the above private key on mainnet
+    const address = 'kaspa:qqu6xcqnxq2e0kh0g8a7tyaq9nz3859425n7ct03q58zarl5njzuy4wlaj98w';
+    describe('extractXOnlyPubkeyFromAddress', () => {
+        it('extracts the correct x-only pubkey from a mainnet address', () => {
+            const pubkey = extractXOnlyPubkeyFromAddress(address);
+            expect(pubkey.toString('hex')).toBe('39a36013301597daef41fbe593a02cc513d0b55527ec2df1050e2e8ff49c85c2');
+            expect(pubkey.length).toBe(32);
+        });
+        it('extracts the correct x-only pubkey from a testnet address', () => {
+            const testnetAddress = 'kaspatest:qqd6e65yefepe9wk0m9vuxdufxd80sphy67gwwd0vdaumzdt4tc9ssxd5s7gn';
+            const pubkey = extractXOnlyPubkeyFromAddress(testnetAddress);
+            expect(pubkey.toString('hex')).toBe('1bacea84ca721c95d67ecace19bc499a77c03726bc8739af637bcd89abaaf058');
+        });
+        it('throws on address without prefix separator', () => {
+            expect(() => extractXOnlyPubkeyFromAddress('noprefix')).toThrow('missing prefix separator');
+        });
+        it('throws on address with payload too short', () => {
+            expect(() => extractXOnlyPubkeyFromAddress('kaspa:q')).toThrow('payload too short');
+        });
+        it('throws on address with invalid bech32 characters', () => {
+            expect(() => extractXOnlyPubkeyFromAddress('kaspa:qINVALID' + 'q'.repeat(60))).toThrow('invalid character');
+        });
+        it('throws on address with non-zero trailing bits in bech32 data', () => {
+            // Changing the last data character from 'y' (0b01100) to 'p' (0b00001) creates
+            // a non-zero trailing bit that makes the 5-to-8-bit conversion fail
+            const badAddr = 'kaspa:qqu6xcqnxq2e0kh0g8a7tyaq9nz3859425n7ct03q58zarl5njzup4wlaj98w';
+            expect(() => extractXOnlyPubkeyFromAddress(badAddr)).toThrow('failed to decode');
+        });
+        it('throws on address with wrong pubkey length', () => {
+            // A shorter payload that decodes to 29 bytes instead of 32
+            const shortAddr = 'kaspa:' + 'q'.repeat(56);
+            expect(() => extractXOnlyPubkeyFromAddress(shortAddr)).toThrow('expected 32 byte pubkey');
+        });
+    });
+    describe('encrypt', () => {
+        it('encrypts and decrypts a message round-trip', async () => {
+            const plaintext = 'Hello Kasia!';
+            const encrypted = await encrypt(plaintext, address);
+            expect(encrypted).toBeInstanceOf(Buffer);
+            // nonce(12) + pubkey(33) + ciphertext(>=1) + mac(16) >= 62
+            expect(encrypted.length).toBeGreaterThanOrEqual(62);
+            const decrypted = await decrypt(encrypted, privateKeyHex);
+            expect(decrypted).toBe(plaintext);
+        });
+        it('produces different ciphertext each time (ephemeral keys)', async () => {
+            const plaintext = 'determinism test';
+            const enc1 = await encrypt(plaintext, address);
+            const enc2 = await encrypt(plaintext, address);
+            expect(enc1).not.toEqual(enc2);
+        });
+    });
+    describe('decrypt', () => {
+        it('decrypts with parity fallback for x-only pubkeys', async () => {
+            // Build a payload with 32-byte x-only ephemeral pubkey (strip prefix)
+            const plaintext = 'parity test';
+            const fullEncrypted = await encrypt(plaintext, address);
+            // Strip the 0x02/0x03 prefix byte from ephemeral pubkey
+            const nonce = fullEncrypted.subarray(0, 12);
+            const pubkey33 = fullEncrypted.subarray(12, 45);
+            const ciphertextAndMac = fullEncrypted.subarray(45);
+            const xOnlyPubkey = pubkey33.subarray(1); // 32 bytes, strip prefix
+            const xOnlyPayload = Buffer.concat([nonce, xOnlyPubkey, ciphertextAndMac]);
+            const decrypted = await decrypt(xOnlyPayload, privateKeyHex);
+            expect(decrypted).toBe(plaintext);
+        });
+        it('throws on encrypted payload that is too short', async () => {
+            await expect(decrypt(Buffer.from('too short'), privateKeyHex)).rejects.toThrow('Encrypted payload too short');
+        });
+        it('decrypts payload with compressed ephemeral pubkey (0x02 prefix)', async () => {
+            const plaintext = 'compressed even';
+            const encrypted = await encrypt(plaintext, address);
+            // encrypt() always produces compressed pubkeys, so this is the normal path
+            expect(encrypted[12]).toBeGreaterThanOrEqual(0x02);
+            expect(encrypted[12]).toBeLessThanOrEqual(0x03);
+            const decrypted = await decrypt(encrypted, privateKeyHex);
+            expect(decrypted).toBe(plaintext);
+        });
+        it('throws when compressed pubkey decryption fails with wrong key', async () => {
+            const plaintext = 'wrong key test';
+            const encrypted = await encrypt(plaintext, address);
+            // Use a different private key that won't produce the correct shared secret
+            const wrongKeyHex = '0000000000000000000000000000000000000000000000000000000000000001';
+            await expect(decrypt(encrypted, wrongKeyHex)).rejects.toThrow();
+        });
+    });
+});

package/dist/kasia/indexer.d.ts

@@ -0,0 +1,13 @@
+import type { HandshakeResponse, ContextualMessageResponse, PaymentResponse, SelfStashResponse } from '../types.js';
+export declare class KasiaIndexer {
+    private baseUrl;
+    constructor(baseUrl: string);
+    getHandshakesBySender(address: string, limit?: number, blockTime?: number): Promise<HandshakeResponse[]>;
+    getHandshakesByReceiver(address: string, limit?: number, blockTime?: number): Promise<HandshakeResponse[]>;
+    getMessagesBySender(address: string, alias: string, limit?: number, blockTime?: number): Promise<ContextualMessageResponse[]>;
+    getPaymentsBySender(address: string, limit?: number, blockTime?: number): Promise<PaymentResponse[]>;
+    getPaymentsByReceiver(address: string, limit?: number, blockTime?: number): Promise<PaymentResponse[]>;
+    getSelfStashByOwner(address: string, scope: string, limit?: number, blockTime?: number): Promise<SelfStashResponse[]>;
+    private fetch;
+}
+export declare function getIndexer(): KasiaIndexer;

package/dist/kasia/indexer.js

@@ -0,0 +1,63 @@
+// ABOUTME: HTTP client for the Kasia indexer API
+// ABOUTME: Handles all read operations against the messaging indexer at indexer.kasia.fyi
+const DEFAULT_INDEXER_URL = 'https://indexer.kasia.fyi';
+const DEFAULT_LIMIT = 50;
+function hexEncodeString(str) {
+    return Buffer.from(str, 'utf-8').toString('hex');
+}
+export class KasiaIndexer {
+    baseUrl;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+    }
+    async getHandshakesBySender(address, limit = DEFAULT_LIMIT, blockTime = 0) {
+        return this.fetch('/handshakes/by-sender', { address, limit: String(limit), block_time: String(blockTime) });
+    }
+    async getHandshakesByReceiver(address, limit = DEFAULT_LIMIT, blockTime = 0) {
+        return this.fetch('/handshakes/by-receiver', { address, limit: String(limit), block_time: String(blockTime) });
+    }
+    async getMessagesBySender(address, alias, limit = DEFAULT_LIMIT, blockTime = 0) {
+        return this.fetch('/contextual-messages/by-sender', {
+            address,
+            alias: hexEncodeString(alias),
+            limit: String(limit),
+            block_time: String(blockTime),
+        });
+    }
+    async getPaymentsBySender(address, limit = DEFAULT_LIMIT, blockTime = 0) {
+        return this.fetch('/payments/by-sender', { address, limit: String(limit), block_time: String(blockTime) });
+    }
+    async getPaymentsByReceiver(address, limit = DEFAULT_LIMIT, blockTime = 0) {
+        return this.fetch('/payments/by-receiver', { address, limit: String(limit), block_time: String(blockTime) });
+    }
+    async getSelfStashByOwner(address, scope, limit = DEFAULT_LIMIT, blockTime = 0) {
+        return this.fetch('/self-stash/by-owner', {
+            owner: address,
+            scope: hexEncodeString(scope),
+            limit: String(limit),
+            block_time: String(blockTime),
+        });
+    }
+    async fetch(path, params) {
+        const url = new URL(path, this.baseUrl);
+        for (const [key, value] of Object.entries(params)) {
+            url.searchParams.set(key, value);
+        }
+        const response = await globalThis.fetch(url.toString(), {
+            method: 'GET',
+            headers: { 'Accept': 'application/json' },
+        });
+        if (!response.ok) {
+            throw new Error(`Indexer API error: ${response.status} ${response.statusText}`);
+        }
+        return response.json();
+    }
+}
+let indexerInstance = null;
+export function getIndexer() {
+    if (!indexerInstance) {
+        const url = process.env.KASIA_INDEXER_URL || DEFAULT_INDEXER_URL;
+        indexerInstance = new KasiaIndexer(url);
+    }
+    return indexerInstance;
+}

package/dist/kasia/indexer.test.d.ts

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

package/dist/kasia/indexer.test.js

@@ -0,0 +1,58 @@
+// ABOUTME: Tests for the Kasia indexer HTTP client
+// ABOUTME: Verifies URL construction, alias hex-encoding, and error handling
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { KasiaIndexer, getIndexer } from './indexer.js';
+// Mock global fetch
+const mockFetch = vi.fn();
+vi.stubGlobal('fetch', mockFetch);
+describe('KasiaIndexer', () => {
+    const indexer = new KasiaIndexer('https://indexer.kasia.fyi');
+    beforeEach(() => {
+        mockFetch.mockReset();
+    });
+    it('fetches handshakes by sender', async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            json: async () => [{ tx_id: 'abc', sender: 'kaspa:q1', receiver: 'kaspa:q2', block_time: 123, accepting_block: null, accepting_daa_score: null, message_payload: 'deadbeef' }],
+        });
+        const result = await indexer.getHandshakesBySender('kaspa:q1');
+        expect(result).toHaveLength(1);
+        expect(result[0].tx_id).toBe('abc');
+        expect(mockFetch).toHaveBeenCalledWith(expect.stringContaining('/handshakes/by-sender?address=kaspa%3Aq1'), expect.anything());
+    });
+    it('fetches handshakes by receiver', async () => {
+        mockFetch.mockResolvedValueOnce({ ok: true, json: async () => [] });
+        await indexer.getHandshakesByReceiver('kaspa:q2');
+        const calledUrl = mockFetch.mock.calls[0][0];
+        expect(calledUrl).toContain('/handshakes/by-receiver?address=kaspa%3Aq2');
+    });
+    it('hex-encodes alias for contextual messages', async () => {
+        mockFetch.mockResolvedValueOnce({ ok: true, json: async () => [] });
+        await indexer.getMessagesBySender('kaspa:q1', 'a1b2c3d4e5f6');
+        const calledUrl = mockFetch.mock.calls[0][0];
+        const aliasHex = Buffer.from('a1b2c3d4e5f6', 'utf-8').toString('hex');
+        expect(calledUrl).toContain(`alias=${aliasHex}`);
+    });
+    it('hex-encodes scope for self-stash', async () => {
+        mockFetch.mockResolvedValueOnce({ ok: true, json: async () => [] });
+        await indexer.getSelfStashByOwner('kaspa:q1', 'saved_handshake');
+        const calledUrl = mockFetch.mock.calls[0][0];
+        const scopeHex = Buffer.from('saved_handshake', 'utf-8').toString('hex');
+        expect(calledUrl).toContain(`scope=${scopeHex}`);
+    });
+    it('throws on HTTP error', async () => {
+        mockFetch.mockResolvedValueOnce({ ok: false, status: 500, statusText: 'Internal Server Error' });
+        await expect(indexer.getHandshakesBySender('kaspa:q1')).rejects.toThrow('500');
+    });
+    it('strips trailing slash from base URL', () => {
+        const idx = new KasiaIndexer('https://indexer.kasia.fyi/');
+        expect(idx.baseUrl).toBe('https://indexer.kasia.fyi');
+    });
+});
+describe('getIndexer', () => {
+    it('returns a KasiaIndexer singleton', () => {
+        const a = getIndexer();
+        const b = getIndexer();
+        expect(a).toBe(b);
+    });
+});

package/dist/kasia/protocol.d.ts

@@ -0,0 +1,5 @@
+export declare function encodeHandshakePayload(encryptedHex: string): string;
+export declare function encodeCommPayload(alias: string, encryptedBytes: Buffer): string;
+export declare function encodePaymentPayload(encryptedBytes: Buffer): string;
+export declare function encodeSelfStashPayload(scope: string, encryptedHex: string): string;
+export declare function payloadToTransactionHex(payload: string): string;

package/dist/kasia/protocol.js

@@ -0,0 +1,24 @@
+// ABOUTME: Kasia protocol message encoding for on-chain payloads
+// ABOUTME: Two strategies: binary hex (handshake, self-stash) and UTF-8+base64 (comm, payment)
+export function encodeHandshakePayload(encryptedHex) {
+    const prefixHex = Buffer.from('ciph_msg:1:handshake:', 'utf-8').toString('hex');
+    return prefixHex + encryptedHex;
+}
+export function encodeCommPayload(alias, encryptedBytes) {
+    return `ciph_msg:1:comm:${alias}:${encryptedBytes.toString('base64')}`;
+}
+export function encodePaymentPayload(encryptedBytes) {
+    return `ciph_msg:1:payment:${encryptedBytes.toString('base64')}`;
+}
+export function encodeSelfStashPayload(scope, encryptedHex) {
+    const prefixHex = Buffer.from(`ciph_msg:1:self_stash:${scope}:`, 'utf-8').toString('hex');
+    return prefixHex + encryptedHex;
+}
+export function payloadToTransactionHex(payload) {
+    // Detect encoding: if no colons and valid hex → already hex bytes
+    // Otherwise → UTF-8 encode the string to hex
+    if (!payload.includes(':') && /^[0-9a-f]+$/i.test(payload)) {
+        return payload;
+    }
+    return Buffer.from(payload, 'utf-8').toString('hex');
+}

package/dist/kasia/protocol.test.d.ts

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

package/dist/kasia/protocol.test.js

@@ -0,0 +1,32 @@
+// ABOUTME: Tests for Kasia protocol message encoding
+// ABOUTME: Verifies handshake (hex), comm (base64), payment (base64), self-stash (hex) encodings
+import { describe, it, expect } from 'vitest';
+import { encodeHandshakePayload, encodeCommPayload, encodePaymentPayload, encodeSelfStashPayload, } from './protocol.js';
+describe('protocol', () => {
+    const encryptedHex = 'deadbeef0123456789abcdef';
+    it('encodes handshake as full hex', () => {
+        const payload = encodeHandshakePayload(encryptedHex);
+        // "ciph_msg:1:handshake:" in hex + encrypted hex
+        const prefixHex = Buffer.from('ciph_msg:1:handshake:', 'utf-8').toString('hex');
+        expect(payload).toBe(prefixHex + encryptedHex);
+    });
+    it('encodes comm as utf-8 string with base64', () => {
+        const encryptedBytes = Buffer.from(encryptedHex, 'hex');
+        const alias = 'a1b2c3d4e5f6';
+        const payload = encodeCommPayload(alias, encryptedBytes);
+        const expected = `ciph_msg:1:comm:${alias}:${encryptedBytes.toString('base64')}`;
+        expect(payload).toBe(expected);
+    });
+    it('encodes payment as utf-8 string with base64', () => {
+        const encryptedBytes = Buffer.from(encryptedHex, 'hex');
+        const payload = encodePaymentPayload(encryptedBytes);
+        const expected = `ciph_msg:1:payment:${encryptedBytes.toString('base64')}`;
+        expect(payload).toBe(expected);
+    });
+    it('encodes self-stash as full hex with scope', () => {
+        const scope = 'saved_handshake';
+        const payload = encodeSelfStashPayload(scope, encryptedHex);
+        const prefixHex = Buffer.from(`ciph_msg:1:self_stash:${scope}:`, 'utf-8').toString('hex');
+        expect(payload).toBe(prefixHex + encryptedHex);
+    });
+});

package/dist/tools/accept-handshake.d.ts

@@ -0,0 +1,5 @@
+import { type KasiaWriteResult } from '../types.js';
+export interface AcceptHandshakeParams {
+    address: string;
+}
+export declare function acceptHandshake(params: AcceptHandshakeParams): Promise<KasiaWriteResult>;

package/dist/tools/accept-handshake.js

@@ -0,0 +1,29 @@
+// ABOUTME: MCP tool to accept an incoming Kasia handshake request
+// ABOUTME: Generates acceptance handshake payload for broadcasting via kaspa-mcp's send_kaspa
+import { getWallet } from 'kaspa-mcp/kaspa/wallet';
+import { encrypt } from '../kasia/crypto.js';
+import { deriveAliases } from '../kasia/alias.js';
+import { encodeHandshakePayload } from '../kasia/protocol.js';
+import { KASIA_MIN_AMOUNT } from '../types.js';
+export async function acceptHandshake(params) {
+    const wallet = getWallet();
+    const myPrivateKeyHex = wallet.getPrivateKey().toString();
+    const { myAlias, theirAlias } = await deriveAliases(myPrivateKeyHex, params.address);
+    const handshake = {
+        type: 'handshake',
+        alias: myAlias,
+        theirAlias,
+        timestamp: Date.now(),
+        version: 1,
+        isResponse: true,
+    };
+    const encrypted = await encrypt(JSON.stringify(handshake), params.address);
+    const payload = encodeHandshakePayload(encrypted.toString('hex'));
+    return {
+        action: 'accept_handshake',
+        to: params.address,
+        amount: KASIA_MIN_AMOUNT,
+        payload,
+        instructions: `Call send_kaspa with to="${params.address}", amount="${KASIA_MIN_AMOUNT}", payload="${payload}" to broadcast this handshake acceptance.`,
+    };
+}

package/dist/tools/accept-handshake.test.d.ts

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