@manifest-network/manifest-mcp-browser 0.1.0

package/src/transactions/utils.test.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect } from 'vitest';
+import { parseAmount, parseBigInt } from './utils.js';
+import { ManifestMCPError, ManifestMCPErrorCode } from '../types.js';
+
+describe('parseAmount', () => {
+  it('should parse valid amount strings', () => {
+    expect(parseAmount('1000umfx')).toEqual({ amount: '1000', denom: 'umfx' });
+    expect(parseAmount('1uatom')).toEqual({ amount: '1', denom: 'uatom' });
+    expect(parseAmount('999999999token')).toEqual({ amount: '999999999', denom: 'token' });
+  });
+
+  it('should handle denominations with numbers', () => {
+    expect(parseAmount('100ibc123')).toEqual({ amount: '100', denom: 'ibc123' });
+  });
+
+  it('should handle factory denoms with slashes', () => {
+    expect(parseAmount('1000000factory/manifest1abc123/upwr')).toEqual({
+      amount: '1000000',
+      denom: 'factory/manifest1abc123/upwr',
+    });
+  });
+
+  it('should handle IBC denoms with slashes', () => {
+    expect(parseAmount('500ibc/ABC123DEF456')).toEqual({
+      amount: '500',
+      denom: 'ibc/ABC123DEF456',
+    });
+  });
+
+  it('should handle denoms with underscores', () => {
+    expect(parseAmount('100my_token')).toEqual({ amount: '100', denom: 'my_token' });
+  });
+
+  it('should throw ManifestMCPError for invalid format', () => {
+    expect(() => parseAmount('')).toThrow(ManifestMCPError);
+    expect(() => parseAmount('umfx')).toThrow(ManifestMCPError);
+    expect(() => parseAmount('1000')).toThrow(ManifestMCPError);
+    expect(() => parseAmount('abc123')).toThrow(ManifestMCPError);
+    expect(() => parseAmount('1000 umfx')).toThrow(ManifestMCPError);
+  });
+
+  it('should have correct error code for invalid format', () => {
+    try {
+      parseAmount('invalid');
+    } catch (error) {
+      expect(error).toBeInstanceOf(ManifestMCPError);
+      expect((error as ManifestMCPError).code).toBe(ManifestMCPErrorCode.TX_FAILED);
+    }
+  });
+
+  it('should provide helpful hint for empty string', () => {
+    try {
+      parseAmount('');
+    } catch (error) {
+      expect((error as ManifestMCPError).message).toContain('Received empty string');
+    }
+  });
+
+  it('should provide helpful hint for amount with space', () => {
+    try {
+      parseAmount('1000 umfx');
+    } catch (error) {
+      expect((error as ManifestMCPError).message).toContain('Remove the space');
+    }
+  });
+
+  it('should provide helpful hint for amount with comma', () => {
+    try {
+      parseAmount('1,000umfx');
+    } catch (error) {
+      expect((error as ManifestMCPError).message).toContain('Do not use commas');
+    }
+  });
+
+  it('should provide helpful hint for missing denomination', () => {
+    try {
+      parseAmount('1000');
+    } catch (error) {
+      expect((error as ManifestMCPError).message).toContain('Missing denomination');
+    }
+  });
+
+  it('should provide helpful hint for denom-first format', () => {
+    try {
+      parseAmount('umfx1000');
+    } catch (error) {
+      expect((error as ManifestMCPError).message).toContain('must start with a number');
+    }
+  });
+
+  it('should include details with received value and example', () => {
+    try {
+      parseAmount('bad');
+    } catch (error) {
+      const details = (error as ManifestMCPError).details;
+      expect(details?.receivedValue).toBe('bad');
+      expect(details?.example).toBe('1000000umfx');
+    }
+  });
+});
+
+describe('parseBigInt', () => {
+  it('should parse valid integer strings', () => {
+    expect(parseBigInt('0', 'test')).toBe(BigInt(0));
+    expect(parseBigInt('123', 'test')).toBe(BigInt(123));
+    expect(parseBigInt('9999999999999999999', 'test')).toBe(BigInt('9999999999999999999'));
+  });
+
+  it('should throw ManifestMCPError for invalid integers', () => {
+    expect(() => parseBigInt('abc', 'field')).toThrow(ManifestMCPError);
+    expect(() => parseBigInt('12.34', 'field')).toThrow(ManifestMCPError);
+    expect(() => parseBigInt('1e10', 'field')).toThrow(ManifestMCPError);
+  });
+
+  it('should throw ManifestMCPError for empty string', () => {
+    // Empty string should be rejected for security (prevents accidental 0 values)
+    expect(() => parseBigInt('', 'field')).toThrow(ManifestMCPError);
+    expect(() => parseBigInt('   ', 'field')).toThrow(ManifestMCPError);
+  });
+
+  it('should include field name in error message', () => {
+    try {
+      parseBigInt('invalid', 'proposal-id');
+    } catch (error) {
+      expect(error).toBeInstanceOf(ManifestMCPError);
+      expect((error as ManifestMCPError).message).toContain('proposal-id');
+    }
+  });
+});

