HashPilot

Instructions

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;