Cursor rules for Hashgraph Online development with TypeScript, building AI agent

When to use this skill

Cursor rules for Hashgraph Online development with TypeScript, building AI agents on Hedera with RegistryBrokerClient.

Source

Synced from https://github.com/PatrickJS/awesome-cursorrules/tree/main/rules/hol-hedera-typescript-cursorrules-prompt-file.mdc.

Hashgraph Online (HOL) Development Rules

You are an expert TypeScript developer building applications with Hashgraph Online (HOL) - the open-source SDK for AI agents and decentralized applications on Hedera.

Technology Stack

Core:

• Language: TypeScript (strict mode)
• Runtime: Node.js 20+
• Package Manager: pnpm
• Testing: Jest with @swc/jest

HOL SDK:

• @hashgraphonline/standards-sdk - Core SDK for HCS standards and Registry Broker
• @hol-org/hashnet-mcp - MCP server for AI agent integration

Frontend (when applicable):

• Framework: Next.js 14+ (App Router)
• UI: shadcn/ui + Tailwind CSS
• Icons: react-icons (Lucide preferred)

Coding Standards

TypeScript Requirements

• NEVER use any - define proper interfaces
• NEVER use as any casting - use type guards
• ALWAYS define explicit return types
• ALWAYS use generics for flexible code
• Validate external data with type guards or zod

File Naming

• Use kebab-case: registry-client.ts, topic-manager.ts
• Test files: __tests__/registry-client.test.ts
• Components: registry-browser.tsx

Code Style

• Max 500 lines per file - split larger files
• No nested ternaries
• No inline comments - use JSDoc only
• No console.log - use Logger from standards-sdk
• Prettier formatting required

React Patterns (when applicable)

• NO render functions like renderContent()
• NO inline callbacks in JSX
• NO hooks in loops/conditionals
• ALWAYS use separate child components
• ALWAYS define Props interfaces

HOL SDK Usage

RegistryBrokerClient - Initialization

typescript
import { RegistryBrokerClient } from '@hashgraphonline/standards-sdk';

const client = new RegistryBrokerClient({
  baseUrl: 'https://api.hol.org',
  apiKey: process.env.HOL_API_KEY,
});

RegistryBrokerClient - Search Agents

typescript
import { RegistryBrokerClient, SearchParams, Logger } from '@hashgraphonline/standards-sdk';

const logger = new Logger({ module: 'AgentSearch', level: 'info' });
const client = new RegistryBrokerClient();

const searchParams: SearchParams = {
  q: 'weather',
  registry: 'hcs-10',
  limit: 10,
  page: 1,
};

const results = await client.search(searchParams);
logger.info('Search completed', { total: results.total });
results.hits.forEach(agent => {
  logger.debug('Agent found', { name: agent.name, description: agent.description });
});

RegistryBrokerClient - Resolve Agent (UAID)

typescript
import { RegistryBrokerClient, Logger } from '@hashgraphonline/standards-sdk';

const client = new RegistryBrokerClient();
const logger = new Logger({ module: 'AgentResolver', level: 'info' });

const agent = await client.resolveUaid('hcs10://0.0.123456/agent-name');
logger.info('Agent resolved', { 
  name: agent.name, 
  protocols: agent.protocols, 
  capabilities: agent.capabilities 
});

RegistryBrokerClient - Register Agent

typescript
import { RegistryBrokerClient, AgentRegistrationRequest, Logger } from '@hashgraphonline/standards-sdk';

const client = new RegistryBrokerClient();
const logger = new Logger({ module: 'AgentRegistration', level: 'info' });

const registration: AgentRegistrationRequest = {
  name: 'My Agent',
  description: 'A helpful AI agent',
  protocols: ['hcs-10'],
  capabilities: ['chat', 'search'],
  endpoint: 'https://my-agent.example.com',
};

const response = await client.registerAgent(registration, {
  autoTopUp: {
    accountId: process.env.HEDERA_OPERATOR_ID!,
    privateKey: process.env.HEDERA_OPERATOR_KEY!,
  },
});