package/src/transactions/utils.ts

@@ -0,0 +1,156 @@
+import { SigningStargateClient } from '@cosmjs/stargate';
+import { fromBech32 } from '@cosmjs/encoding';
+import { ManifestMCPError, ManifestMCPErrorCode, CosmosTxResult } from '../types.js';
+
+/** Maximum number of arguments allowed */
+export const MAX_ARGS = 100;
+
+/** Maximum memo length (Cosmos SDK default) */
+export const MAX_MEMO_LENGTH = 256;
+
+/**
+ * Validate args array length
+ */
+export function validateArgsLength(args: string[], context: string): void {
+  if (args.length > MAX_ARGS) {
+    throw new ManifestMCPError(
+      ManifestMCPErrorCode.TX_FAILED,
+      `Too many arguments for ${context}: ${args.length}. Maximum allowed: ${MAX_ARGS}`
+    );
+  }
+}
+
+/**
+ * Validate a bech32 address using @cosmjs/encoding
+ */
+export function validateAddress(address: string, fieldName: string, expectedPrefix?: string): void {
+  if (!address || address.trim() === '') {
+    throw new ManifestMCPError(
+      ManifestMCPErrorCode.INVALID_ADDRESS,
+      `${fieldName} is required`
+    );
+  }
+
+  try {
+    const { prefix } = fromBech32(address);
+    if (expectedPrefix && prefix !== expectedPrefix) {
+      throw new ManifestMCPError(
+        ManifestMCPErrorCode.INVALID_ADDRESS,
+        `Invalid ${fieldName}: "${address}". Expected prefix "${expectedPrefix}", got "${prefix}"`
+      );
+    }
+  } catch (error) {
+    if (error instanceof ManifestMCPError) {
+      throw error;
+    }
+    throw new ManifestMCPError(
+      ManifestMCPErrorCode.INVALID_ADDRESS,
+      `Invalid ${fieldName}: "${address}". Not a valid bech32 address.`
+    );
+  }
+}
+
+/**
+ * Validate memo length
+ */
+export function validateMemo(memo: string): void {
+  if (memo.length > MAX_MEMO_LENGTH) {
+    throw new ManifestMCPError(
+      ManifestMCPErrorCode.TX_FAILED,
+      `Memo too long: ${memo.length} characters. Maximum allowed: ${MAX_MEMO_LENGTH}`
+    );
+  }
+}
+
+/**
+ * Safely parse a string to BigInt with proper error handling and configurable error code.
+ * This is the base implementation used by both transaction and query utilities.
+ */
+export function parseBigIntWithCode(
+  value: string,
+  fieldName: string,
+  errorCode: ManifestMCPErrorCode
+): bigint {
+  // Check for empty string explicitly (BigInt('') returns 0n, not an error)
+  if (!value || value.trim() === '') {
+    throw new ManifestMCPError(
+      errorCode,
+      `Invalid ${fieldName}: empty value. Expected a valid integer.`
+    );
+  }
+
+  try {
+    return BigInt(value);
+  } catch {
+    throw new ManifestMCPError(
+      errorCode,
+      `Invalid ${fieldName}: "${value}". Expected a valid integer.`
+    );
+  }
+}
+
+/**
+ * Safely parse a string to BigInt with proper error handling (for transactions)
+ */
+export function parseBigInt(value: string, fieldName: string): bigint {
+  return parseBigIntWithCode(value, fieldName, ManifestMCPErrorCode.TX_FAILED);
+}
+
+/**
+ * Parse amount string into coin (e.g., "1000umfx" -> { amount: "1000", denom: "umfx" })
+ * Supports simple denoms (umfx), IBC denoms (ibc/...), and factory denoms (factory/creator/subdenom)
+ */
+export function parseAmount(amountStr: string): { amount: string; denom: string } {
+  // Regex supports alphanumeric denoms with slashes and underscores for IBC/factory denoms
+  const match = amountStr.match(/^(\d+)([a-zA-Z][a-zA-Z0-9/_]*)$/);
+  if (!match) {
+    // Provide specific hints based on common mistakes
+    let hint = '';
+    if (!amountStr || amountStr.trim() === '') {
+      hint = ' Received empty string.';
+    } else if (amountStr.includes(' ')) {
+      hint = ' Remove the space between number and denom.';
+    } else if (amountStr.includes(',')) {
+      hint = ' Do not use commas in the number.';
+    } else if (/^\d+$/.test(amountStr)) {
+      hint = ' Missing denomination (e.g., add "umfx" after the number).';
+    } else if (/^[a-zA-Z]/.test(amountStr)) {
+      hint = ' Amount must start with a number, not the denomination.';
+    }
+
+    throw new ManifestMCPError(
+      ManifestMCPErrorCode.TX_FAILED,
+      `Invalid amount format: "${amountStr}".${hint} Expected format: <number><denom> (e.g., "1000000umfx" or "1000000factory/address/subdenom")`,
+      { receivedValue: amountStr, expectedFormat: '<number><denom>', example: '1000000umfx' }
+    );
+  }
+  return { amount: match[1], denom: match[2] };
+}
+
+/**
+ * Build transaction result from DeliverTxResponse
+ */
+export function buildTxResult(
+  module: string,
+  subcommand: string,
+  result: Awaited<ReturnType<SigningStargateClient['signAndBroadcast']>>,
+  waitForConfirmation: boolean
+): CosmosTxResult {
+  const txResult: CosmosTxResult = {
+    module,
+    subcommand,
+    transactionHash: result.transactionHash,
+    code: result.code,
+    height: String(result.height),
+    rawLog: result.rawLog || undefined,
+    gasUsed: String(result.gasUsed),
+    gasWanted: String(result.gasWanted),
+  };
+
+  if (waitForConfirmation) {
+    txResult.confirmed = result.code === 0;
+    txResult.confirmationHeight = String(result.height);
+  }
+
+  return txResult;
+}

