@manifest-network/manifest-mcp-browser 0.1.0

package/src/client.ts

@@ -0,0 +1,178 @@
+import { SigningStargateClient, GasPrice, HttpEndpoint } from '@cosmjs/stargate';
+import {
+  cosmosProtoRegistry,
+  cosmosAminoConverters,
+  liftedinitProtoRegistry,
+  liftedinitAminoConverters,
+  strangeloveVenturesProtoRegistry,
+  strangeloveVenturesAminoConverters,
+  osmosisProtoRegistry,
+  osmosisAminoConverters,
+  liftedinit,
+} from '@manifest-network/manifestjs';
+import { Registry } from '@cosmjs/proto-signing';
+import { AminoTypes } from '@cosmjs/stargate';
+import { ManifestMCPConfig, WalletProvider, ManifestMCPError, ManifestMCPErrorCode } from './types.js';
+
+// Type for the RPC query client from manifestjs liftedinit bundle
+// This includes cosmos modules + liftedinit-specific modules (billing, manifest, sku)
+export type ManifestQueryClient = Awaited<ReturnType<typeof liftedinit.ClientFactory.createRPCQueryClient>>;
+
+/** Default timeout for transaction broadcast (60 seconds) */
+const DEFAULT_BROADCAST_TIMEOUT_MS = 60_000;
+
+/** Default polling interval for transaction confirmation (3 seconds) */
+const DEFAULT_BROADCAST_POLL_INTERVAL_MS = 3_000;
+
+/**
+ * Get combined signing client options with all Manifest registries
+ */
+function getSigningManifestClientOptions() {
+  const registry = new Registry([
+    ...cosmosProtoRegistry,
+    ...liftedinitProtoRegistry,
+    ...strangeloveVenturesProtoRegistry,
+    ...osmosisProtoRegistry,
+  ]);
+
+  const aminoTypes = new AminoTypes({
+    ...cosmosAminoConverters,
+    ...liftedinitAminoConverters,
+    ...strangeloveVenturesAminoConverters,
+    ...osmosisAminoConverters,
+  });
+
+  return { registry, aminoTypes };
+}
+
+/**
+ * Manages CosmJS client instances with lazy initialization and singleton pattern
+ */
+export class CosmosClientManager {
+  private static instances: Map<string, CosmosClientManager> = new Map();
+
+  private config: ManifestMCPConfig;
+  private walletProvider: WalletProvider;
+  private queryClient: ManifestQueryClient | null = null;
+  private signingClient: SigningStargateClient | null = null;
+
+  private constructor(config: ManifestMCPConfig, walletProvider: WalletProvider) {
+    this.config = config;
+    this.walletProvider = walletProvider;
+  }
+
+  /**
+   * Get or create a singleton instance for the given config
+   */
+  static getInstance(
+    config: ManifestMCPConfig,
+    walletProvider: WalletProvider
+  ): CosmosClientManager {
+    const key = `${config.chainId}:${config.rpcUrl}`;
+    let instance = CosmosClientManager.instances.get(key);
+
+    if (!instance) {
+      instance = new CosmosClientManager(config, walletProvider);
+      CosmosClientManager.instances.set(key, instance);
+    }
+
+    return instance;
+  }
+
+  /**
+   * Clear all cached instances (useful for testing or reconnection)
+   */
+  static clearInstances(): void {
+    CosmosClientManager.instances.clear();
+  }
+
+  /**
+   * Get the manifestjs RPC query client with all module extensions
+   */
+  async getQueryClient(): Promise<ManifestQueryClient> {
+    if (!this.queryClient) {
+      try {
+        // Use liftedinit ClientFactory which includes cosmos + liftedinit modules
+        this.queryClient = await liftedinit.ClientFactory.createRPCQueryClient({
+          rpcEndpoint: this.config.rpcUrl,
+        });
+      } catch (error) {
+        throw new ManifestMCPError(
+          ManifestMCPErrorCode.RPC_CONNECTION_FAILED,
+          `Failed to connect to RPC endpoint: ${error instanceof Error ? error.message : String(error)}`,
+          { rpcUrl: this.config.rpcUrl }
+        );
+      }
+    }
+    return this.queryClient;
+  }
+
+  /**
+   * Get a signing client with all Manifest registries (for transactions)
+   */
+  async getSigningClient(): Promise<SigningStargateClient> {
+    if (!this.signingClient) {
+      try {
+        const signer = await this.walletProvider.getSigner();
+        const gasPrice = GasPrice.fromString(this.config.gasPrice);
+        const { registry, aminoTypes } = getSigningManifestClientOptions();
+
+        // Configure endpoint with HTTP timeout
+        const endpoint: HttpEndpoint = {
+          url: this.config.rpcUrl,
+          headers: {},
+        };
+
+        // Note: Registry type from @cosmjs/proto-signing doesn't perfectly match
+        // SigningStargateClientOptions due to telescope-generated proto types.
+        // This is a known limitation with custom cosmos-sdk module registries.
+        this.signingClient = await SigningStargateClient.connectWithSigner(
+          endpoint,
+          signer,
+          {
+            registry: registry as Parameters<typeof SigningStargateClient.connectWithSigner>[2] extends { registry?: infer R } ? R : never,
+            aminoTypes,
+            gasPrice,
+            broadcastTimeoutMs: DEFAULT_BROADCAST_TIMEOUT_MS,
+            broadcastPollIntervalMs: DEFAULT_BROADCAST_POLL_INTERVAL_MS,
+          }
+        );
+      } catch (error) {
+        if (error instanceof ManifestMCPError) {
+          throw error;
+        }
+        throw new ManifestMCPError(
+          ManifestMCPErrorCode.RPC_CONNECTION_FAILED,
+          `Failed to connect signing client: ${error instanceof Error ? error.message : String(error)}`,
+          { rpcUrl: this.config.rpcUrl }
+        );
+      }
+    }
+    return this.signingClient;
+  }
+
+  /**
+   * Get the wallet address
+   */
+  async getAddress(): Promise<string> {
+    return this.walletProvider.getAddress();
+  }
+
+  /**
+   * Get the configuration
+   */
+  getConfig(): ManifestMCPConfig {
+    return this.config;
+  }
+
+  /**
+   * Disconnect all clients
+   */
+  disconnect(): void {
+    if (this.signingClient) {
+      this.signingClient.disconnect();
+      this.signingClient = null;
+    }
+    this.queryClient = null;
+  }
+}

