MIST.cash MCP Server

Instructions

Implementation Reference

• src/tools/verificar-existencia.ts:10-58 (handler)

  Implements the core logic: validates input using Zod schema, sets up Starknet provider and Chamber contract, checks transaction existence via checkTxExists with retry and 30s timeout.

  export async function verificarExistenciaTransaccion(params: unknown) {
      // Validate parameters
      const validated = VerificarExistenciaTransaccionSchema.parse(params);
  
      try {
          // Create provider
          const provider = createProvider(
              validated.provider_rpc_url ? { nodeUrl: validated.provider_rpc_url } : undefined
          );
  
          // Get contract address (supports custom Madara address)
          const network = (process.env.STARKNET_NETWORK || 'mainnet') as 'mainnet' | 'sepolia';
          const contractAddress = getContractAddress(network);
  
          // Get contract instance
          const contract = await getChamberContract(provider, contractAddress, CHAMBER_ABI);
  
          // Check transaction existence with retry logic and timeout
          const checkPromise = retryWithBackoff(
              () => checkTxExists(
                  contract,
                  validated.claiming_key,
                  validated.recipient,
                  validated.token_address,
                  validated.amount
              )
          );
  
          const timeoutPromise = new Promise((_, reject) =>
              setTimeout(() => reject(new Error('Request timeout after 30s')), 30000)
          );
  
          const exists = await Promise.race([checkPromise, timeoutPromise]) as boolean;
  
          return {
              success: true,
              exists,
              transaction_details: {
                  claiming_key: validated.claiming_key,
                  recipient: validated.recipient,
                  token_address: validated.token_address,
                  amount: validated.amount
              },
              note: 'This method is for fully private transactions where assets are not publicly visible'
          };
      } catch (error) {
          throw new Error(`Failed to verify transaction existence: ${(error as Error).message}`);
      }
  }

• src/utils/validation.js:22-28 (schema)

  Zod schema defining and validating the tool's input parameters: claiming_key, recipient, token_address, amount, optional provider_rpc_url.

  export const VerificarExistenciaTransaccionSchema = z.object({
      claiming_key: z.string().min(1, 'Claiming key is required'),
      recipient: StarknetAddressSchema,
      token_address: StarknetAddressSchema,
      amount: z.string().regex(/^\d+$/, 'Amount must be a numeric string'),
      provider_rpc_url: z.string().url().optional()
  });

• src/index.ts:86-114 (registration)

  Registers the tool metadata (name, description, inputSchema) in the MCP server's listTools handler.

      name: 'verificar_existencia_transaccion',
      description: 'Verify if a transaction exists with specific assets. For fully private transactions where assets are not publicly visible.',
      inputSchema: {
          type: 'object',
          properties: {
              claiming_key: {
                  type: 'string',
                  description: 'Claiming key for the transaction',
              },
              recipient: {
                  type: 'string',
                  description: 'Starknet address of the recipient',
              },
              token_address: {
                  type: 'string',
                  description: 'Token contract address (e.g., ETH, USDC)',
              },
              amount: {
                  type: 'string',
                  description: 'Amount in base units (wei)',
              },
              provider_rpc_url: {
                  type: 'string',
                  description: 'Optional custom Starknet RPC URL',
              },
          },
          required: ['claiming_key', 'recipient', 'token_address', 'amount'],
      },
  },

• src/index.ts:186-194 (registration)

  Registers the tool execution handler in the MCP server's CallToolRequestSchema switch statement, dispatching to verificarExistenciaTransaccion.

  case 'verificar_existencia_transaccion':
      return {
          content: [
              {
                  type: 'text',
                  text: JSON.stringify(await verificarExistenciaTransaccion(args), null, 2),
              },
          ],
      };

• src/index.ts:20-20 (registration)

  Imports the handler function for use in tool registration and dispatch.

  import { verificarExistenciaTransaccion } from './tools/verificar-existencia.js';