package/src/types.ts

@@ -0,0 +1,152 @@
+import type { OfflineSigner } from '@cosmjs/proto-signing';
+
+/**
+ * Configuration for the Manifest MCP Browser server
+ */
+export interface ManifestMCPConfig {
+  /** Chain ID (e.g., "manifest-ledger-testnet") */
+  readonly chainId: string;
+  /** RPC endpoint URL */
+  readonly rpcUrl: string;
+  /** Gas price with denomination (e.g., "1.0umfx") */
+  readonly gasPrice: string;
+  /** Gas adjustment multiplier (default: 1.3) */
+  readonly gasAdjustment?: number;
+  /** Address prefix (e.g., "manifest") */
+  readonly addressPrefix?: string;
+}
+
+/**
+ * Wallet provider interface for different wallet implementations
+ *
+ * Any wallet that provides an OfflineSigner works (Keplr, Web3Auth, Leap, cosmos-kit, etc.)
+ */
+export interface WalletProvider {
+  /** Get the wallet's address */
+  getAddress(): Promise<string>;
+  /** Get the offline signer for signing transactions */
+  getSigner(): Promise<OfflineSigner>;
+  /** Optional: Connect to the wallet */
+  connect?(): Promise<void>;
+  /** Optional: Disconnect from the wallet */
+  disconnect?(): Promise<void>;
+}
+
+/**
+ * Result from a Cosmos query
+ */
+export interface CosmosQueryResult {
+  readonly module: string;
+  readonly subcommand: string;
+  readonly result: Record<string, unknown>;
+}
+
+/**
+ * Result from a Cosmos transaction
+ */
+export interface CosmosTxResult {
+  readonly module: string;
+  readonly subcommand: string;
+  readonly transactionHash: string;
+  readonly code: number;
+  readonly height: string;
+  readonly rawLog?: string;
+  confirmed?: boolean;
+  confirmationHeight?: string;
+  readonly gasUsed?: string;
+  readonly gasWanted?: string;
+}
+
+/**
+ * Module information for discovery
+ */
+export interface ModuleInfo {
+  readonly name: string;
+  readonly description: string;
+  readonly args?: string; // Usage hint for arguments
+}
+
+/**
+ * Available modules listing
+ */
+export interface AvailableModules {
+  readonly queryModules: readonly ModuleInfo[];
+  readonly txModules: readonly ModuleInfo[];
+}
+
+/**
+ * Error codes for ManifestMCPError
+ */
+export enum ManifestMCPErrorCode {
+  // Configuration errors
+  INVALID_CONFIG = 'INVALID_CONFIG',
+  MISSING_CONFIG = 'MISSING_CONFIG',
+
+  // Wallet errors
+  WALLET_NOT_CONNECTED = 'WALLET_NOT_CONNECTED',
+  WALLET_CONNECTION_FAILED = 'WALLET_CONNECTION_FAILED',
+  KEPLR_NOT_INSTALLED = 'KEPLR_NOT_INSTALLED',
+  INVALID_MNEMONIC = 'INVALID_MNEMONIC',
+
+  // Client errors
+  CLIENT_NOT_INITIALIZED = 'CLIENT_NOT_INITIALIZED',
+  RPC_CONNECTION_FAILED = 'RPC_CONNECTION_FAILED',
+
+  // Query errors
+  QUERY_FAILED = 'QUERY_FAILED',
+  UNSUPPORTED_QUERY = 'UNSUPPORTED_QUERY',
+  INVALID_ADDRESS = 'INVALID_ADDRESS',
+
+  // Transaction errors
+  TX_FAILED = 'TX_FAILED',
+  TX_SIMULATION_FAILED = 'TX_SIMULATION_FAILED',
+  TX_BROADCAST_FAILED = 'TX_BROADCAST_FAILED',
+  TX_CONFIRMATION_TIMEOUT = 'TX_CONFIRMATION_TIMEOUT',
+  UNSUPPORTED_TX = 'UNSUPPORTED_TX',
+  INSUFFICIENT_FUNDS = 'INSUFFICIENT_FUNDS',
+
+  // Module errors
+  UNKNOWN_MODULE = 'UNKNOWN_MODULE',
+  UNKNOWN_SUBCOMMAND = 'UNKNOWN_SUBCOMMAND',
+
+  // General errors
+  UNKNOWN_ERROR = 'UNKNOWN_ERROR',
+}
+
+/**
+ * Custom error class for Manifest MCP Browser errors
+ */
+export class ManifestMCPError extends Error {
+  public readonly code: ManifestMCPErrorCode;
+  public readonly details?: Record<string, unknown>;
+
+  constructor(
+    code: ManifestMCPErrorCode,
+    message: string,
+    details?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = 'ManifestMCPError';
+    this.code = code;
+    this.details = details;
+
+    // Ensure proper prototype chain for instanceof checks
+    Object.setPrototypeOf(this, ManifestMCPError.prototype);
+  }
+
+  toJSON(): Record<string, unknown> {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      details: this.details,
+    };
+  }
+}
+
+/**
+ * Account information
+ */
+export interface AccountInfo {
+  readonly address: string;
+}

