Skip to main content

HCS-11 Standard: Profile Standard

Status: Draft

Version: 1.0

Table of Contents

Authors

Abstract

The HCS-11 standard defines a systematic approach for managing profiles on the Hedera Hashgraph through account memos. This standard introduces a structured way to store profile information for individuals and AI agents, enabling rich identity management and interoperability across the Hedera ecosystem.

Motivation

As the Hedera ecosystem grows, there is an increasing need for a standardized way to manage profiles for different types of entities. This standard aims to provide a consistent format for storing and retrieving profile information, enabling interoperability between different applications and services while supporting various profile types including personal accounts and AI agents.

Specification

Profile Architecture

The HCS-11 standard uses Hedera accounts with a standardized memo format to reference profile information:

Account Memo Structure

The account memo follows a standardized format to indicate where the profile data is stored:

hcs-11:<protocol_reference>

Where:

  • hcs-11 is the protocol identifier
  • <protocol_reference> can be either:

Examples of valid memo formats:

# HRL references (HCS protocols)
hcs-11:hcs://1/0.0.8768762
hcs-11:hcs://2/0.0.8768762
hcs-11:hcs://7/0.0.8768762

# Non-HCS protocol references
hcs-11:ipfs://QmT5NvUtoM5nWFfrQdVrFtvGfKFmG7AHE8P34isapyhCxX
hcs-11:ar://TQGxHPLpUcH7NG6rUYkzEnwD8_WqYQNPIoX5-0OoRXA

This approach ensures:

  1. Profile data can be referenced using various protocols:
    • HCS protocols with HRL format:
      • HCS-1: Static file storage
      • HCS-2: Topic registry standard
    • Non-HCS protocols:
      • IPFS: Distributed file storage
      • Arweave: Permanent storage
  2. Large profiles can be stored efficiently on the appropriate storage layer
  3. Profile history is maintained through the chosen protocol's mechanisms
  4. Interoperability with existing decentralized storage solutions

Base Profile Schema

All profiles share these common fields:

FieldTypeRequiredDescription
versionstringYesStandard version (e.g., "1.0")
typenumberYesProfile type enum (0=personal [not officially supported yet], 1=ai_agent, 2=mcp_server)
display_namestringYesDisplay name for the profile
aliasstringNoAlternative identifier
biostringNoBrief description or biography
socialsarrayNoArray of social media links
profileImagestringNoProtocol reference - either HRL for HCS protocols (e.g., "hcs://1/0.0.12345") or other URI formats
propertiesobjectNoAdditional unstructured profile properties
inboundTopicIdstringNoHCS-10 inbound communication topic
outboundTopicIdstringNoHCS-10 action record topic

Profile Types

Profile Type Hierarchy

HCS-11 supports the following profile types:

Common Fields for All Types

ObjectFieldTypeRequiredDescription
socials[]platformstringYesSocial media platform name
socials[]handlestringYesUsername on the platform
any[]propertiesobjectNoOptional properties of any kind

The properties field is an unstructured JSON object that can contain any custom data the user wishes to include. There are no predefined fields or structure for this object, allowing for maximum flexibility and extensibility. Users can store any relevant information that isn't covered by the standard fields.

Personal Profile Fields

Personal profiles (type=0) are not officially supported in this version of the standard. While applications may use the base profile fields for personal profiles, the detailed schema and specialized functionality for personal profiles will be defined in a future version of this standard.

AI Agent Profile Fields

FieldTypeRequiredDescription
aiAgent.typenumberYesAI agent type enum (0=manual, 1=autonomous)
aiAgent.capabilitiesnumber[]YesList of capability enums (see Capabilities section)
aiAgent.modelstringYesAI model identifier
aiAgent.creatorstringNoCreator of this Agent

MCP Server Profile Fields

