@hashgraphonline/standards-sdk 0.0.16 → 0.0.18

package/dist/es/hcs-10/agent-builder.d.ts

@@ -0,0 +1,42 @@
+import { InboundTopicType, NetworkType, FeeConfigBuilderInterface, AgentConfiguration } from './types.d';
+import { AIAgentCapability } from '../hcs-11';
+import { AgentMetadata } from './sdk';
+type SocialPlatform = 'twitter' | 'discord' | 'github' | 'website' | 'x' | 'linkedin' | 'youtube' | 'telegram';
+/**
+ * AgentBuilder is a builder class for creating agent configurations.
+ * It provides a fluent interface for setting various properties of the agent.
+ *
+ * Example usage:
+ * ```typescript
+ * const agentBuilder = new AgentBuilder();
+ * agentBuilder.setName('My Agent');
+ * agentBuilder.setDescription('This is my agent');
+ * agentBuilder.setCapabilities([AIAgentCapability.CREATE_CONTENT]);
+ * agentBuilder.setModel('gpt-4o');
+ * agentBuilder.setCreator('John Doe');
+ * agentBuilder.addSocial('twitter', 'JohnDoe');
+ * agentBuilder.addProperty('key', 'value');
+ * const agentConfig = agentBuilder.build();
+ * ```
+ *
+ */
+export declare class AgentBuilder {
+    private config;
+    setName(name: string): AgentBuilder;
+    setDescription(description: string): AgentBuilder;
+    setCapabilities(capabilities: AIAgentCapability[]): AgentBuilder;
+    setAgentType(type: 'autonomous' | 'manual'): AgentBuilder;
+    setModel(model: string): AgentBuilder;
+    setCreator(creator: string): AgentBuilder;
+    addSocial(platform: SocialPlatform, handle: string): AgentBuilder;
+    addProperty(key: string, value: any): AgentBuilder;
+    setMetadata(metadata: AgentMetadata): AgentBuilder;
+    setProfilePicture(pfpBuffer: Buffer, pfpFileName: string): AgentBuilder;
+    setNetwork(network: NetworkType): AgentBuilder;
+    setInboundTopicType(inboundTopicType: InboundTopicType): AgentBuilder;
+    setFeeConfig(feeConfigBuilder: FeeConfigBuilderInterface): AgentBuilder;
+    setConnectionFeeConfig(feeConfigBuilder: FeeConfigBuilderInterface): AgentBuilder;
+    setExistingAccount(accountId: string, privateKey: string): AgentBuilder;
+    build(): AgentConfiguration;
+}
+export {};

package/dist/es/hcs-10/base-client.d.ts

@@ -0,0 +1,60 @@
+import { Logger, LogLevel } from '../utils/logger';
+import { Registration } from './registrations';
+import { HederaMirrorNode, TopicInfo, AccountResponse } from '../services/mirror-node';
+export interface HCS10Config {
+    network: 'mainnet' | 'testnet';
+    logLevel?: LogLevel;
+}
+export interface HCSMessage {
+    p: 'hcs-10';
+    op: 'connection_request' | 'connection_created' | 'message';
+    data: string;
+    created?: Date;
+    consensus_timestamp?: string;
+    m?: string;
+    payer: string;
+    outbound_topic_id?: string;
+    connection_request_id?: number;
+    confirmed_request_id?: number;
+    connection_topic_id?: string;
+    connected_account_id?: string;
+    requesting_account_id?: string;
+    connection_id?: number;
+    sequence_number: number;
+    operator_id?: string;
+}
+export declare abstract class HCS10BaseClient extends Registration {
+    protected network: string;
+    protected logger: Logger;
+    protected mirrorNode: HederaMirrorNode;
+    constructor(config: HCS10Config);
+    abstract getAccountAndSigner(): {
+        accountId: string;
+        signer: any;
+    };
+    getMessages(topicId: string): Promise<{
+        messages: HCSMessage[];
+    }>;
+    protected checkRegistrationStatus(transactionId: string, network: string, baseUrl: string): Promise<{
+        status: 'pending' | 'success' | 'failed';
+    }>;
+    requestAccount(account: string): Promise<AccountResponse>;
+    getAccountMemo(accountId: string): Promise<string | null>;
+    protected getTopicInfoFromMemo(memo: string): Promise<TopicInfo | null>;
+    getTopicInfo(accountId: string): Promise<TopicInfo | null>;
+    retrieveOutboundConnectTopic(accountId: string): Promise<TopicInfo>;
+    retrieveOutboundMessages(agentAccountId: string): Promise<HCSMessage[]>;
+    hasConnectionCreated(agentAccountId: string, connectionId: number): Promise<boolean>;
+    clearCache(): void;
+}
+export declare class HCS10Cache {
+    private static instance;
+    private cache;
+    private cacheExpiry;
+    private readonly CACHE_TTL;
+    private constructor();
+    static getInstance(): HCS10Cache;
+    set(key: string, value: TopicInfo): void;
+    get(key: string): TopicInfo | undefined;
+    clear(): void;
+}