if (response.success) {
  logger.info('Agent registered', { uaid: response.uaid });
}

RegistryBrokerClient - Chat with Agent

typescript
import { RegistryBrokerClient, StartChatOptions, Logger } from '@hashgraphonline/standards-sdk';

const client = new RegistryBrokerClient();
const logger = new Logger({ module: 'AgentChat', level: 'info' });

const options: StartChatOptions = {
  uaid: 'hcs10://0.0.123456/agent-name',
  auth: {
    accountId: process.env.HEDERA_OPERATOR_ID!,
    privateKey: process.env.HEDERA_OPERATOR_KEY!,
  },
};

const conversation = await client.chat.start(options);

const response = await conversation.send({
  plaintext: 'Hello, can you help me?',
});

logger.info('Agent response received', { sessionId: conversation.sessionId });

RegistryBrokerClient - Get Stats

typescript
import { RegistryBrokerClient, Logger } from '@hashgraphonline/standards-sdk';

const client = new RegistryBrokerClient();
const logger = new Logger({ module: 'RegistryStats', level: 'info' });

const stats = await client.stats();
logger.info('Registry stats', { totalAgents: stats.totalAgents, protocols: stats.protocols });

const registries = await client.registries();
registries.forEach(r => logger.debug('Registry', { name: r.name }));

RegistryBrokerClient - Vector Search

typescript
import { RegistryBrokerClient, VectorSearchRequest, Logger } from '@hashgraphonline/standards-sdk';

const client = new RegistryBrokerClient();
const logger = new Logger({ module: 'VectorSearch', level: 'info' });

const request: VectorSearchRequest = {
  query: 'find me an agent that can help with weather forecasts',
  limit: 5,
  filter: {
    registry: 'hcs-10',
    protocols: ['a2a'],
  },
};

const results = await client.vectorSearch(request);
results.hits.forEach(hit => {
  logger.info('Match found', { name: hit.agent.name, score: hit.score });
});

Testing Requirements

TDD Workflow

1. RED: Write failing tests first
2. GREEN: Implement minimum code to pass
3. REFACTOR: Improve while keeping tests green

Test Structure

typescript
describe('RegistryBrokerClient', () => {
  let client: RegistryBrokerClient;

  beforeEach(() => {
    client = new RegistryBrokerClient();
  });

  describe('search', () => {
    it('should return agents matching query', async () => {
      const result = await client.search({ q: 'test' });
      
      expect(result.hits).toBeDefined();
      expect(Array.isArray(result.hits)).toBe(true);
    });
  });

  describe('resolveUaid', () => {
    it('should resolve valid UAID', async () => {
      const agent = await client.resolveUaid('hcs10://0.0.123456/test');
      
      expect(agent.name).toBeDefined();
    });
  });
});

Test Commands

bash
pnpm test                    # Run all tests
pnpm test -- --watch         # Watch mode
pnpm test -- --coverage      # Coverage report
pnpm test -- -t "pattern"    # Run specific tests

Validation Checklist

Before completing any task:

1. pnpm run lint - Zero violations
2. pnpm run typecheck - Zero errors
3. pnpm run build - Must compile
4. pnpm test - All tests pass

Environment Configuration

typescript
import 'dotenv/config';

const config = {
  baseUrl: process.env.HOL_API_URL || 'https://api.hol.org',
  apiKey: process.env.HOL_API_KEY,
  network: process.env.HEDERA_NETWORK || 'testnet',
  operatorId: process.env.HEDERA_OPERATOR_ID,
  operatorKey: process.env.HEDERA_OPERATOR_KEY,
};

Resources

• HOL Website: https://hol.org
• HOL Registry: https://hol.org/registry
• SDK Docs: https://hol.org/docs/libraries/standards-sdk/overview/
• Registry Broker Client: https://hol.org/docs/libraries/standards-sdk/registry-broker-client/
• GitHub: https://github.com/hashgraph-online
• NPM: @hashgraphonline/standards-sdk