@zkred/hedera-agentid-plugin

v7.0.2

Published

15 days ago

A Hedera Agent Kit plugin to generate Privado ID DIDs using @zkred/agent-id SDK.

Downloads

350

0High
0Medium
0Low

vkpatva

13jay96

sarkazein

hedera plugin agentkit zkred ssi privado-id did

Zkred Agent ID Hedera Plugin

A comprehensive Hedera Agent Kit plugin that provides a complete identity management solution for decentralized agents. Built by the Zkred Team, this plugin enables developers to create, manage, and verify digital identities using Privado ID Decentralized Identifiers (DIDs) within Hedera Agent Kit workflows.

The plugin provides seamless integration between Hedera's distributed ledger technology and Zkred's identity management system, offering a full suite of tools for agent identity creation, validation, handshake protocols, and signature verification.

Now compatible with ERC 8004 (Identity Registry) contracts deployed on Hedera Testnet, providing enhanced identity management capabilities with token URI support and metadata storage.

Installation

npm install @zkred/hedera-agentid-plugin

ERC 8004 Compatibility

This plugin now supports ERC 8004 (Identity Registry) standard contracts deployed on Hedera Testnet. The Identity Registry contract provides:

ERC 721 Token-based Identity: Each agent identity is represented as an NFT token
Token URI Support: Optional token URI for each agent identity
Metadata Storage: Key-value metadata storage for each agent
Upgradeable Contract: UUPS upgradeable contract pattern for future enhancements
Contract Address: 0x4c74ebd72921d537159ed2053f46c12a7d8e5923 (Hedera Testnet)

The new register_agent and register_agent_with_metadata tools interact directly with the ERC 8004 Identity Registry contract, providing enhanced identity management capabilities.

Usage

import { zkredAgentIdPlugin } from "@zkred/hedera-agentid-plugin";

const hederaAgentToolkit = new HederaLangchainToolkit({
  client,
  configuration: {
    context: {
      mode: AgentMode.AUTONOMOUS,
    },
    plugins: [
      coreTokenPlugin,
      coreAccountPlugin,
      coreConsensusPlugin,
      coreQueriesPlugin,
      zkredAgentIdPlugin,
    ],
  },
});

Available Tools

This plugin provides 11 comprehensive tools for complete identity management and agent interaction:

| Tool Name | Description | Method | | --------------------------------- | ---------------------------------------------------------------------------- | --------------------------------- | | generate_agent_did | Generates a Privado ID DID from an Ethereum address using the iden3 protocol | generate_agent_did | | get_publickey_from_did | Extracts Ethereum public key from a DID string | get_publickey_from_did | | create_identity | Creates a new agent identity on the blockchain registry | create_identity | | register_agent | Registers an agent on ERC 8004 Identity Registry (with or without token URI) | register_agent | | register_agent_with_metadata | Registers an agent with token URI and metadata on ERC 8004 Identity Registry | register_agent_with_metadata | | validate_agent | Validates an agent's existence and retrieves details from the registry | validate_agent | | get_agent_from_service_endpoint | Gets agent details by looking up the service endpoint in the registry | get_agent_from_service_endpoint | | verify_signature | Verifies a signature against a DID | verify_signature | | generate_challenge | Generates a random challenge string of specified length | generate_challenge | | initiate_agent_handshake | Initiates a handshake between two agents | initiate_agent_handshake | | complete_agent_handshake | Completes a handshake by signing and sending challenge response | complete_agent_handshake |

Tool Details

1. Generate Agent DID

Generates a Privado ID DID from an Ethereum address using the iden3 protocol.

Parameters:

ethAddress (string, required): Ethereum address in 0x-prefixed format (20 bytes)
chain (string, required): Chain name (e.g., "polygon", "privado")
network (string, required): Network name (e.g., "amoy", "main")

Example:

const result = await agent.execute({
  method: "generate_agent_did",
  params: {
    ethAddress: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
    chain: "polygon",
    network: "amoy",
  },
});
// Returns: { success: true, did: "did:iden3:polygon:amoy:..." }

2. Get Public Key from DID

Extracts the Ethereum public key from a DID string.

Parameters:

did (string, required): The DID string to extract public key from

Example:

const result = await agent.execute({
  method: "get_publickey_from_did",
  params: {
    did: "did:iden3:polygon:amoy:...",
  },
});
// Returns: { success: true, publicKey: "0x..." }

3. Create Identity

Creates a new agent identity on the blockchain registry.

Parameters:

privateKey (string, required): Private key (0x-prefixed, 64-hex string)
chainId (number, required): Chain ID (296 for Hedera)
description (string, required): Agent description
serviceEndpoint (string, required): Service endpoint URL
rpcUrl (string, optional): Optional RPC URL