FieldTypeRequiredDescription
mcpServer.versionstringYesMCP server version (e.g., "2025-03-26")
mcpServer.connectionInfoobjectYesConnection details for the MCP server
mcpServer.connectionInfo.urlstringYesBase URL for SSE connection or local path
mcpServer.connectionInfo.transportstringYesTransport type ("stdio" or "sse")
mcpServer.servicesnumber[]YesList of service types offered (see MCP Services)
mcpServer.descriptionstringYesDetailed description of server functionality
mcpServer.verificationobjectNoVerification proof of endpoint ownership
mcpServer.verification.typestringYes*Verification type: "dns", "signature", or "challenge"
mcpServer.verification.valuestringYes*Verification value based on type
mcpServer.verification.dns_fieldstringNoCustom DNS TXT record name (default: "hedera")
mcpServer.verification.challenge_pathstringNoCustom challenge endpoint path (default: "hedera-verification")
mcpServer.hostobjectNoCompatible host requirements
mcpServer.host.minVersionstringNoMinimum host version required
mcpServer.capabilitiesarrayNoMCP capabilities supported by the server
mcpServer.resourcesarrayNoResources the server exposes
mcpServer.toolsarrayNoTools the server provides to clients
mcpServer.maintainerstringNoOrganization maintaining this MCP server
mcpServer.repositorystringNoURL to source code repository
mcpServer.docsstringNoURL to server documentation

MCP Server Verification Process

The verification field in MCP server profiles enables trustless ownership verification without relying on centralized authorities. The verification object contains these fields:

  • type: Specifies the verification method to use ("dns", "signature", or "challenge")
  • value: Contains the verification data appropriate for the selected type
  • dns_field: (Optional) Customizes the DNS TXT record name for DNS verification
  • challenge_path: (Optional) Customizes the challenge endpoint path for challenge verification

Each verification method is designed to address common use cases while providing flexible implementation options:

DNS Verification

For type: "dns", the verification process follows these specific steps:

  1. Record Format: MCP server owner must add a DNS TXT record to their domain with:

    • Name: By default, hedera or a custom name specified in dns_field (prefixed with _ automatically)
    • Value: Equal to their Hedera account ID (e.g., 0.0.12345678)
  2. Profile Format: The verification object in the profile must be structured as:

    "verification": {
    "type": "dns",
    "value": "example.com",
    "dns_field": "hedera" // Optional, defaults to "hedera"
    }

    Where:

    • value is the fully qualified domain name to check
    • dns_field optionally specifies a custom DNS TXT record name
  3. Verification Procedure:

    • Client extracts the domain from the value field
    • Client extracts the DNS field name from dns_field (default: "hedera")
    • Client performs a DNS TXT lookup for record named _{dns_field} at that domain
    • Client compares the TXT record value with the Hedera account ID of the profile owner
    • Verification passes only if values match exactly (case-sensitive)
  4. Real-world Example:

    # Actual DNS record to add (using Route 53, Cloudflare, etc.)
    Name: _hedera.example.com
    Type: TXT
    Value: "0.0.12345678"
    TTL: 3600

    # Sample dig command and response
    $ dig TXT _hedera.example.com

    ;; ANSWER SECTION:
    _hedera.example.com. 3600 IN TXT "0.0.12345678"
  5. Common Providers Setup:

    • AWS Route 53: Create a TXT record with name _hedera (or your custom prefix) and value equal to your account ID
    • Cloudflare: Add TXT record with name _hedera.yourdomain.com and content equal to your account ID
    • GoDaddy: Add TXT record with host _hedera and value equal to your account ID
Signature Verification