package/src/config.test.ts

@@ -0,0 +1,143 @@
+import { describe, it, expect } from 'vitest';
+import { createConfig, validateConfig, createValidatedConfig } from './config.js';
+import { ManifestMCPError, ManifestMCPErrorCode } from './types.js';
+
+describe('createConfig', () => {
+  it('should apply default values', () => {
+    const config = createConfig({
+      chainId: 'test-chain',
+      rpcUrl: 'https://example.com',
+      gasPrice: '1.0umfx',
+    });
+
+    expect(config.chainId).toBe('test-chain');
+    expect(config.rpcUrl).toBe('https://example.com');
+    expect(config.gasPrice).toBe('1.0umfx');
+    expect(config.gasAdjustment).toBe(1.3);
+    expect(config.addressPrefix).toBe('manifest');
+  });
+
+  it('should preserve provided optional values', () => {
+    const config = createConfig({
+      chainId: 'test-chain',
+      rpcUrl: 'https://example.com',
+      gasPrice: '1.0umfx',
+      gasAdjustment: 2.0,
+      addressPrefix: 'custom',
+    });
+
+    expect(config.gasAdjustment).toBe(2.0);
+    expect(config.addressPrefix).toBe('custom');
+  });
+});
+
+describe('validateConfig', () => {
+  it('should return valid for correct config', () => {
+    const result = validateConfig({
+      chainId: 'manifest-testnet',
+      rpcUrl: 'https://rpc.example.com',
+      gasPrice: '1.0umfx',
+    });
+
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('should detect missing required fields', () => {
+    const result = validateConfig({});
+
+    expect(result.valid).toBe(false);
+    expect(result.errors).toContain('chainId is required');
+    expect(result.errors).toContain('rpcUrl is required');
+    expect(result.errors).toContain('gasPrice is required');
+  });
+
+  it('should validate chainId format', () => {
+    const result = validateConfig({
+      chainId: '-invalid',
+      rpcUrl: 'https://example.com',
+      gasPrice: '1.0umfx',
+    });
+
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.includes('chainId'))).toBe(true);
+  });
+
+  it('should validate rpcUrl format', () => {
+    const result = validateConfig({
+      chainId: 'test',
+      rpcUrl: 'not-a-url',
+      gasPrice: '1.0umfx',
+    });
+
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.includes('rpcUrl'))).toBe(true);
+  });
+
+  it('should validate gasPrice format', () => {
+    const result = validateConfig({
+      chainId: 'test',
+      rpcUrl: 'https://example.com',
+      gasPrice: 'invalid',
+    });
+
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.includes('gasPrice'))).toBe(true);
+  });
+
+  it('should validate optional gasAdjustment', () => {
+    const result = validateConfig({
+      chainId: 'test',
+      rpcUrl: 'https://example.com',
+      gasPrice: '1.0umfx',
+      gasAdjustment: -1,
+    });
+
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.includes('gasAdjustment'))).toBe(true);
+  });
+
+  it('should validate optional addressPrefix', () => {
+    const result = validateConfig({
+      chainId: 'test',
+      rpcUrl: 'https://example.com',
+      gasPrice: '1.0umfx',
+      addressPrefix: 'INVALID',
+    });
+
+    expect(result.valid).toBe(false);
+    expect(result.errors.some(e => e.includes('addressPrefix'))).toBe(true);
+  });
+});
+
+describe('createValidatedConfig', () => {
+  it('should return config for valid input', () => {
+    const config = createValidatedConfig({
+      chainId: 'test-chain',
+      rpcUrl: 'https://example.com',
+      gasPrice: '1.0umfx',
+    });
+
+    expect(config.chainId).toBe('test-chain');
+  });
+
+  it('should throw ManifestMCPError for invalid input', () => {
+    expect(() => createValidatedConfig({
+      chainId: '',
+      rpcUrl: '',
+      gasPrice: '',
+    })).toThrow(ManifestMCPError);
+  });
+
+  it('should have INVALID_CONFIG error code', () => {
+    try {
+      createValidatedConfig({
+        chainId: '',
+        rpcUrl: '',
+        gasPrice: '',
+      });
+    } catch (error) {
+      expect((error as ManifestMCPError).code).toBe(ManifestMCPErrorCode.INVALID_CONFIG);
+    }
+  });
+});

