Hedera T3N Plugin

Plugin Name

@terminal3/hedera-t3n-plugin was built by Terminal 3 for T3N agent identity workflows. It enables Hedera Agent Kit builders to create local agent identities, open authenticated T3N sessions, track user DIDs, inspect profile-field availability, and inspect T3N plus Hedera registration state.

This open-source packaging pass keeps the existing user-DID, profile, session, and registration-inspection capabilities intact. The cleanup removes stale legacy compliance wording and private-package assumptions, not active runtime features.

Installation

npm install @terminal3/hedera-t3n-plugin hedera-agent-kit @hashgraph/sdk

Usage

import { Client, PrivateKey } from "@hashgraph/sdk";
import { AgentMode, HederaLangchainToolkit } from "hedera-agent-kit";
import { hederaT3nPlugin } from "@terminal3/hedera-t3n-plugin";

const client = Client.forTestnet().setOperator(
  process.env.HEDERA_ACCOUNT_ID!,
  PrivateKey.fromStringECDSA(process.env.HEDERA_PRIVATE_KEY!)
);

const toolkit = new HederaLangchainToolkit({
  client,
  configuration: {
    context: {
      mode: AgentMode.AUTONOMOUS,
    },
    plugins: [hederaT3nPlugin],
    tools: [],
  },
});

const tools = toolkit.getTools();

Set AGENT_IDENTITY_CONFIG_PATH in the host runtime before invoking tools that read the local identity file.

Functionality

Hedera T3N Plugin Identity readiness, session auth, user-DID tracking, profile inspection, and registration-readback tools for a locally managed T3N agent identity.

| Tool Name | Description | Usage | | --- | --- | --- | | ADD_USER_DID | Stores one user DID plus a local remark for later profile checks. | Parameters: userDid, remark. Replaces any previously stored DID in the current runtime. | | CHECK_AGENT_REGISTRATION_STATUS | Summarizes whether the current agent is registered on T3N and Hedera ERC-8004. | No parameters. Requires AGENT_IDENTITY_CONFIG_PATH and a testnet/mainnet identity. | | CHECK_MY_PROFILE_FIELDS | Checks whether requested fields exist for the currently stored user DID without returning values. | Parameters: fields. Requires an active T3N session plus a stored user DID. | | CHECK_PROFILE_FIELD_EXISTENCE | Checks whether requested fields exist for another T3N profile without returning values. | Parameters: fields, optional targetDid. Requires an active T3N session. | | CREATE_T3N_AUTH_SESSION | Creates or reuses an authenticated in-memory T3N session for the current identity. | No parameters. Requires a valid local identity file and reachable T3N endpoints for non-local environments. | | FETCH_AGENT_REGISTRATION_RECORD | Returns the detailed T3N and Hedera registration records for the current agent. | No parameters. Requires AGENT_IDENTITY_CONFIG_PATH and a testnet/mainnet identity. | | GET_USER_DID | Reads stored user DIDs from the current runtime. | Optional parameters: userDid, remark. With no filters it returns every tracked DID. | | HAS_AGENT_IDENTITY_CONFIG | Validates the local identity JSON referenced by AGENT_IDENTITY_CONFIG_PATH. | No parameters. Requires AGENT_IDENTITY_CONFIG_PATH to point to a readable identity file. | | PROFILE_FIELD_MAPPING | Maps user-friendly profile field names to the T3N JSONPath selectors used for lookup filters. | Parameter: fields. Returns supported mappings plus unsupported field names. | | VALIDATE_T3N_AUTH_SESSION | Confirms that the current in-memory T3N session is authenticated and still usable. | No parameters. Call after CREATE_T3N_AUTH_SESSION. |

CLI Workflows

The package ships a hedera-t3n-plugin binary.

hedera-t3n-plugin init
hedera-t3n-plugin create-identity --env testnet --path ./output/identities/agent_identity.json
hedera-t3n-plugin ipfs-submit-agent-card-pinata --path ./output/identities/agent_identity.json --jwt <PINATA_JWT>
hedera-t3n-plugin register-agent-erc8004 --env testnet --path ./output/identities/agent_identity.json --agent-uri https://gateway.pinata.cloud/ipfs/<cid>

• init creates local .env and .env.secret.pinata files from the packaged examples.
• register-agent-erc8004 supports testnet and mainnet only.
• Registration stays explicit: the plugin exposes registration inspection tools, while publishing the public agent card and writing ERC-8004 state happen through the CLI or programmatic APIs.

Programmatic APIs

import {
  createIdentity,
  registerAgentErc8004,
  submitAgentCardToPinata,
} from "@terminal3/hedera-t3n-plugin";

const identity = await createIdentity({
  networkTier: "testnet",
  outputPath: "./output/identities/agent_identity.json",
});

const upload = await submitAgentCardToPinata({
  identityConfigPath: identity.credentials_path,
  jwt: process.env.PINATA_JWT,
});

const registration = await registerAgentErc8004({
  networkTier: "testnet",
  identityConfigPath: identity.credentials_path,
  agentUri: upload.gatewayUrl,
});

Environment

• HEDERA_NETWORK: defaults identity creation to testnet; supported values are local, testnet, and mainnet
• AGENT_IDENTITY_CONFIG_PATH: local identity JSON path used by plugin tools and registration helpers
• HEDERA_ACCOUNT_ID / HEDERA_PRIVATE_KEY: required for live Hedera registration
• PINATA_JWT or PINATA_API_KEY + PINATA_API_SECRET: required for the Pinata upload helper
• T3N_API_URL, T3N_RUNTIME_API_URL, T3N_ML_KEM_PUBLIC_KEY(_FILE): optional advanced overrides for local CCF or custom T3N environments
• T3N_AGENT_REGISTRY_SCRIPT_VERSION, T3N_USER_SCRIPT_VERSION: optional overrides when a target cluster cannot resolve /api/contracts/current
• T3N_LOCAL_BACKEND=ccf: opt in to a live local CCF backend when HEDERA_NETWORK=local

Development

pnpm install
pnpm validate
pnpm test:e2e

• pnpm validate runs lint, unit tests, integration tests, build, npm pack --dry-run, and a tarball smoke-install check
• pnpm test:e2e covers identity validation, registration inspection, session auth, user-DID tracking, profile-field lookup guards, and delegated self-only checks; live registration phases remain opt-in and may require explicit T3N_API_URL / T3N_RUNTIME_API_URL overrides when the public endpoint does not expose the agent-registry contract
• additional test guidance lives in tests/README.md

Release Notes

• 2.0.0 is the first public npm/open-source packaging pass for this plugin surface
• existing user-DID, profile, session, and registration-inspection tools remain available
• stale legacy compliance wording and GitHub-Packages-only instructions were removed
• readiness docs: OPEN_SOURCE_READINESS_MATRIX.md, RELEASE_CHECKLIST.md, OPEN_SOURCE_NOTES.md