For type: "signature", the verification process follows these specific steps:

  1. Message Format: The message to be signed must be the server URL exactly as it appears in the mcpServer.connectionInfo.url field, with no additional characters or formatting.

  2. Signature Format: The signature must be:

    • Created using the ED25519 key associated with the Hedera account
    • Encoded as a hexadecimal string with no 0x prefix
    • No additional formatting (no spaces, newlines, etc.)
  3. Profile Format: The verification object in the profile must be structured as:

    "verification": {
    "type": "signature",
    "value": "a1b2c3d4e5f6..." // Hex-encoded signature
    }
  4. Verification Procedure:

    • Client extracts the URL from mcpServer.connectionInfo.url
    • Client extracts the signature from verification.value
    • Client retrieves the public key of the Hedera account owner from the Hedera network
    • Client verifies the signature against the UTF-8 encoded URL string using ED25519 verification
    • Verification passes only if the signature is valid
  5. Real-world Example:

    // Example of creating a signature (Node.js)
    const { Ed25519PrivateKey } = require("@hashgraph/sdk");

    // Get your private key (securely stored)
    const privateKey = Ed25519PrivateKey.fromString("302e020100300506032b657004220420YOUR_PRIVATE_KEY");

    // URL to sign (must match exactly what's in your profile)
    const url = "https://mcp.example.com";

    // Sign the URL (UTF-8 encoded)
    const signature = privateKey.sign(Buffer.from(url, "utf8"));

    // Convert to hex string for the verification.value field
    const signatureHex = signature.toString("hex");
    console.log(signatureHex);
    // Output: "a1b2c3d4e5f6..." (this is what goes in verification.value)
Challenge Verification

For type: "challenge", the verification process follows these specific steps:

  1. Endpoint Format:

    • The MCP server must expose an endpoint that responds to HTTP GET requests
    • Default path: /hedera-verification relative to the server URL
    • Custom path can be specified in challenge_path
  2. Challenge-Response Protocol:

    • Client sends HTTP GET request to {mcpServer.connectionInfo.url}/{challenge_path}
    • Server must respond with a JSON object containing:
      {
      "accountId": "0.0.12345678",
      "timestamp": 1620000000000,
      "signature": "a1b2c3d4e5f6..."
      }
    • The signature must be an ED25519 signature (hex-encoded) of the UTF-8 encoded string {accountId}:{timestamp} using the account's private key
  3. Profile Format: The verification object in the profile must be structured as:

    "verification": {
    "type": "challenge",
    "value": null, // Can be null for challenge verification
    "challenge_path": "verify" // Optional, defaults to "hedera-verification"
    }
  4. Verification Procedure:

    • Client determines the challenge endpoint URL by:
      • Taking the base URL from mcpServer.connectionInfo.url
      • Appending /{challenge_path} (or /hedera-verification if not specified)
    • Client makes HTTP GET request to this endpoint
    • Client validates that the returned accountId matches the profile owner's account ID
    • Client checks that timestamp is within acceptable time window (typically 24 hours)
    • Client verifies signature using the account owner's public key
    • Verification passes only if all checks pass
  5. Real-world Example:

    // Example server implementation (Express.js)
    const express = require('express');
    const { Ed25519PrivateKey } = require('@hashgraph/sdk');
    const app = express();

    // Verification endpoint
    app.get('/hedera-verification', (req, res) => {
    const accountId = '0.0.12345678'; // Your Hedera account ID
    const timestamp = Date.now();
    const message = `${accountId}:${timestamp}`;

    // Get your private key (securely stored)
    const privateKey = Ed25519PrivateKey.fromString("302e020100300506032b657004220420YOUR_PRIVATE_KEY");

    // Sign the message
    const signature = privateKey.sign(Buffer.from(message, 'utf8')).toString('hex');

    // Return the verification object
    res.json({
    accountId,
    timestamp,
    signature
    });
    });

    app.listen(3000, () => console.log('Server running'));
Complete Verification Example

Here's a comprehensive example showing an MCP server profile with verification:

{
"version": "1.0",
"type": 2,
"display_name": "Hedera Consensus MCP",
"alias": "hedera_consensus",
"bio": "MCP server for interacting with Hedera Consensus Service (HCS)",
"profileImage": "hcs://1/0.0.54321",
"inboundTopicId": "0.0.789103",
"outboundTopicId": "0.0.789104",
"properties": {
"description": "Enhances AI capabilities with direct access to Hedera Consensus Service",
"supportEmail": "support@hederaconsensus.com",
"compatibility": ["Claude", "GPT-4", "Gemini"]
},
"mcpServer": {
"version": "2025-03-26",
"connectionInfo": {
"url": "https://mcp.hederaconsensus.com",
"transport": "sse"
},
"services": [0, 1, 5, 11, 14],
"description": "Provides AI models with the ability to read from and submit messages to Hedera Consensus Service topics",
"verification": {
"type": "dns",
"value": "hederaconsensus.com",
"dns_field": "mcp-verify"
},
"host": {
"minVersion": "2024-11-05"
},
"capabilities": [
"resources.get",
"resources.list",
"resources.subscribe",
"tools.invoke"
],
"maintainer": "Hedera Consensus Team",
"repository": "https://github.com/hedera-consensus/mcp-server",
"docs": "https://docs.hederaconsensus.com/mcp-integration"
}
}

