verificar_existencia_transaccion

Check if a private transaction with specific assets exists on Starknet using claiming keys and recipient details for privacy-preserving payments.

Instructions

Verify if a transaction exists with specific assets. For fully private transactions where assets are not publicly visible.

Input Schema

TableJSON Schema

Name	Required	Description
`claiming_key`	Yes	Claiming key for the transaction
`recipient`	Yes	Starknet address of the recipient
`token_address`	Yes	Token contract address (e.g., ETH, USDC)
`amount`	Yes	Amount in base units (wei)
`provider_rpc_url`	No	Optional custom Starknet RPC URL

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';
```

MIST.cash MCP Server