package/src/wallet/index.ts

@@ -0,0 +1,2 @@
+export type { WalletProvider } from '../types.js';
+export { MnemonicWalletProvider } from './mnemonic.js';

package/src/wallet/mnemonic.ts

@@ -0,0 +1,122 @@
+import { DirectSecp256k1HdWallet, OfflineSigner } from '@cosmjs/proto-signing';
+import { WalletProvider, ManifestMCPError, ManifestMCPErrorCode, ManifestMCPConfig } from '../types.js';
+
+/**
+ * Mnemonic-based wallet provider for non-browser environments or testing
+ *
+ * SECURITY NOTE: The mnemonic is stored in memory until disconnect() is called.
+ * After disconnect(), the wallet cannot be reconnected - create a new instance instead.
+ */
+export class MnemonicWalletProvider implements WalletProvider {
+  private config: ManifestMCPConfig;
+  private mnemonic: string | null;
+  private wallet: DirectSecp256k1HdWallet | null = null;
+  private address: string | null = null;
+  private disconnected: boolean = false;
+
+  constructor(config: ManifestMCPConfig, mnemonic: string) {
+    this.config = config;
+    this.mnemonic = mnemonic;
+  }
+
+  /**
+   * Initialize the wallet from the mnemonic
+   */
+  private async initWallet(): Promise<void> {
+    if (this.disconnected) {
+      throw new ManifestMCPError(
+        ManifestMCPErrorCode.WALLET_NOT_CONNECTED,
+        'Wallet has been disconnected and cannot be reconnected. Create a new MnemonicWalletProvider instance.'
+      );
+    }
+
+    if (this.wallet) {
+      return;
+    }
+
+    if (!this.mnemonic) {
+      throw new ManifestMCPError(
+        ManifestMCPErrorCode.WALLET_NOT_CONNECTED,
+        'Mnemonic has been cleared. Create a new MnemonicWalletProvider instance.'
+      );
+    }
+
+    const prefix = this.config.addressPrefix ?? 'manifest';
+
+    try {
+      this.wallet = await DirectSecp256k1HdWallet.fromMnemonic(this.mnemonic, {
+        prefix,
+      });
+
+      const accounts = await this.wallet.getAccounts();
+      if (accounts.length === 0) {
+        throw new ManifestMCPError(
+          ManifestMCPErrorCode.INVALID_MNEMONIC,
+          'No accounts derived from mnemonic'
+        );
+      }
+
+      this.address = accounts[0].address;
+    } catch (error) {
+      throw new ManifestMCPError(
+        ManifestMCPErrorCode.INVALID_MNEMONIC,
+        `Failed to create wallet from mnemonic: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  /**
+   * Connect (initialize) the wallet
+   */
+  async connect(): Promise<void> {
+    await this.initWallet();
+  }
+
+  /**
+   * Disconnect and securely clear all sensitive data
+   *
+   * IMPORTANT: After calling disconnect(), this wallet instance cannot be reused.
+   * Create a new MnemonicWalletProvider instance if you need to reconnect.
+   */
+  async disconnect(): Promise<void> {
+    // Clear the mnemonic by overwriting with empty string then nullifying
+    // Note: JavaScript strings are immutable, so we can't truly zero the memory,
+    // but we can remove all references to allow garbage collection
+    this.mnemonic = null;
+    this.wallet = null;
+    this.address = null;
+    this.disconnected = true;
+  }
+
+  /**
+   * Get the wallet's address
+   */
+  async getAddress(): Promise<string> {
+    await this.initWallet();
+
+    if (!this.address) {
+      throw new ManifestMCPError(
+        ManifestMCPErrorCode.WALLET_NOT_CONNECTED,
+        'Wallet failed to initialize'
+      );
+    }
+
+    return this.address;
+  }
+
+  /**
+   * Get the offline signer for signing transactions
+   */
+  async getSigner(): Promise<OfflineSigner> {
+    await this.initWallet();
+
+    if (!this.wallet) {
+      throw new ManifestMCPError(
+        ManifestMCPErrorCode.WALLET_NOT_CONNECTED,
+        'Wallet failed to initialize'
+      );
+    }
+
+    return this.wallet;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ES2020",
+    "lib": ["ES2020", "DOM"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}