package/dist/es/hcs-10/browser.d.ts

@@ -2,7 +2,7 @@ import { PublicKey, TransactionReceipt } from '@hashgraph/sdk';
 import { HashinalsWalletConnectSDK } from '@hashgraphonline/hashinal-wc';
 import { Logger, LogLevel } from '../utils/logger';
 import { RetrievedInscriptionResult } from '@kiloscribe/inscription-sdk';
-import { Outbound, HCSMessage } from './outbound';
+import { HCS10BaseClient } from './base-client';
 import { AgentConfig, NetworkType } from './types.d';
 export type BrowserHCSClientConfig = {
     network: 'mainnet' | 'testnet';
@@ -28,10 +28,9 @@ interface SocialLinks {
 export type BrowserAgentConfig = Omit<AgentConfig<BrowserHCSClient>, 'privateKey'> & {
     client: BrowserHCSClient;
 };
-export declare class BrowserHCSClient extends Outbound {
+export declare class BrowserHCSClient extends HCS10BaseClient {
     private hwc;
     protected logger: Logger;
-    private guardedRegistryTopicId;
     private guardedRegistryBaseUrl;
     private hcs11Client;
     constructor(config: BrowserHCSClientConfig);
@@ -93,9 +92,6 @@ export declare class BrowserHCSClient extends Outbound {
         accountId: string;
         signer: any;
     };
-    protected getMessages(topicId: string): Promise<{
-        messages: HCSMessage[];
-    }>;
     /**
      * Inscribes a profile picture file to the Hedera network
      * @param buffer File buffer to inscribe

package/dist/es/hcs-10/fee-config-builder.d.ts

@@ -0,0 +1,66 @@
+import { FeeConfigBuilderInterface, TopicFeeConfig } from './types.d';
+/**
+ * FeeConfigBuilder provides a fluent interface for creating fee configurations
+ * for HCS-10 topics. This makes it easy to configure fees without dealing with
+ * the complexity of the underlying fee structure.
+ *
+ * Example usage:
+ * ```typescript
+ * const feeConfig = new FeeConfigBuilder()
+ *   .setHbarAmount(1) // 1 HBAR
+ *   .setFeeCollector('0.0.12345')
+ *   .addExemptAccount('0.0.67890')
+ *   .build();
+ * ```
+ */
+export declare class FeeConfigBuilder implements FeeConfigBuilderInterface {
+    private feeAmount;
+    private decimals;
+    private feeCollectorAccountId;
+    private exemptAccountIds;
+    /**
+     * Static factory method to create a fee config with HBAR amount in one line
+     * @param hbarAmount Amount in HBAR
+     * @param collectorAccountId Account that will receive the fees
+     * @param exemptAccounts Optional array of exempt account IDs
+     * @returns A configured FeeConfigBuilder
+     */
+    static forHbar(hbarAmount: number, collectorAccountId: string, exemptAccounts?: string[]): FeeConfigBuilder;
+    /**
+     * Sets the fee amount in HBAR (convenient method)
+     * @param hbarAmount The amount in HBAR (e.g., 5 for 5 HBAR)
+     * @returns This builder instance for method chaining
+     */
+    setHbarAmount(hbarAmount: number): FeeConfigBuilder;
+    /**
+     * Sets the amount of the fee to be collected for topic submissions
+     * @param amount The fee amount (in tinybars or token units)
+     * @param decimals Decimal places for fixed point representation (default: 0)
+     * @returns This builder instance for method chaining
+     */
+    setFeeAmount(amount: number, decimals?: number): FeeConfigBuilder;
+    /**
+     * Sets the Hedera account ID that will collect the fees
+     * @param accountId The fee collector's account ID (e.g., '0.0.12345')
+     * @returns This builder instance for method chaining
+     */
+    setFeeCollector(accountId: string): FeeConfigBuilder;
+    /**
+     * Adds an account ID to the list of accounts exempt from paying fees
+     * @param accountId The account ID to exempt from fees
+     * @returns This builder instance for method chaining
+     */
+    addExemptAccount(accountId: string): FeeConfigBuilder;
+    /**
+     * Adds multiple account IDs to the list of accounts exempt from paying fees
+     * @param accountIds Array of account IDs to exempt from fees
+     * @returns This builder instance for method chaining
+     */
+    addExemptAccounts(accountIds: string[]): FeeConfigBuilder;
+    /**
+     * Builds and returns the final fee configuration object
+     * @throws Error if fee collector account ID is not set or if fee amount is not positive
+     * @returns A complete TopicFeeConfig object
+     */
+    build(): TopicFeeConfig;
+}

package/dist/es/hcs-10/index.d.ts

@@ -1,5 +1,5 @@
 export * from './sdk';
-export * from './browser';
 export * from './errors';
-export * from './outbound';
+export * from './agent-builder';
+export * from './base-client';
 export * from './registrations';

package/dist/es/hcs-10/registrations.d.ts

@@ -1,4 +1,5 @@
 import { AgentMetadata } from './sdk';
+import { Logger } from '../utils/logger';
 export interface RegistrationSearchOptions {
     tags?: string[];
     accountId?: string;
@@ -22,6 +23,21 @@ export interface RegistrationSearchResult {
     error?: string;
     success: boolean;
 }
+export type RegistrationResult = {
+    transaction?: any;
+    transactionId?: string;
+    success: boolean;
+    error?: string;
+    validationErrors?: any[];
+};
 export declare abstract class Registration {
+    protected checkRegistrationStatus(transactionId: string, network: string, baseUrl: string, logger?: Logger): Promise<{
+        status: 'pending' | 'success' | 'failed';
+    }>;
+    waitForRegistrationConfirmation(transactionId: string, network: string, baseUrl: string, maxAttempts?: number, delayMs?: number, logger?: Logger): Promise<boolean>;
+    executeRegistration(accountId: string, inboundTopicId: string, network: string, baseUrl: string, logger?: Logger, metadata?: {
+        tags: string[];
+        [key: string]: any;
+    }): Promise<RegistrationResult>;
     findRegistrations(options?: RegistrationSearchOptions, baseUrl?: string): Promise<RegistrationSearchResult>;
 }

package/dist/es/hcs-10/sdk.d.ts

@@ -1,8 +1,11 @@
-import { Client, PrivateKey, TransactionReceipt, PublicKey } from '@hashgraph/sdk';
+import { Client, PrivateKey, KeyList, TransactionReceipt, PublicKey } from '@hashgraph/sdk';
 import { RetrievedInscriptionResult } from '@kiloscribe/inscription-sdk';
 import { Logger } from '../utils/logger';
-import { Outbound, HCSMessage } from './outbound';
-import { HCSClientConfig, NetworkType, AgentConfig, CreateAccountResponse, CreateAgentResponse, InscribePfpResponse, StoreHCS11ProfileResponse, AgentRegistrationResult, HandleConnectionRequestResponse, WaitForConnectionConfirmationResponse, GetAccountAndSignerResponse } from './types.d';
+import { HCS10BaseClient } from './base-client';
+import { HCSClientConfig, AgentConfig, CreateAccountResponse, CreateAgentResponse, InscribePfpResponse, StoreHCS11ProfileResponse, AgentRegistrationResult, HandleConnectionRequestResponse, WaitForConnectionConfirmationResponse, GetAccountAndSignerResponse, InboundTopicType, TopicFeeConfig, FeeConfigBuilderInterface } from './types.d';
+import { AgentBuilder } from './agent-builder';
+export { InboundTopicType } from './types.d';
+export { FeeConfigBuilder } from './fee-config-builder';
 export interface AgentMetadata {
     type: 'autonomous' | 'manual';
     model?: string;
@@ -19,13 +22,14 @@ export interface AgentMetadata {
     creator?: string;
     properties?: Record<string, any>;
 }
-export declare class HCS10Client extends Outbound {
+export declare class HCS10Client extends HCS10BaseClient {
     private client;
     private operatorPrivateKey;
     protected network: string;
     protected logger: Logger;
     protected guardedRegistryBaseUrl: string;
     private hcs11Client;
+    private feeAmount;
     constructor(config: HCSClientConfig);
     getClient(): Client;
     /**
@@ -33,17 +37,20 @@ export declare class HCS10Client extends Outbound {
      * @returns Object with account ID and private key
      */
     createAccount(): Promise<CreateAccountResponse>;
+    /**
+     * Creates an inbound topic with the specified configuration
+     * @param accountId Account ID associated with the topic
+     * @param topicType Type of inbound topic (public, controlled, or fee-based)
+     * @param feeConfig Optional fee configuration for fee-based topics
+     * @returns The topic ID of the created inbound topic
+     */
+    createInboundTopic(accountId: string, topicType: InboundTopicType, feeConfig?: FeeConfigBuilderInterface): Promise<string>;
     /**
      * Creates a new agent with inbound and outbound topics
-     * @param pfpBuffer Profile picture buffer
-     * @param pfpFileName Profile picture filename
-     * @param agentName Agent name
-     * @param agentDescription Agent description
-     * @param capabilities Agent capability tags
-     * @param metadata Additional agent metadata
+     * @param builder The agent builder object
      * @returns Object with topic IDs
      */
-    createAgent(pfpBuffer: Buffer, pfpFileName: string, agentName: string, agentDescription: string, capabilities: number[], metadata: AgentMetadata): Promise<CreateAgentResponse>;
+    createAgent(builder: AgentBuilder): Promise<CreateAgentResponse>;
     /**
      * Inscribes a profile picture to Hedera
      * @param buffer Profile picture buffer
@@ -64,33 +71,21 @@ export declare class HCS10Client extends Outbound {
      * @returns Response with topic IDs and transaction ID
      */
     storeHCS11Profile(agentName: string, agentDescription: string, inboundTopicId: string, outboundTopicId: string, capabilities: number[], metadata: AgentMetadata, pfpBuffer?: Buffer, pfpFileName?: string): Promise<StoreHCS11ProfileResponse>;
+    private setupFees;
     /**
      * Handles a connection request from another account
      * @param inboundTopicId Inbound topic ID
      * @param requestingAccountId Requesting account ID
      * @param connectionRequestId Connection request ID
+     * @param connectionFeeConfig Optional fee configuration for the connection topic
      * @returns Response with connection details
      */
-    handleConnectionRequest(inboundTopicId: string, requestingAccountId: string, connectionRequestId: number): Promise<HandleConnectionRequestResponse>;
+    handleConnectionRequest(inboundTopicId: string, requestingAccountId: string, connectionRequestId: number, connectionFeeConfig?: FeeConfigBuilderInterface): Promise<HandleConnectionRequestResponse>;
     confirmConnection(inboundTopicId: string, connectionTopicId: string, connectedAccountId: string, connectionId: number, operatorId: string, memo: string, submitKey?: PrivateKey): Promise<number>;
     sendMessage(connectionTopicId: string, operatorId: string, data: string, memo?: string, submitKey?: PrivateKey): Promise<void>;
-    /**
-     * Retrieves the memo field from a Hedera account
-     * @param accountId The account ID to fetch the memo for
-     * @returns The account memo as a string, or null if not found/error
-     */
-    getAccountMemo(accountId: string): Promise<string | null>;
-    /**
-     * Creates a threshold topic with the operator and requester keys
-     * @param memo The memo for the topic
-     * @param requesterPublicKey The public key of the requester
-     * @returns The topic ID of the created topic
-     */
-    createThresholdTopic(memo: string, requesterPublicKey: string): Promise<string>;
-    createTopic(memo: string, adminKey?: boolean, submitKey?: boolean): Promise<string>;
+    createTopic(memo: string, adminKey?: boolean | PublicKey | KeyList, submitKey?: boolean | PublicKey | KeyList, feeConfig?: TopicFeeConfig): Promise<string>;
     submitMessage(topicId: string, message: string, submitKey?: PrivateKey): Promise<TransactionReceipt>;
     private submitPayload;
-    queryTopicMessages(topicId: string): Promise<string[]>;
     submitConnectionRequest(inboundTopicId: string, requestingAccountId: string, operatorId: string, memo: string): Promise<TransactionReceipt>;
     recordOutboundConnectionConfirmation({ outboundTopicId, connectionRequestId, confirmedRequestId, connectionTopicId, operatorId, memo, }: {
         outboundTopicId: string;
@@ -110,20 +105,18 @@ export declare class HCS10Client extends Outbound {
      * @returns Connection confirmation details
      */
     waitForConnectionConfirmation(inboundTopicId: string, connectionRequestId: number, maxAttempts?: number, delayMs?: number): Promise<WaitForConnectionConfirmationResponse>;
-    /**
-     * Gets the account ID and signer for the client
-     * @returns Account ID and signer
-     */
     getAccountAndSigner(): GetAccountAndSignerResponse;
-    protected getMessages(topicId: string): Promise<{
-        messages: HCSMessage[];
-    }>;
     /**
-     * Retrieves the public key for a given account ID
-     * @param accountId Account ID to retrieve the public key for
-     * @returns The public key of the account
+     * Checks if a user can submit to a topic and determines if a fee is required
+     * @param topicId The topic ID to check
+     * @param userAccountId The account ID of the user attempting to submit
+     * @returns Object with canSubmit, requiresFee, and optional reason
      */
-    getPublicKey(accountId: string): Promise<PublicKey>;
+    canSubmitToInboundTopic(topicId: string, userAccountId: string): Promise<{
+        canSubmit: boolean;
+        requiresFee: boolean;
+        reason?: string;
+    }>;
     /**
      * Creates and registers an agent with a Guarded registry.
      *
@@ -133,20 +126,10 @@ export declare class HCS10Client extends Outbound {
      * 3. Creates an agent on the client.
      * 4. Registers the agent with the Hashgraph Online Guarded Registry.
      *
-     * @param name Agent name
-     * @param description Agent description
-     * @param capabilities Agent capability tags
-     * @param metadata Additional metadata
-     * @param pfpBuffer Profile picture buffer
-     * @param pfpFileName Profile picture filename
-     * @param network Network type
-     * @param existingAccount Optional existing account
+     * @param builder The agent builder object
      * @returns Agent configuration
      */
-    createAndRegisterAgent(name: string, description: string, capabilities: number[], metadata: AgentMetadata, pfpBuffer: Buffer, pfpFileName: string, network: NetworkType, existingAccount?: {
-        accountId: string;
-        privateKey: string;
-    }): Promise<AgentConfig<HCS10Client>>;
+    createAndRegisterAgent(builder: AgentBuilder): Promise<AgentConfig<HCS10Client>>;
     /**
      * Registers an agent with the guarded registry
      * @param accountId Account ID to register
@@ -166,4 +149,7 @@ export declare class HCS10Client extends Outbound {
      * @param submitKey - The submit key of the agent
      */
     registerAgent(registryTopicId: string, accountId: string, inboundTopicId: string, memo: string, submitKey?: PrivateKey): Promise<void>;
+    getInboundTopicType(topicId: string): Promise<InboundTopicType>;
+    getNetwork(): string;
+    getLogger(): Logger;
 }

package/dist/es/index.d.ts

@@ -4,3 +4,4 @@ export * from './hcs-10';
 export * from './hcs-11';
 export * from './utils';
 export * from './inscribe';
+export * from './services';

package/dist/es/services/index.d.ts

@@ -0,0 +1 @@
+export * from './mirror-node';

package/dist/es/services/mirror-node.d.ts

@@ -0,0 +1,149 @@
+import { PublicKey } from '@hashgraph/sdk';
+import { Logger } from '../utils/logger';
+import { HCSMessage } from '../hcs-10/base-client';
+export interface Balance {
+    balance: number;
+    timestamp: string;
+    tokens: TokenBalance[];
+}
+export interface TokenBalance {
+    token_id: string;
+    balance: number;
+}
+export interface Key {
+    _type: string;
+    key: string;
+}
+export interface AccountResponse {
+    account: string;
+    alias: string;
+    auto_renew_period: number;
+    balance: Balance;
+    created_timestamp: string;
+    decline_reward: boolean;
+    deleted: boolean;
+    ethereum_nonce: number;
+    evm_address: string;
+    expiry_timestamp: string;
+    key: Key;
+    max_automatic_token_associations: number;
+    memo: string;
+    pending_reward: number;
+    receiver_sig_required: boolean;
+    staked_account_id: string | null;
+    staked_node_id: string | null;
+    stake_period_start: string | null;
+    transactions: Transaction[];
+    links: Links;
+}
+export interface Transaction {
+    bytes: string | null;
+    charged_tx_fee: number;
+    consensus_timestamp: string;
+    entity_id: string | null;
+    max_fee: string;
+    memo_base64: string;
+    name: string;
+    nft_transfers: NftTransfer[];
+    node: string;
+    nonce: number;
+    parent_consensus_timestamp: string | null;
+    result: string;
+    scheduled: boolean;
+    staking_reward_transfers: Transfer[];
+    token_transfers: TokenTransfer[];
+    transaction_hash: string;
+    transaction_id: string;
+    transfers: Transfer[];
+    valid_duration_seconds: string;
+    valid_start_timestamp: string;
+}
+export interface Transfer {
+    account: string;
+    amount: number;
+    is_approval: boolean;
+}
+export interface TokenTransfer {
+    token_id: string;
+    account: string;
+    amount: string;
+    is_approval: boolean;
+}
+export interface NftTransfer {
+    receiver_account_id: string;
+    sender_account_id: string;
+    serial_number: number;
+    is_approval: boolean;
+}
+export interface Links {
+    next: string;
+}
+export type NetworkType = 'mainnet' | 'testnet';
+export interface TopicInfo {
+    inboundTopic: string;
+    outboundTopic: string;
+}
+export interface TopicMessage {
+    consensus_timestamp: string;
+    topic_id: string;
+    message: string;
+    sequence_number: number;
+    running_hash: string;
+    running_hash_version: number;
+    payer_account_id: string;
+}
+export interface TopicMessagesResponse {
+    messages: TopicMessage[];
+    links: {
+        next?: string;
+    };
+}
+export interface TopicResponse {
+    admin_key: Key;
+    auto_renew_account: string;
+    auto_renew_period: number;
+    created_timestamp: string;
+    custom_fees: CustomFees;
+    deleted: boolean;
+    fee_exempt_key_list: Key[];
+    fee_schedule_key: Key;
+    memo: string;
+    submit_key: Key;
+    timestamp: Timestamp;
+    topic_id: string;
+}
+export interface Key {
+    _type: string;
+    key: string;
+}
+export interface CustomFees {
+    created_timestamp: string;
+    fixed_fees: FixedFee[];
+}
+export interface FixedFee {
+    amount: number;
+    collector_account_id: string;
+    denominating_token_id: string;
+}
+export interface Timestamp {
+    from: string;
+    to: string;
+}
+export declare class HederaMirrorNode {
+    private network;
+    private baseUrl;
+    private logger?;
+    constructor(network: NetworkType, logger?: Logger);
+    private getMirrorNodeUrl;
+    getBaseUrl(): string;
+    getPublicKey(accountId: string): Promise<PublicKey>;
+    getAccountMemo(accountId: string): Promise<string | null>;
+    getTopicInfo(topicId: string): Promise<TopicResponse>;
+    getTopicFees(topicId: string): Promise<CustomFees | null>;
+    getTopicMessages(topicId: string): Promise<HCSMessage[]>;
+    requestAccount(accountId: string): Promise<AccountResponse>;
+    checkKeyListAccess(keyBytes: Buffer, userPublicKey: PublicKey): Promise<boolean>;
+    private evaluateKeyAccess;
+    private evaluateKeyList;
+    private compareEd25519Key;
+}