Example:

const result = await agent.execute({
  method: "create_identity",
  params: {
    privateKey: "0x1234567890abcdef...",
    chainId: 296,
    description: "My Agent",
    serviceEndpoint: "https://myagent.com",
  },
});
// Returns: { success: true, txHash: "0x...", did: "did:...", agentId: "123", publicKey: "0x..." }

4. Register Agent (ERC 8004)

Registers an agent on the ERC 8004 Identity Registry contract. Can register with or without a token URI.

Parameters:

privateKey (string, required): Private key (0x-prefixed, 64-hex string)
tokenURI (string, optional): Optional token URI for the agent
chainId (number, optional): Chain ID (296 for Hedera, defaults to 296)
rpcUrl (string, optional): Optional RPC URL (auto-set based on chainId if not provided)

Example:

// Register without token URI
const result = await agent.execute({
  method: "register_agent",
  params: {
    privateKey: "0x1234567890abcdef...",
  },
});
// Returns: { success: true, txHash: "0x...", agentId: "123" }

// Register with token URI
const resultWithUri = await agent.execute({
  method: "register_agent",
  params: {
    privateKey: "0x1234567890abcdef...",
    tokenURI: "https://example.com/metadata/123",
  },
});
// Returns: { success: true, txHash: "0x...", agentId: "123", tokenURI: "https://example.com/metadata/123" }

5. Register Agent With Metadata (ERC 8004)

Registers an agent on the ERC 8004 Identity Registry contract with token URI and metadata.

Parameters:

privateKey (string, required): Private key (0x-prefixed, 64-hex string)
tokenURI (string, required): Token URI for the agent
metadata (array, required): Array of metadata entries, each with:
- key (string): Metadata key
- value (string): Metadata value (will be converted to bytes)
chainId (number, optional): Chain ID (296 for Hedera, defaults to 296)
rpcUrl (string, optional): Optional RPC URL (auto-set based on chainId if not provided)

Example:

const result = await agent.execute({
  method: "register_agent_with_metadata",
  params: {
    privateKey: "0x1234567890abcdef...",
    tokenURI: "https://example.com/metadata/123",
    metadata: [
      { key: "name", value: "My Agent" },
      { key: "description", value: "A sample agent" },
      { key: "version", value: "1.0.0" },
    ],
  },
});
// Returns: { success: true, txHash: "0x...", agentId: "123", tokenURI: "...", metadata: [...] }

6. Validate Agent

Validates an agent's existence and retrieves details from the registry.

Parameters:

did (string, required): The DID string to validate
chainId (number, required): Chain ID (296 for Hedera)
rpcUrl (string, optional): Optional RPC URL

Example:

const result = await agent.execute({
  method: "validate_agent",
  params: {
    did: "did:iden3:privado:main:...",
    chainId: 296,
  },
});
// Returns: { success: true, data: { did, agentId, description, serviceEndPoint } }

7. Get Agent From Service Endpoint

Gets agent details by looking up the service endpoint in the identity registry.

Parameters:

serviceEndpoint (string, required): The service endpoint URL to lookup
chainId (number, required): Chain ID (296 for Hedera)
rpcUrl (string, optional): Optional RPC URL

Example:

const result = await agent.execute({
  method: "get_agent_from_service_endpoint",
  params: {
    serviceEndpoint: "https://myagent.com",
    chainId: 296,
  },
});
// Returns: { success: true, data: { did, agentId, description, serviceEndPoint } }

8. Verify Signature

Verifies a signature against a DID.

Parameters:

sessionId (string, required): Session identifier
challenge (string, required): Challenge string
signature (string, required): Signature to verify
did (string, required): Decentralized identifier

Example:

const result = await agent.execute({
  method: "verify_signature",
  params: {
    sessionId: "12345",
    challenge: "challenge_string",
    signature: "0x...",
    did: "did:iden3:privado:main:...",
  },
});
// Returns: { success: true, isValid: true }

9. Generate Challenge

Generates a random challenge string of specified length using alphanumeric characters.

Parameters:

length (number, required): Length of the random string to generate (must be positive integer)

Example:

const result = await agent.execute({
  method: "generate_challenge",
  params: {
    length: 32,
  },
});
// Returns: { success: true, challenge: "aBc123..." }

10. Initiate Agent Handshake

Initiates a handshake between two agents.

Parameters:

initiatorDid (string, required): DID of the initiating agent
initiatorChainId (number, required): Chain ID for initiator (296 for Hedera)
receiverDid (string, required): DID of the receiving agent
receiverChainId (number, required): Chain ID for receiver (296 for Hedera)
initiatorRpcUrl (string, optional): Optional RPC URL for initiator
receiverRpcUrl (string, optional): Optional RPC URL for receiver

Example:

const result = await agent.execute({
  method: "initiate_agent_handshake",
  params: {
    initiatorDid: "did:iden3:privado:main:...",
    initiatorChainId: 296,
    receiverDid: "did:iden3:privado:main:...",
    receiverChainId: 296,
  },
});
// Returns: { success: true, handshake: { sessionId, receiverAgentCallbackEndPoint, challenge } }

11. Complete Agent Handshake

Completes a handshake by signing and sending challenge response.

Parameters:

privateKey (string, required): Private key for signing the challenge
sessionId (string, required): Session ID from handshake initiation
receiverAgentCallbackEndPoint (string, required): Callback endpoint URL
challenge (string, required): Challenge string to be signed

Example:

const result = await agent.execute({
  method: "complete_agent_handshake",
  params: {
    privateKey: "0x1234567890abcdef...",
    sessionId: "12345",
    receiverAgentCallbackEndPoint: "https://receiver.com/callback",
    challenge: "challenge_string",
  },
});
// Returns: { success: true, handshakeCompleted: true }

Complete Workflow Example

Here's a complete example of how to use the plugin for agent identity management and handshake:

// 1. Generate a DID from an Ethereum address
const didResult = await agent.execute({
  method: "generate_agent_did",
  params: {
    ethAddress: "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
    chain: "privado",
    network: "main",
  },
});

// 2. Create an identity on the blockchain
const identityResult = await agent.execute({
  method: "create_identity",
  params: {
    privateKey: "0x1234567890abcdef...",
    chainId: 296,
    description: "My Agent",
    serviceEndpoint: "https://myagent.com",
  },
});
// identityResult now includes: { txHash, did, agentId, publicKey }

// 2a. Register agent on ERC 8004 Identity Registry (alternative approach)
const registerResult = await agent.execute({
  method: "register_agent",
  params: {
    privateKey: "0x1234567890abcdef...",
    tokenURI: "https://example.com/metadata/agent123",
  },
});
// registerResult includes: { txHash, agentId, tokenURI }

// 2b. Register agent with metadata on ERC 8004 Identity Registry
const registerWithMetadataResult = await agent.execute({
  method: "register_agent_with_metadata",
  params: {
    privateKey: "0x1234567890abcdef...",
    tokenURI: "https://example.com/metadata/agent123",
    metadata: [
      { key: "name", value: "My Agent" },
      { key: "description", value: "A sample agent" },
    ],
  },
});
// registerWithMetadataResult includes: { txHash, agentId, tokenURI, metadata }

// 3. Validate the created agent
const validationResult = await agent.execute({
  method: "validate_agent",
  params: {
    did: identityResult.did,
    chainId: 296,
  },
});

// 4. Get agent details from service endpoint
const agentFromEndpoint = await agent.execute({
  method: "get_agent_from_service_endpoint",
  params: {
    serviceEndpoint: "https://myagent.com",
    chainId: 296,
  },
});

// 5. Initiate handshake with another agent
const handshakeResult = await agent.execute({
  method: "initiate_agent_handshake",
  params: {
    initiatorDid: identityResult.did,
    initiatorChainId: 296,
    receiverDid: "did:iden3:privado:main:...",
    receiverChainId: 296,
  },
});

// 6. Complete the handshake
const completeResult = await agent.execute({
  method: "complete_agent_handshake",
  params: {
    privateKey: "0x1234567890abcdef...",
    sessionId: handshakeResult.handshake.sessionId,
    receiverAgentCallbackEndPoint:
      handshakeResult.handshake.receiverAgentCallbackEndPoint,
    challenge: handshakeResult.handshake.challenge,
  },
});

Features

Complete Identity Management: Full lifecycle management of decentralized agent identities
Cross-chain Identity: Generate DIDs that work across different blockchain networks
Ethereum Integration: Convert Ethereum addresses to Privado ID format
Blockchain Registry: Create and manage agent identities on Hedera blockchain
ERC 8004 Compatibility: Full support for ERC 8004 Identity Registry standard on Hedera Testnet
Token URI Support: Register agents with optional token URIs for metadata storage
Metadata Management: Store and manage custom metadata for agent identities
Agent Validation: Verify agent existence and retrieve detailed information
Secure Handshake Protocol: Initiate and complete secure agent-to-agent handshakes
Challenge Generation: Generate random challenge strings for secure authentication
Public Key Management: Extract and manage public keys from DIDs
Verifiable Credentials: Support for self-sovereign identity (SSI) workflows
Hedera Integration: Seamless integration with Hedera Agent Kit
TypeScript Support: Full TypeScript support with comprehensive type definitions

