Overview

Documentation

HashGraph is the semantic infrastructure layer for HashKey Chain. It transforms raw, unreadable blockchain bytecode into highly structured, AI-readable Protocol Graphs.

Most blockchain tools stop at the ABI. They tell computers how to call a contract, but not what the contract actually does. HashGraph bridges this gap by deterministically compiling a contract's relationships, roles, dependencies, and metadata into a singular Protocol Graph, and then mapping a semantic intent layer on top of it.

Important: HashGraph is strictly read-only infrastructure. It does not execute transactions, hold private keys, or perform audits. It is a semantic data provider for downstream agents and developer tools.

Quick Start

HashGraph is designed to be consumed directly by AI agents. You can run the MCP Server with zero configuration.

1. Global Installation

Install the HashGraph MCP server globally on your machine:

$ npm install -g hashgraph-mcp

2. Run via NPX (Direct execution)

Alternatively, run the server instantly without local installation:

$ npx -y hashgraph-mcp
Architecture

Compiler Pipeline

HashGraph is built on a strict deterministic pipeline. The pipeline operates as a series of pure functions. Data flows strictly downwards.

account_tree
1
Input Contract
Accepts a raw 0x address from HashKey Chain.
2
Blockscout Fetcher
Retrieves verified ABI, source code, and creation transactions.
3
Normalizer (Proxy Resolution)
Detects EIP-1967, EIP-1167, and Diamond Proxies. Deflattens ABI.
4
Deterministic Compiler
Extracts roles, dependencies, events. Generates 100% factual structural graph.
5
Semantic Enrichment
LLM infers intent and developer context based ONLY on the structural graph.

The Deterministic Compiler

The core innovation of HashGraph is the absolute separation of Fact and Inference. The Deterministic Compiler handles the Facts.

  • ABI is Truth: The compiler prioritizes verified ABIs above all other data sources.
  • Dependency Tracing: It scans constructors and immutable public variables to determine what other contracts this protocol relies on.
  • Role Identification: It statically analyzes onlyOwner, hasRole, and standard modifiers to build an authorization map.

The Semantic Engine

While structural data is perfect for computers, AI agents and humans need context. The Semantic Engine provides this layer while adhering to strict safety rules.

cancel What it Cannot Do
  • Cannot invent blockchain facts
  • Cannot guess a variable type
  • Cannot perform security audits
  • Cannot calculate confidence scores
check_circle What it Can Do
  • Summarize the protocol's goal
  • Group related functions (e.g. "Liquidation")
  • Explain what a transaction calldata intends
  • Provide integration notes for developers

* Note on Confidence: Confidence scores are computed deterministically. The LLM is forbidden from assigning its own confidence levels.

Components

The Protocol Graph Schema

The final output of the pipeline is a standardized JSON schema representing the ProtocolGraph.

data_object Metadata

Core identification strings, proxy configurations, and compilation states.

"metadata": {
  "protocol_name": "Lending Vault",
  "contract_address": "0x42...",
  "compiler_version": "1.0",
  "is_proxy": true,
  "implementation": "0xc0d3..."
}

account_tree Structural (Deterministic)

The absolute truth extracted from the ABI. Guaranteed to match the on-chain bytecode.

"structural": {
  "roles": ["Owner", "Guardian", "Operator"],
  "dependencies": [
    { "target": "0xabc...", "type": "Oracle" }
  ],
  "events": ["Deposit", "Withdraw", "Liquidate"],
  "functions": 24
}

psychology Semantic & Security (AI Layer)

Inferred human-readable context layered safely on top of the structure.

"semantic": {
  "intent": "Manages collateralized debt positions...",
  "user_goal": "Deposit USDC to borrow synthetic assets."
},
"security": {
  "guardrails": ["Requires Oracle heartbeat within 1hr"],
  "privileged_functions": ["pause()", "upgradeTo()"]
}

SDK Integration (Developer Preview)

The programmatic SDK is fully developed and exported directly from the published NPM package. You can install it and import the client class to build custom programmatic integrations: 

import { HashGraphClient } from "hashgraph-mcp";

// Initialize client
const client = new HashGraphClient({
  rpcUrl: process.env.RPC_URL,
  cacheMode: "HIT_OR_COMPILE"
});

// Fetch the full compiled graph
const graph = await client.getProtocolGraph(
  "0x4200000000000000000000000000000000000015"
);

console.log("Roles detected:", graph.structural.roles);
console.log("AI Summary:", graph.semantic.intent);

MCP Server (For AI Agents)

The Model Context Protocol (MCP) server allows AI agents like Claude Desktop or Cursor to directly interact with the deterministic HashGraph compiler without you having to write any code.

Claude Desktop Setup

Add this to your ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "hashgraph": {
      "command": "npx",
      "args": ["-y", "hashgraph-mcp"]
    }
  }
}

Restart Claude, and you can now ask Claude questions like: "Analyze contract 0x... and tell me what dependencies it has."

Available Tools (Exposed via MCP)

info Concept Clarification: Tools vs. Functions

It is easy to confuse MCP Server Tools with Contract ABI Functions:

MCP Server Tools (9 Methods)

The APIs exposed by the HashGraph MCP server to AI agents (e.g. get_protocol_graph, explain_transaction).

Contract ABI Functions (e.g., 21 Functions)

The smart contract functions written in Solidity and deployed on-chain (e.g. transfer, setOwner) that HashGraph compiles.

Tool Name Parameters Description
get_protocol_graph address Compiles a smart contract address into a structured JSON graph containing roles, dependencies, events, and intent.
get_contract_summary address Returns a lightweight structural and metadata overview of a contract.
explain_transaction address, calldata Decodes raw transaction calldata and evaluates its safety based on the compiled deterministic graph.
search_protocol address, query Searches the cached protocol graphs for specific privileges, standard interfaces, or variables.
simulate_transaction to, data, from?, value? Simulates a transaction against the blockchain to see its outcome without writing state.
read_contract address, data Reads state variables or evaluates view functions directly from the contract.
get_source_code address Fetches fully resolved, unflattened Solidity source code for verified contracts.
lookup_graph_attestation address Checks the on-chain HashKey Mainnet attestation registry for a protocol graph hash.
register_protocol_graph address, graphHash, metadataURI Registers a deterministic protocol graph hash to the mainnet registry (gated by default).

Interactive Examples

The best way to understand the Protocol Graph is to compile one yourself.

HashGraph Explorer

Paste any HashKey Chain contract address into the Explorer to watch the Deterministic Compiler pipeline in real time.

Open Explorer arrow_forward
ml>