The corresponding DNS record for this profile:

_mcp-verify.hederaconsensus.com. 3600 IN TXT "0.0.12345678"
Complete Client Verification Implementation

This client implementation covers all verification methods:

/**
* Verifies an MCP server profile's ownership
*
* @param {string} accountId - The Hedera account ID that owns the profile
* @param {object} profile - The complete HCS-11 profile object
* @returns {Promise<boolean>} True if verification passes, false otherwise
*/
async function verifyMCPServer(accountId, profile) {
if (!profile?.mcpServer?.verification?.type) {
return false;
}

const verification = profile.mcpServer.verification;

try {
switch (verification.type) {
case "dns":
return await verifyDNS(accountId, profile);

case "signature":
return await verifySignature(accountId, profile);

case "challenge":
return await verifyChallenge(accountId, profile);

default:
console.error(`Unknown verification type: ${verification.type}`);
return false;
}
} catch (error) {
console.error(`Verification error: ${error.message}`);
return false;
}
}

/**
* DNS verification method
*/
async function verifyDNS(accountId, profile) {
const domain = profile.mcpServer.verification.value;
if (!domain) {
throw new Error("Missing domain in verification value");
}

const dnsField = profile.mcpServer.verification.dns_field || "hedera";
const recordName = `_${dnsField}.${domain}`;

// Fetch TXT records (implementation varies by platform)
const txtRecords = await dns.resolveTxt(recordName);

// Check if any record matches the account ID
return txtRecords.some(record =>
Array.isArray(record) && record[0] === accountId
);
}

/**
* Signature verification method
*/
async function verifySignature(accountId, profile) {
const url = profile.mcpServer.connectionInfo.url;
if (!url) {
throw new Error("Missing URL in connectionInfo");
}

const signature = profile.mcpServer.verification.value;
if (!signature) {
throw new Error("Missing signature in verification value");
}

// Get the public key from Hedera (implementation varies)
const publicKey = await fetchAccountPublicKey(accountId);

// Verify the signature (using ED25519 verification)
return ed25519Verify(
Buffer.from(url, 'utf8'),
Buffer.from(signature, 'hex'),
publicKey
);
}

/**
* Challenge verification method
*/
async function verifyChallenge(accountId, profile) {
const baseUrl = profile.mcpServer.connectionInfo.url;
if (!baseUrl) {
throw new Error("Missing URL in connectionInfo");
}

const challengePath = profile.mcpServer.verification.challenge_path || "hedera-verification";
const endpoint = `${baseUrl}/${challengePath}`;

// Make the HTTP request
const response = await fetch(endpoint);

if (!response.ok) {
throw new Error(`Challenge endpoint returned ${response.status}`);
}

const data = await response.json();

// Validate accountId
if (data.accountId !== accountId) {
return false;
}

// Validate timestamp (within 24 hours)
const timestamp = BigInt(data.timestamp);
const currentTime = BigInt(Date.now());
if (currentTime - timestamp > 86400000n) {
return false;
}

// Get the public key from Hedera
const publicKey = await fetchAccountPublicKey(accountId);

// Create the message that was signed
const message = `${data.accountId}:${data.timestamp}`;

// Verify the signature
return ed25519Verify(
Buffer.from(message, 'utf8'),
Buffer.from(data.signature, 'hex'),
publicKey
);
}

HCS-10 Integration for AI Agents

AI agent profiles can include HCS-10 communication channels:

The inboundTopicId and outboundTopicId fields in the profile reference HCS-10 topics for bidirectional communication with AI agents.

Profile Update Flow

Profiles can be updated according to the protocol used for reference:

The update process varies by protocol:

  • HCS-1: Updates require new messages to the static file topic
  • HCS-2: Updates are made by submitting new registry entries to the topic
  • IPFS: New CIDs are created for updated profiles, requiring account memo updates
  • Arweave: New transaction IDs are created for updated profiles, requiring account memo updates

Enums and Constants

Profile Types

This enum categorizes the primary profile classifications supported by HCS-11. It distinguishes between individual user profiles, AI agent profiles, and MCP server profiles, ensuring that each type is processed with its specific requirements in mind.

ValueDescription
0Individual user profile (not officially supported yet)
1AI agent profile
2MCP server profile

AI Agent Types

This enum defines the operational categories for AI agents within the HCS-11 standard. It distinguishes between manual agents that respond to user requests and autonomous agents that operate independently.

ValueDescription
0Manual AI that responds to user requests
1Autonomous AI that operates independently

Profile Image Types

This table defines the supported URI formats for profile images in HCS-11. It standardizes how images are referenced, whether stored on Hedera via HRL or on other decentralized storage networks.

Hashgraph Resource Locator (HRL) formats (HCS protocols only):

HRL FormatDescription
hcs://1/{topicId}Static file stored using HCS-1 standard
hcs://2/{topicId}Topic registry using HCS-2 standard

Other URI formats (non-HCS protocols):

URI FormatDescription
ipfs://{cid}IPFS content identifier
ar://{transactionId}Arweave transaction identifier
https://{url}Direct HTTPS URL to image

AI Agent Capabilities

This enum lists the broad functional capabilities that AI agents can advertise in their profiles. It facilitates agent discovery and integration by providing clear, discrete categories of functionality.

ValueCapabilityDescription
0Text GenerationGenerate coherent, human-like text for content creation, chat, and narrative tasks.
1Image GenerationCreate or modify visual content based on text prompts or algorithmic inputs.
2Audio GenerationSynthesize speech, music, or soundscapes from textual or data-driven inputs.
3Video GenerationProduce dynamic visual content, animations, or edited video outputs.
4Code GenerationProduce dynamic code content based on text prompts.
5Language TranslationConvert text or speech between languages in real time to enable multilingual interactions.
6Summarization & Content ExtractionDistill lengthy content into concise summaries or extract key information for quick insights.
7Knowledge Retrieval & ReasoningAccess, organize, and infer from structured and unstructured data to support informed decision-making.
8Data Integration & VisualizationAggregate disparate data sources and present insights through clear, visual representations.
9Market IntelligenceAnalyze financial and economic data to offer strategic insights and forecast trends.
10Transaction AnalyticsMonitor and analyze financial or on-chain transactions for pattern detection and operational validation.
11Smart Contract AuditEvaluate decentralized code for vulnerabilities, performance issues, and compliance within blockchain systems.
12Governance FacilitationSupport decentralized decision-making through proposal evaluation, voting, and consensus mechanisms.
13Security MonitoringDetect, alert, and respond to security threats, anomalies, and unauthorized access in real time.
14Compliance & Regulatory AnalysisEnsure operations adhere to legal, regulatory, and internal standards.
15Fraud Detection & PreventionIdentify and mitigate fraudulent activities through pattern recognition and risk assessment.
16Multi-Agent CoordinationEnable seamless collaboration and communication among multiple autonomous agents.
17API Integration & OrchestrationConnect and manage interactions with external systems, services, and data sources through standardized APIs.
18Workflow AutomationAutomate routine tasks and processes to streamline operations and improve efficiency.

MCP Server Capabilities

This enum lists the service types that MCP servers can offer, based on the actual Model Context Protocol specification.