Dependencies

@hashgraph/sdk: Hedera SDK for blockchain operations
@zkred/agent-id: Zkred's agent ID SDK
bs58: Base58 encoding for DID generation
crc: Checksum validation
ethers: Ethereum library for cryptographic operations and blockchain interactions
hedera-agent-kit: Core Hedera Agent Kit framework
zod: Schema validation
axios: HTTP client for agent-to-agent communication

Changelog

Version 7.0.2

Fixed: Added .nullable() to all optional fields to comply with OpenAI API structured outputs requirements
Fixed: Resolved warnings about optional fields requiring .nullable() for proper JSON Schema serialization
Enhanced: All optional parameters now properly support both null and undefined values

Version 7.0.1

Fixed: Resolved schema serialization issue by downgrading Zod from v4.1.12 to v3.25.76 to match hedera-agent-kit compatibility
Fixed: All tools now use consistent schema formatting pattern for proper JSON Schema serialization
Fixed: Resolved "type: None instead of type: object" schema validation error
Enhanced: Improved schema consistency across all 11 tools

Version 7.0.0

BREAKING: Migrated to ERC 8004 (Identity Registry) compatible contracts deployed on Hedera Testnet
Added: register_agent tool for registering agents with or without token URI on ERC 8004 Identity Registry
Added: register_agent_with_metadata tool for registering agents with token URI and metadata on ERC 8004 Identity Registry
Enhanced: Support for ERC 721 token-based identity management with URI storage
Enhanced: Metadata storage capabilities for agent identity management
Changed: Updated contract interaction to use new IdentityRegistryUpgradeable contract
Changed: Made chainId and rpcUrl optional parameters (defaults to Hedera Testnet - chainId 296)
Enhanced: Improved flexibility with optional token URI registration
Updated: Contract address updated to ERC 8004 compatible deployment on Hedera Testnet
Documentation: Updated README with new tools and ERC 8004 compatibility information

Version 4.0.0

BREAKING: Renamed generate_signature tool to generate_challenge for better semantic clarity
Changed: Updated tool functionality from generating signatures to generating random challenge strings
Updated: Tool now accepts length parameter instead of privateKey and message parameters
Enhanced: Improved tool description and documentation to reflect new challenge generation purpose
Updated: All documentation, examples, and references updated to reflect the tool rename

Version 2.0.1

Changed: Updated the contract address to the latest deployed version for improved stability and compatibility.

Version 2.0.0

BREAKING: Updated create_identity tool to return agentId as string instead of BigInt for better serialization
Added: create_identity tool now returns publicKey in the response for enhanced identity management
Fixed: Resolved BigInt serialization issues in agent responses
Enhanced: Improved type safety and compatibility with agent frameworks
Major: Significant improvements to identity management and agent integration

Version 1.0.3

Added: Service endpoint lookup tool for agent discovery
Enhanced: Improved code formatting and structure
Enhanced: Better error handling and validation

Version 1.0.2

Added: Complete identity management suite with 9 comprehensive tools
Added: Agent handshake protocol for secure agent-to-agent communication
Added: Challenge generation and signature verification capabilities
Added: Public key extraction from DIDs
Added: Agent validation and registry management
Added: Blockchain identity creation on Hedera network
Enhanced: Comprehensive TypeScript support with full type definitions
Enhanced: Improved error handling and validation across all tools
Enhanced: Better documentation and usage examples

Version 1.0.0

Initial Release: Basic DID generation from Ethereum addresses
Core Features: Integration with Hedera Agent Kit
Basic Tools: Generate agent DIDs using iden3 protocol

License

MIT

Support

For issues and questions, please visit: https://github.com/Zkred/zkred-agentid-hedera-plugin/issues

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Zkred Agent ID Hedera Plugin

Installation

ERC 8004 Compatibility

Usage

Available Tools

Tool Details

1. Generate Agent DID

2. Get Public Key from DID

3. Create Identity

4. Register Agent (ERC 8004)

5. Register Agent With Metadata (ERC 8004)

6. Validate Agent

7. Get Agent From Service Endpoint

8. Verify Signature

9. Generate Challenge

10. Initiate Agent Handshake

11. Complete Agent Handshake

Complete Workflow Example

Features

Dependencies

Changelog

Version 7.0.2

Version 7.0.1

Version 7.0.0

Version 4.0.0

Version 2.0.1

Version 2.0.0

Version 1.0.3

Version 1.0.2

Version 1.0.0

License

Support