@hashgraphonline/standards-sdk
Version:
The Hashgraph Online Standards SDK provides a complete implementation of the Hashgraph Consensus Standards (HCS), giving developers all the tools needed to build applications on Hedera.
304 lines • 12 kB
TypeScript
import { Logger, LogLevel } from '../utils/logger';
import { Registration } from './registrations';
import { AccountResponse, TopicResponse, TopicInfo } from '../services/types';
import { TransactionReceipt, PrivateKey } from '@hashgraph/sdk';
import { HederaMirrorNode, MirrorNodeConfig } from '../services';
import { WaitForConnectionConfirmationResponse, TransactMessage, HCSMessage } from './types';
export declare enum Hcs10MemoType {
INBOUND = "inbound",
OUTBOUND = "outbound",
CONNECTION = "connection",
REGISTRY = "registry"
}
/**
* Configuration for HCS-10 client.
*
* @example
* // Using default Hedera mirror nodes
* const config = {
* network: 'testnet',
* logLevel: 'info'
* };
*
* @example
* // Using HGraph custom mirror node provider
* const config = {
* network: 'mainnet',
* logLevel: 'info',
* mirrorNode: {
* customUrl: 'https://mainnet.hedera.api.hgraph.dev/v1/<API-KEY>',
* apiKey: 'your-hgraph-api-key'
* }
* };
*
* @example
* // Using custom mirror node with headers
* const config = {
* network: 'testnet',
* mirrorNode: {
* customUrl: 'https://custom-mirror.example.com',
* apiKey: 'your-api-key',
* headers: {
* 'X-Custom-Header': 'value'
* }
* }
* };
*/
export interface HCS10Config {
/** The Hedera network to connect to */
network: 'mainnet' | 'testnet';
/** Log level for the client */
logLevel?: LogLevel;
/** Whether to pretty print logs */
prettyPrint?: boolean;
/** Fee amount for transactions that require fees */
feeAmount?: number;
/** Custom mirror node configuration */
mirrorNode?: MirrorNodeConfig;
/** Whether to run logger in silent mode */
silent?: boolean;
/** The key type to use for the operator */
keyType?: 'ed25519' | 'ecdsa';
}
export interface ProfileResponse {
profile: any;
topicInfo?: TopicInfo;
success: boolean;
error?: string;
}
export declare abstract class HCS10BaseClient extends Registration {
protected network: string;
protected logger: Logger;
protected feeAmount: number;
mirrorNode: HederaMirrorNode;
protected operatorId: string;
constructor(config: HCS10Config);
abstract submitPayload(topicId: string, payload: object | string, submitKey?: PrivateKey, requiresFee?: boolean): Promise<TransactionReceipt>;
abstract getAccountAndSigner(): {
accountId: string;
signer: any;
};
/**
* Updates the mirror node configuration.
* @param config The new mirror node configuration.
*/
configureMirrorNode(config: MirrorNodeConfig): void;
extractTopicFromOperatorId(operatorId: string): string;
extractAccountFromOperatorId(operatorId: string): string;
/**
* Get a stream of messages from a connection topic
* @param topicId The connection topic ID to get messages from
* @param options Optional filtering options for messages
* @returns A stream of filtered messages valid for connection topics
*/
getMessageStream(topicId: string, options?: {
sequenceNumber?: string | number;
limit?: number;
order?: 'asc' | 'desc';
}): Promise<{
messages: HCSMessage[];
}>;
/**
* Public method to retrieve topic information using the internal mirror node client.
*
* @param topicId The ID of the topic to query.
* @returns Topic information or null if not found or an error occurs.
*/
getPublicTopicInfo(topicId: string): Promise<TopicResponse | null>;
/**
* 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
*/
canSubmitToTopic(topicId: string, userAccountId: string): Promise<{
canSubmit: boolean;
requiresFee: boolean;
reason?: string;
}>;
/**
* Get all messages from a topic
* @param topicId The topic ID to get messages from
* @param options Optional filtering options for messages
* @returns All messages from the topic
*/
getMessages(topicId: string, options?: {
sequenceNumber?: string | number;
limit?: number;
order?: 'asc' | 'desc';
}): Promise<{
messages: HCSMessage[];
}>;
/**
* Requests an account from the mirror node
* @param account The account ID to request
* @returns The account response
*/
requestAccount(account: string): Promise<AccountResponse>;
/**
* Retrieves the memo for an account
* @param accountId The account ID to retrieve the memo for
* @returns The memo
*/
getAccountMemo(accountId: string): Promise<string | null>;
/**
* Retrieves the profile for an account
* @param accountId The account ID to retrieve the profile for
* @param disableCache Whether to disable caching of the result
* @returns The profile
*/
retrieveProfile(accountId: string, disableCache?: boolean): Promise<ProfileResponse>;
/**
* @deprecated Use retrieveCommunicationTopics instead
* @param accountId The account ID to retrieve the outbound connect topic for
* @returns {TopicInfo} Topic Info from target profile.
*/
retrieveOutboundConnectTopic(accountId: string): Promise<TopicInfo>;
/**
* Retrieves the communication topics for an account
* @param accountId The account ID to retrieve the communication topics for
* @param disableCache Whether to disable caching of the result
* @returns {TopicInfo} Topic Info from target profile.
*/
retrieveCommunicationTopics(accountId: string, disableCache?: boolean): Promise<TopicInfo>;
/**
* Retrieves outbound messages for an agent
* @param agentAccountId The account ID of the agent
* @param options Optional filtering options for messages
* @returns The outbound messages
*/
retrieveOutboundMessages(agentAccountId: string, options?: {
sequenceNumber?: string | number;
limit?: number;
order?: 'asc' | 'desc';
}): Promise<HCSMessage[]>;
/**
* Checks if a connection has been created for an agent
* @param agentAccountId The account ID of the agent
* @param connectionId The ID of the connection
* @returns True if the connection has been created, false otherwise
*/
hasConnectionCreated(agentAccountId: string, connectionId: number): Promise<boolean>;
/**
* Gets message content, resolving any HRL references if needed
* @param data The data string that may contain an HRL reference
* @param forceRaw Whether to force returning raw binary data
* @returns The resolved content
*/
getMessageContent(data: string, forceRaw?: boolean): Promise<string | ArrayBuffer>;
/**
* Gets message content with its content type, resolving any HRL references if needed
* @param data The data string that may contain an HRL reference
* @param forceRaw Whether to force returning raw binary data
* @returns The resolved content along with content type information
*/
getMessageContentWithType(data: string, forceRaw?: boolean): Promise<{
content: string | ArrayBuffer;
contentType: string;
isBinary: boolean;
}>;
/**
* Submits a connection request to an inbound topic
* @param inboundTopicId The ID of the inbound topic
* @param memo An optional memo for the message
* @returns The transaction receipt
*/
submitConnectionRequest(inboundTopicId: string, memo: string): Promise<TransactionReceipt>;
/**
* Records an outbound connection confirmation
* @param outboundTopicId The ID of the outbound topic
* @param connectionRequestId The ID of the connection request
* @param confirmedRequestId The ID of the confirmed request
* @param connectionTopicId The ID of the connection topic
* @param operatorId The operator ID of the original message sender.
* @param memo An optional memo for the message
*/
recordOutboundConnectionConfirmation({ outboundTopicId, requestorOutboundTopicId, connectionRequestId, confirmedRequestId, connectionTopicId, operatorId, memo, }: {
outboundTopicId: string;
requestorOutboundTopicId: string;
connectionRequestId: number;
confirmedRequestId: number;
connectionTopicId: string;
operatorId: string;
memo: string;
}): Promise<TransactionReceipt>;
/**
* Waits for confirmation of a connection request
* @param inboundTopicId Inbound topic ID
* @param connectionRequestId Connection request ID
* @param maxAttempts Maximum number of attempts
* @param delayMs Delay between attempts in milliseconds
* @returns Connection confirmation details
*/
waitForConnectionConfirmation(inboundTopicId: string, connectionRequestId: number, maxAttempts?: number, delayMs?: number, recordConfirmation?: boolean): Promise<WaitForConnectionConfirmationResponse>;
/**
* Retrieves the operator ID for the current agent
* @param disableCache Whether to disable caching of the result
* @returns The operator ID
*/
getOperatorId(disableCache?: boolean): Promise<string>;
/**
* Retrieves the account ID of the owner of an inbound topic
* @param inboundTopicId The ID of the inbound topic
* @returns The account ID of the owner of the inbound topic
*/
retrieveInboundAccountId(inboundTopicId: string): Promise<string>;
clearCache(): void;
/**
* Generates a standard HCS-10 memo string.
* @param type The type of topic memo ('inbound', 'outbound', 'connection').
* @param options Configuration options for the memo.
* @returns The formatted memo string.
* @protected
*/
protected _generateHcs10Memo(type: Hcs10MemoType, options: {
ttl?: number;
accountId?: string;
inboundTopicId?: string;
connectionId?: number;
}): string;
/**
* Reads a topic's memo and determines its HCS-10 type
* @param topicId The topic ID to check
* @returns The HCS-10 memo type or null if not an HCS-10 topic
*/
getTopicMemoType(topicId: string): Promise<Hcs10MemoType | null>;
protected checkRegistrationStatus(transactionId: string, network: string, baseUrl: string): Promise<{
status: 'pending' | 'success' | 'failed';
}>;
/**
* Validates if an operator_id follows the correct format (agentTopicId@accountId)
* @param operatorId The operator ID to validate
* @returns True if the format is valid, false otherwise
*/
protected isValidOperatorId(operatorId: string): boolean;
/**
* Retrieves all transaction requests from a topic
* @param topicId The topic ID to retrieve transactions from
* @param options Optional filtering and retrieval options
* @returns Array of transaction requests sorted by timestamp (newest first)
*/
getTransactionRequests(topicId: string, options?: {
limit?: number;
sequenceNumber?: string | number;
order?: 'asc' | 'desc';
}): Promise<TransactMessage[]>;
/**
* Gets the HCS-10 transaction memo for analytics based on the operation type
* @param payload The operation payload
* @returns The transaction memo in format hcs-10:op:{operation_enum}:{topic_type_enum}
*/
protected getHcs10TransactionMemo(payload: object | string): string | null;
}
export declare class HCS10Cache {
private static instance;
private cache;
private cacheExpiry;
private readonly CACHE_TTL;
private constructor();
static getInstance(): HCS10Cache;
set(key: string, value: ProfileResponse): void;
get(key: string): ProfileResponse | undefined;
clear(): void;
}
//# sourceMappingURL=base-client.d.ts.map