HashPilot

Instructions

Implementation Reference

• src/tools/verify.ts:26-145 (handler)

  The primary handler function for the 'verify_contract' MCP tool. Handles input validation, file reading (single file/dir/Hardhat build-info/Foundry artifacts), calls HashScan verification service, and formats the ToolResult response.

  export async function verifyContract(args: {
    address: string;
    network: HederaNetwork;
    contractName: string;
    filePath: string;
    creatorTxHash?: string;
    buildInfoPath?: string;
    artifactPath?: string;
  }): Promise<ToolResult> {
    try {
      logger.info('Verifying contract on HashScan', {
        address: args.address,
        network: args.network,
        contractName: args.contractName,
      });
  
      let result;
  
      // If buildInfoPath or artifactPath provided, use solc-json verification
      if (args.buildInfoPath) {
        // Hardhat build-info verification
        const buildInfo = await hashScanService.readHardhatBuildInfo(args.buildInfoPath);
        result = await hashScanService.verifyWithSolcJson(
          args.address,
          args.network,
          buildInfo.input,
          buildInfo.compilerVersion,
          args.contractName,
          args.creatorTxHash,
        );
      } else if (args.artifactPath) {
        // Foundry artifact verification
        const artifact = await hashScanService.readFoundryArtifact(args.artifactPath);
  
        // Read source file
        const sourceCode = await fs.readFile(args.filePath, 'utf-8');
  
        result = await hashScanService.verifyContract(
          args.address,
          args.network,
          {
            [`${args.contractName}.sol`]: sourceCode,
            'metadata.json': artifact.metadata,
          },
          args.creatorTxHash,
          args.contractName,
        );
      } else {
        // Direct file verification - read source files from directory or single file
        const stats = await fs.stat(args.filePath);
        const files: Record<string, string> = {};
  
        if (stats.isDirectory()) {
          // Read all .sol files from directory
          const entries = await fs.readdir(args.filePath, { withFileTypes: true });
          for (const entry of entries) {
            if (entry.isFile() && entry.name.endsWith('.sol')) {
              const fullPath = path.join(args.filePath, entry.name);
              const content = await fs.readFile(fullPath, 'utf-8');
              files[entry.name] = content;
            }
          }
        } else {
          // Single file
          const content = await fs.readFile(args.filePath, 'utf-8');
          files[path.basename(args.filePath)] = content;
        }
  
        result = await hashScanService.verifyContract(
          args.address,
          args.network,
          files,
          args.creatorTxHash,
          args.contractName,
        );
      }
  
      if (result.success) {
        const hashScanUrl = hashScanService.getContractUrl(args.address, args.network);
  
        return {
          success: true,
          data: {
            address: result.address,
            chainId: result.chainId,
            status: result.status,
            libraryMap: result.libraryMap,
            hashScanUrl,
            message:
              result.status === 'perfect'
                ? 'Contract verified successfully with perfect match'
                : 'Contract verified with partial match',
          },
          metadata: {
            executedVia: 'hashscan',
            command: 'verify_contract',
          },
        };
      } else {
        return {
          success: false,
          error: result.message || 'Verification failed',
          metadata: {
            executedVia: 'hashscan',
            command: 'verify_contract',
          },
        };
      }
    } catch (error: any) {
      logger.error('Contract verification failed', { error: error.message });
      return {
        success: false,
        error: error.message,
        metadata: {
          executedVia: 'hashscan',
          command: 'verify_contract',
        },
      };
    }
  }

• src/tools/verify.ts:405-444 (schema)

  Complete input schema definition for the verify_contract tool, matching the handler parameters. Used internally or as reference for MCP registration.

  {
    name: 'verify_contract',
    description:
      'Verify a smart contract on HashScan (Hedera block explorer). Supports direct file upload, Hardhat build-info, and Foundry artifacts. Returns verification status and HashScan URL.',
    inputSchema: {
      type: 'object' as const,
      properties: {
        address: {
          type: 'string',
          description: 'Contract address in 0x... format',
          pattern: '^0x[a-fA-F0-9]{40}$',
        },
        network: {
          type: 'string',
          description: 'Hedera network',
          enum: ['mainnet', 'testnet', 'previewnet'],
        },
        contractName: {
          type: 'string',
          description: 'Contract name (e.g., "Greeter")',
        },
        filePath: {
          type: 'string',
          description: 'Path to source file or directory containing .sol files',
        },
        creatorTxHash: {
          type: 'string',
          description: 'Optional: Transaction hash that created the contract',
        },
        buildInfoPath: {
          type: 'string',
          description: 'Optional: Path to Hardhat build-info JSON file for easier verification',
        },
        artifactPath: {
          type: 'string',
          description: 'Optional: Path to Foundry artifact JSON file (out/Contract.sol/Contract.json)',
        },
      },
      required: ['address', 'network', 'contractName', 'filePath'],
    },

• src/index.ts:458-479 (registration)

  MCP tool registration in the optimizedToolDefinitions array, including schema and description. Returned by ListToolsRequestHandler.

    {
      name: 'verify_contract',
      description: `Verify smart contract on HashScan block explorer.
  
  METHODS: Direct source upload, Hardhat build-info, Foundry artifacts
  RETURNS: Verification status and HashScan URL
  
  USE FOR: Contract transparency, code verification, public auditability.`,
      inputSchema: {
        type: 'object' as const,
        properties: {
          address: { type: 'string', description: 'Contract address (0x...)' },
          network: {
            type: 'string',
            enum: ['mainnet', 'testnet', 'previewnet'],
          },
          contractName: { type: 'string', description: 'Contract name' },
          filePath: { type: 'string', description: 'Source file path' },
        },
        required: ['address', 'network', 'contractName', 'filePath'],
      },
    },

• src/index.ts:636-638 (registration)

  Dispatch/execution handler in the main CallToolRequestSchema switch statement that invokes the verifyContract handler.

  case 'verify_contract':
    result = await verifyContract(args as any);
    break;

• src/services/hashscan-service.ts:120-177 (helper)

  Core helper function in HashScanService that performs the actual API verification request to HashScan's Sourcify endpoint.

  async verifyContract(
    address: string,
    network: HederaNetwork,
    files: Record<string, string>,
    creatorTxHash?: string,
    chosenContract?: string,
  ): Promise<VerificationResult> {
    try {
      const chainId = this.getChainId(network);
  
      logger.info('Verifying contract on HashScan', {
        address,
        network,
        chainId,
        fileCount: Object.keys(files).length,
      });
  
      const response = await this.client.post('/verify', {
        address,
        chain: chainId,
        files,
        creatorTxHash,
        chosenContract,
      });
  
      const result = response.data.result?.[0];
      if (!result) {
        throw new Error('No verification result returned');
      }
  
      logger.info('Contract verification successful', {
        address,
        status: result.status,
        chainId: result.chainId,
      });
  
      return {
        success: true,
        address: result.address,
        chainId: result.chainId,
        status: result.status,
        libraryMap: result.libraryMap,
      };
    } catch (error: any) {
      logger.error('Contract verification failed', {
        error: error.message,
        response: error.response?.data,
      });
  
      return {
        success: false,
        address,
        chainId: this.getChainId(network),
        status: 'failed',
        message: error.response?.data?.error || error.message,
      };
    }
  }