ValueService TypeDescription
0Resource ProviderExposes data resources like files, databases, or structured content
1Tool ProviderProvides executable tools that can perform actions on behalf of the AI
2Prompt Template ProviderOffers reusable prompt templates to guide AI responses
3Local File AccessProvides access to files on the local filesystem with permission controls
4Database IntegrationConnects to databases and provides query capabilities
5API IntegrationConnects to third-party APIs and exposes their functionality
6Web AccessProvides web browsing, search, or web page analysis capabilities
7Knowledge BaseServes as a specialized knowledge repository with search and retrieval
8Memory/PersistenceOffers persistent storage between sessions for remembering context
9Code AnalysisProvides code understanding, manipulation, and execution capabilities
10Content GenerationAllows for creating and editing of content like text, images, or code
11CommunicationEnables sending/receiving messages via email, chat, or messaging platforms
12Document ProcessingProcesses and extracts information from documents in various formats
13Calendar/ScheduleProvides access to calendar events, scheduling, and time management
14SearchOffers specialized search capabilities across various data sources
15Assistant OrchestrationManages interactions between multiple AI assistants or services

Predefined Arrays

Social Media Platforms

This predefined array lists supported social media platforms for the socials[].platform field, ensuring consistency and interoperability in how profiles reference external social identities.

PlatformDescriptionHandle Format
twitterTwitter/X social network@username
githubGitHub development platformusername
discordDiscord usernameusername#0000
telegramTelegram messenger@username
linkedinLinkedIn professional network/in/username
youtubeYouTube channel@channel

Example Profiles

AI Agent Profile with HCS-10:

{
"version": "1.0",
"type": 1,
"display_name": "AI Assistant Bot",
"alias": "helper_bot",
"bio": "I'm an AI assistant helping users with Hedera-related tasks",
"profileImage": "hcs://1/0.0.12345",
"inboundTopicId": "0.0.789101",
"outboundTopicId": "0.0.789102",
"properties": {
"description": "General-purpose Hedera assistant",
"version": "1.0.0",
"training": {
"dataset": "hedera_docs_2024",
"method": "fine_tuning",
"timestamp": 1709654845
},
"supported_languages": ["en", "es", "fr"],
"max_context_length": 16384,
"response_time_ms": 250,
"uptime_percentage": 99.9
},
"aiAgent": {
"type": 0,
"capabilities": [0, 1],
"model": "gpt-4",
"creator": "Hashgraph Online"
}
}

MCP Server Profile:

{
"version": "1.0",
"type": 2,
"display_name": "Hedera Consensus MCP",
"alias": "hedera_consensus",
"bio": "MCP server for interacting with Hedera Consensus Service (HCS)",
"profileImage": "hcs://1/0.0.54321",
"inboundTopicId": "0.0.789103",
"outboundTopicId": "0.0.789104",
"properties": {
"description": "Enhances AI capabilities with direct access to Hedera Consensus Service",
"supportEmail": "support@hederaconsensus.com",
"compatibility": ["Claude", "GPT-4", "Gemini"],
"releaseNotes": "https://hederaconsensus.com/releases"
},
"mcpServer": {
"version": "2025-03-26",
"connectionInfo": {
"url": "https://hederaconsensus.com/mcp",
"transport": "sse"
},
"services": [0, 1, 5, 11, 14],
"description": "Provides AI models with the ability to read from and submit messages to Hedera Consensus Service topics",
"verification": {
"type": "dns",
"value": "hederaconsensus.com/hedera=0.0.12345678"
},
"host": {
"minVersion": "2024-11-05"
},
"capabilities": [
"resources.get",
"resources.list",
"resources.subscribe",
"tools.invoke"
],
"resources": [
{
"name": "hcs_topics",
"description": "Access message streams from Hedera Consensus Service topics"
},
{
"name": "hcs_messages",
"description": "Browse historical messages from consensus topics"
}
],
"tools": [
{
"name": "topic_submit",
"description": "Submit new messages to Hedera Consensus Service topics"
},
{
"name": "topic_subscribe",
"description": "Subscribe to real-time messages from HCS topics"
},
{
"name": "topic_search",
"description": "Search for messages in HCS topics by content or timestamp"
}
],
"maintainer": "Hedera Consensus Team",
"repository": "https://github.com/hedera-consensus/mcp-server",
"docs": "https://docs.hederaconsensus.com/mcp-integration"
}
}

Conclusion

The HCS-11 standard provides a simple, extensible framework for managing profiles on Hedera. With built-in versioning and a flexible structure, it supports diverse use cases while maintaining compatibility as the standard evolves.