rpc_execute_contract
Execute state-changing smart contract functions on Hedera blockchain. Handles transaction signing, gas estimation, and receipt polling for token transfers and contract interactions.
Instructions
Execute state-changing contract function via eth_sendRawTransaction.
EXECUTES: Transaction that modifies contract state HANDLES: Function encoding, signing, gas estimation, receipt polling COSTS: Gas fees for execution RETURNS: Transaction hash, receipt, decoded logs AUTO-KEY: privateKey is OPTIONAL - automatically uses MCP operator account if not provided
USE FOR: Token transfers, contract interactions, state modifications.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| contractAddress | Yes | Contract address (0x...) | |
| abi | Yes | Contract ABI | |
| functionName | Yes | Function to execute | |
| args | No | Function arguments | |
| privateKey | No | Sender private key (optional - uses MCP operator) | |
| value | No | HBAR value to send (in wei) |
Implementation Reference
- src/tools/rpc.ts:184-245 (handler)Core implementation of rpc_execute_contract tool: executes state-changing smart contract functions via Hedera JSON-RPC relay, handles validation, service call, and formatted response.export async function rpcExecuteContract(args: { contractAddress: string; abi: any[]; functionName: string; args?: any[]; value?: string; gasLimit?: number; privateKey?: string; fromAlias?: string; network?: 'mainnet' | 'testnet' | 'previewnet' | 'local'; }): Promise<ToolResult> { try { logger.info('Executing contract function (state-changing)', { contractAddress: args.contractAddress, functionName: args.functionName, network: args.network, }); // Validate address if (!args.contractAddress.startsWith('0x') || args.contractAddress.length !== 42) { throw new Error('Invalid contract address format'); } const result = await jsonRpcService.executeContract({ contractAddress: args.contractAddress, abi: args.abi, functionName: args.functionName, args: args.args, value: args.value, gasLimit: args.gasLimit, privateKey: args.privateKey, fromAlias: args.fromAlias, network: args.network, }); return { success: true, data: { functionName: args.functionName, transactionHash: result.transactionHash, blockNumber: result.receipt.blockNumber, gasUsed: result.receipt.gasUsed, status: result.receipt.status === '0x1' ? 'success' : 'failed', logs: result.receipt.logs, }, metadata: { executedVia: 'json_rpc_relay', command: 'contract execute', }, }; } catch (error) { logger.error('Contract execution failed', { error }); return { success: false, error: error instanceof Error ? error.message : 'Unknown error occurred', metadata: { executedVia: 'json_rpc_relay', command: 'contract execute', }, }; } }
- src/tools/rpc.ts:357-406 (schema)Detailed input schema definition for rpc_execute_contract tool within the rpcTools export array.{ name: 'rpc_execute_contract', description: 'Execute state-changing contract function via eth_sendRawTransaction. Handles function encoding, transaction signing, gas estimation, submission, and receipt polling. Requires private key. Returns transaction hash and logs.', inputSchema: { type: 'object' as const, properties: { contractAddress: { type: 'string', description: 'Contract address (0x... format)', }, abi: { type: 'array', description: 'Contract ABI', items: {}, }, functionName: { type: 'string', description: 'Function name to execute', }, args: { type: 'array', description: 'Optional: Function arguments', items: {}, }, value: { type: 'string', description: 'Optional: HBAR value to send in wei (18 decimals)', }, gasLimit: { type: 'number', description: 'Optional: Gas limit override (auto-estimated if not provided)', }, privateKey: { type: 'string', description: 'Optional: Private key in DER format (or use fromAlias)', }, fromAlias: { type: 'string', description: 'Optional: Address book alias to use for execution', }, network: { type: 'string', enum: ['mainnet', 'testnet', 'previewnet', 'local'], description: 'Target network (default: current network)', }, }, required: ['contractAddress', 'abi', 'functionName'], }, },
- src/index.ts:292-314 (registration)Tool registration in the MCP server's optimizedToolDefinitions array, including simplified input schema.name: 'rpc_execute_contract', description: `Execute state-changing contract function via eth_sendRawTransaction. EXECUTES: Transaction that modifies contract state HANDLES: Function encoding, signing, gas estimation, receipt polling COSTS: Gas fees for execution RETURNS: Transaction hash, receipt, decoded logs AUTO-KEY: privateKey is OPTIONAL - automatically uses MCP operator account if not provided USE FOR: Token transfers, contract interactions, state modifications.`, inputSchema: { type: 'object' as const, properties: { contractAddress: { type: 'string', description: 'Contract address (0x...)' }, abi: { type: 'array', items: {}, description: 'Contract ABI' }, functionName: { type: 'string', description: 'Function to execute' }, args: { type: 'array', items: {}, description: 'Function arguments' }, privateKey: { type: 'string', description: 'Sender private key (optional - uses MCP operator)' }, value: { type: 'string', description: 'HBAR value to send (in wei)' }, }, required: ['contractAddress', 'abi', 'functionName'], }, },
- src/index.ts:614-616 (registration)Dispatch registration in the MCP server's CallToolRequestSchema handler switch statement, routing calls to the rpcExecuteContract handler.case 'rpc_execute_contract': result = await rpcExecuteContract(args as any); break;