package/src/config.ts

@@ -0,0 +1,122 @@
+import { ManifestMCPConfig, ManifestMCPError, ManifestMCPErrorCode } from './types.js';
+
+/**
+ * Default gas adjustment multiplier
+ */
+const DEFAULT_GAS_ADJUSTMENT = 1.3;
+
+/**
+ * Default address prefix for Manifest Network
+ */
+const DEFAULT_ADDRESS_PREFIX = 'manifest';
+
+/**
+ * Validate a URL string
+ */
+function isValidUrl(url: string): boolean {
+  try {
+    new URL(url);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate gas price format (e.g., "1.0umfx")
+ */
+function isValidGasPrice(gasPrice: string): boolean {
+  // Gas price should be a number followed by a denomination
+  return /^\d+(\.\d+)?[a-zA-Z]+$/.test(gasPrice);
+}
+
+/**
+ * Validate chain ID format
+ */
+function isValidChainId(chainId: string): boolean {
+  // Chain ID should be alphanumeric with hyphens
+  return /^[a-zA-Z0-9][\w-]*$/.test(chainId);
+}
+
+/**
+ * Create a configuration object with defaults applied
+ */
+export function createConfig(input: ManifestMCPConfig): ManifestMCPConfig {
+  return {
+    chainId: input.chainId,
+    rpcUrl: input.rpcUrl,
+    gasPrice: input.gasPrice,
+    gasAdjustment: input.gasAdjustment ?? DEFAULT_GAS_ADJUSTMENT,
+    addressPrefix: input.addressPrefix ?? DEFAULT_ADDRESS_PREFIX,
+  };
+}
+
+/**
+ * Validation result
+ */
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+/**
+ * Validate a configuration object
+ */
+export function validateConfig(config: Partial<ManifestMCPConfig>): ValidationResult {
+  const errors: string[] = [];
+
+  // Required fields
+  if (!config.chainId) {
+    errors.push('chainId is required');
+  } else if (!isValidChainId(config.chainId)) {
+    errors.push('chainId must be alphanumeric with hyphens (e.g., "manifest-ledger-testnet")');
+  }
+
+  if (!config.rpcUrl) {
+    errors.push('rpcUrl is required');
+  } else if (!isValidUrl(config.rpcUrl)) {
+    errors.push('rpcUrl must be a valid URL');
+  }
+
+  if (!config.gasPrice) {
+    errors.push('gasPrice is required');
+  } else if (!isValidGasPrice(config.gasPrice)) {
+    errors.push('gasPrice must be a number followed by denomination (e.g., "1.0umfx")');
+  }
+
+  // Optional fields
+  if (config.gasAdjustment !== undefined) {
+    if (typeof config.gasAdjustment !== 'number' || config.gasAdjustment <= 0) {
+      errors.push('gasAdjustment must be a positive number');
+    }
+  }
+
+  if (config.addressPrefix !== undefined) {
+    if (!/^[a-z]+$/.test(config.addressPrefix)) {
+      errors.push('addressPrefix must be lowercase letters only');
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Create and validate a configuration, throwing on invalid config
+ */
+export function createValidatedConfig(input: ManifestMCPConfig): ManifestMCPConfig {
+  const validation = validateConfig(input);
+
+  if (!validation.valid) {
+    throw new ManifestMCPError(
+      ManifestMCPErrorCode.INVALID_CONFIG,
+      `Invalid configuration: ${validation.errors.join(', ')}`,
+      { errors: validation.errors }
+    );
+  }
+
+  return createConfig(input);
+}
+

package/src/cosmos.ts

@@ -0,0 +1,196 @@
+import { CosmosClientManager } from './client.js';
+import { CosmosQueryResult, CosmosTxResult, ManifestMCPError, ManifestMCPErrorCode } from './types.js';
+import { getSupportedModules } from './modules.js';
+import { routeBankQuery } from './queries/bank.js';
+import { routeStakingQuery } from './queries/staking.js';
+import { routeDistributionQuery } from './queries/distribution.js';
+import { routeGovQuery } from './queries/gov.js';
+import { routeAuthQuery } from './queries/auth.js';
+import { routeBillingQuery } from './queries/billing.js';
+import { routeBankTransaction } from './transactions/bank.js';
+import { routeStakingTransaction } from './transactions/staking.js';
+import { routeDistributionTransaction } from './transactions/distribution.js';
+import { routeGovTransaction } from './transactions/gov.js';
+import { routeBillingTransaction } from './transactions/billing.js';
+import { routeManifestTransaction } from './transactions/manifest.js';
+
+// Validation pattern for module/subcommand names (alphanumeric, hyphens, underscores)
+// First character must not be a hyphen to prevent potential issues
+const VALID_NAME_PATTERN = /^[a-zA-Z0-9_][a-zA-Z0-9_-]*$/;
+
+/**
+ * Validate that a string is safe for use as a module or subcommand name
+ */
+function validateName(name: string, field: string): void {
+  if (!name || !VALID_NAME_PATTERN.test(name)) {
+    throw new ManifestMCPError(
+      ManifestMCPErrorCode.QUERY_FAILED,
+      `Invalid ${field}: "${name}". Only alphanumeric characters, hyphens, and underscores are allowed.`
+    );
+  }
+}
+
+// Get module lists from the authoritative registry
+const supportedModules = getSupportedModules();
+const QUERY_MODULES = Object.keys(supportedModules.query);
+const TX_MODULES = Object.keys(supportedModules.tx);
+
+/**
+ * Execute a Cosmos query via manifestjs RPC client
+ */
+export async function cosmosQuery(
+  clientManager: CosmosClientManager,
+  module: string,
+  subcommand: string,
+  args: string[] = []
+): Promise<CosmosQueryResult> {
+  validateName(module, 'module');
+  validateName(subcommand, 'subcommand');
+
+  const queryClient = await clientManager.getQueryClient();
+
+  let result: Record<string, unknown>;
+
+  try {
+    switch (module) {
+      case 'bank':
+        result = await routeBankQuery(queryClient, subcommand, args);
+        break;
+      case 'staking':
+        result = await routeStakingQuery(queryClient, subcommand, args);
+        break;
+      case 'distribution':
+        result = await routeDistributionQuery(queryClient, subcommand, args);
+        break;
+      case 'gov':
+        result = await routeGovQuery(queryClient, subcommand, args);
+        break;
+      case 'auth':
+        result = await routeAuthQuery(queryClient, subcommand, args);
+        break;
+      case 'billing':
+        result = await routeBillingQuery(queryClient, subcommand, args);
+        break;
+      default:
+        throw new ManifestMCPError(
+          ManifestMCPErrorCode.UNKNOWN_MODULE,
+          `Unknown query module: ${module}`,
+          { availableModules: QUERY_MODULES }
+        );
+    }
+
+    return {
+      module,
+      subcommand,
+      result,
+    };
+  } catch (error) {
+    if (error instanceof ManifestMCPError) {
+      throw error;
+    }
+    throw new ManifestMCPError(
+      ManifestMCPErrorCode.QUERY_FAILED,
+      `Query ${module} ${subcommand} failed: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+/**
+ * Execute a Cosmos transaction via manifestjs signing client
+ */
+export async function cosmosTx(
+  clientManager: CosmosClientManager,
+  module: string,
+  subcommand: string,
+  args: string[] = [],
+  waitForConfirmation: boolean = false
+): Promise<CosmosTxResult> {
+  validateName(module, 'module');
+  validateName(subcommand, 'subcommand');
+
+  const signingClient = await clientManager.getSigningClient();
+  const senderAddress = await clientManager.getAddress();
+  const config = clientManager.getConfig();
+
+  try {
+    switch (module) {
+      case 'bank':
+        return await routeBankTransaction(
+          signingClient,
+          senderAddress,
+          subcommand,
+          args,
+          config,
+          waitForConfirmation
+        );
+      case 'staking':
+        return await routeStakingTransaction(
+          signingClient,
+          senderAddress,
+          subcommand,
+          args,
+          config,
+          waitForConfirmation
+        );
+      case 'distribution':
+        return await routeDistributionTransaction(
+          signingClient,
+          senderAddress,
+          subcommand,
+          args,
+          config,
+          waitForConfirmation
+        );
+      case 'gov':
+        return await routeGovTransaction(
+          signingClient,
+          senderAddress,
+          subcommand,
+          args,
+          config,
+          waitForConfirmation
+        );
+      case 'billing':
+        return await routeBillingTransaction(
+          signingClient,
+          senderAddress,
+          subcommand,
+          args,
+          config,
+          waitForConfirmation
+        );
+      case 'manifest':
+        return await routeManifestTransaction(
+          signingClient,
+          senderAddress,
+          subcommand,
+          args,
+          config,
+          waitForConfirmation
+        );
+      default:
+        throw new ManifestMCPError(
+          ManifestMCPErrorCode.UNKNOWN_MODULE,
+          `Unknown tx module: ${module}`,
+          { availableModules: TX_MODULES }
+        );
+    }
+  } catch (error) {
+    if (error instanceof ManifestMCPError) {
+      // Re-throw with enriched context if not already present
+      if (!error.details?.module) {
+        throw new ManifestMCPError(
+          error.code,
+          error.message,
+          { ...error.details, module, subcommand, args }
+        );
+      }
+      throw error;
+    }
+    throw new ManifestMCPError(
+      ManifestMCPErrorCode.TX_FAILED,
+      `Tx ${module} ${subcommand} failed: ${error instanceof Error ? error.message : String(error)}`,
+      { module, subcommand, args }
+    );
+  }
+}