@gear-js/api
Version:
A JavaScript library that provides functionality to connect GEAR Component APIs.
269 lines (268 loc) • 11.6 kB
TypeScript
import type { SubmittableExtrinsic } from '@polkadot/api/types';
import type { ISubmittableResult } from '@polkadot/types/types';
import type { UserMessageSent, UserMessageSentData } from '../events';
import type { ProgramMetadata } from '../metadata';
import type { HexString, ICalculateReplyForHandleOptions, MessageSendOptions, MessageSendReplyOptions, ReplyInfo, UserMessageSentSubscriptionFilter, UserMessageSentSubscriptionItem } from '../types';
import { GearTransaction } from './Transaction';
export declare class GearMessage extends GearTransaction {
/**
* ## Send Message
* @param args Message parameters.
* @param meta Program metadata obtained using `getProgramMetadata` function.
* @param typeIndex (optional) Index of type in the registry. If not specified the type index from `meta.handle.input` will be used instead.
* @returns Submitable result
*
* _Note that parameter `prepaid` is not supported starting from `1010` runtime version._
* @example
* ```javascript
* const programId = '0x..';
* const hexMeta = '0x...';
* const meta = ProgramMetadata.from(hexMeta);
*
* const tx = api.message.send({
* destination: programId,
* payload: { amazingPayload: { } },
* gasLimit: 20_000_000
* }, meta, meta.handle.input)
*
* tx.signAndSend(account, (events) => {
* events.forEach(({event}) => console.log(event.toHuman()))
* })
* ```
*/
send(args: MessageSendOptions, meta: ProgramMetadata, typeIndex?: number): SubmittableExtrinsic<'promise', ISubmittableResult>;
/**
* ## Send Message
* @param args Message parameters
* @param hexRegistry Registry in hex format
* @param typeIndex Index of type in the registry.
* @returns Submitable result
*
* _Note that parameter `prepaid` is not supported starting from `1010` runtime version._
* @example
* ```javascript
* const programId = '0x..';
* const hexRegistry = '0x...';
*
* const tx = api.message.send({
* destination: programId,
* payload: { amazingPayload: { ... } },
* gasLimit: 20_000_000
* }, hexRegistry, 4)
*
* tx.signAndSend(account, (events) => {
* events.forEach(({event}) => console.log(event.toHuman()))
* })
* ```
*/
send(args: MessageSendOptions, hexRegistry: HexString, typeIndex: number): SubmittableExtrinsic<'promise', ISubmittableResult>;
/**
* ## Send Message
* @param args Message parameters
* @param metaOrHexRegistry (optional) Registry in hex format or ProgramMetadata
* @param typeName payload type (one of the default rust types if metadata or registry don't specified)
* @returns Submitable result
*
* _Note that parameter `prepaid` is not supported starting from `1010` runtime version._
* @example
* ```javascript
* const programId = '0x..';
*
* const tx = api.message.send({
* destination: programId,
* payload: 'PING',
* gasLimit: 20_000_000
* }, undefined, 'String')
*
* tx.signAndSend(account, (events) => {
* events.forEach(({event}) => console.log(event.toHuman()))
* })
* ```
*/
send(args: MessageSendOptions, metaOrHexRegistry?: ProgramMetadata | HexString, typeName?: string): SubmittableExtrinsic<'promise', ISubmittableResult>;
/**
* ## Send reply message
* @param args Message parameters
* @param meta Program metadata obtained using `ProgramMetadata.from` method.
* @param typeIndex (optional) Index of type in the registry. If not specified the type index from `meta.reply.input` will be used instead.
* @returns Submitable result
*
* _Note that parameter `prepaid` is not supported starting from `1010` runtime version._
* @example
* ```javascript
* const replyToMessage = '0x..';
* const hexMeta = '0x...';
* const meta = ProgramMetadata.from(hexMeta);
*
* const tx = api.message.send({
* replyToId: replyToMessage,
* payload: { amazingPayload: { } },
* gasLimit: 20_000_000
* }, meta, meta.reply.input)
*
* tx.signAndSend(account, (events) => {
* events.forEach(({event}) => console.log(event.toHuman()))
* })
* ```
*/
sendReply(args: MessageSendReplyOptions, meta?: ProgramMetadata, typeIndex?: number): Promise<SubmittableExtrinsic<'promise', ISubmittableResult>>;
/**
* ## Send reply message
* @param args Message parameters
* @param hexRegistry Registry in hex format
* @param typeIndex Index of type in the registry.
* @returns Submitable result
*
* _Note that parameter `prepaid` is not supported starting from `1010` runtime version._
* @example
* ```javascript
* const replyToMessage = '0x..';
* const hexRegistry = '0x...';
*
* const tx = api.message.send({
* replyToId: replyToMessage,
* payload: { amazingPayload: { } },
* gasLimit: 20_000_000
* }, hexRegistry, 5)
*
* tx.signAndSend(account, (events) => {
* events.forEach(({event}) => console.log(event.toHuman()))
* })
* ```
*/
sendReply(args: MessageSendReplyOptions, hexRegistry: HexString, typeIndex: number): Promise<SubmittableExtrinsic<'promise', ISubmittableResult>>;
/**
* ## Send reply message
* @param args Message parameters
* @param metaOrHexRegistry (optional) Registry in hex format or ProgramMetadata
* @param typeName payload type (one of the default rust types if metadata or registry don't specified)
* @returns Submitable extrinsic
*
* _Note that parameter `prepaid` is not supported starting from `1010` runtime version._
* @example
* ```javascript
* const replyToMessage = '0x..';
* const hexRegistry = '0x...';
*
* const tx = api.message.send({
* replyToId: replyToMessage,
* payload: { amazingPayload: { } },
* gasLimit: 20_000_000
* }, hexRegistry, 5)
*
* tx.signAndSend(account, (events) => {
* events.forEach(({event}) => console.log(event.toHuman()))
* })
* ```
*/
sendReply(args: MessageSendReplyOptions, metaOrHexRegistry?: ProgramMetadata | HexString, typeName?: string): Promise<SubmittableExtrinsic<'promise', ISubmittableResult>>;
/**
* ## Get event with reply message
* @param msgId - id of sent message
* @param txBlock - number or hash of block where the message was sent
* @returns UserMessageSent event
*/
getReplyEvent(programId: HexString, msgId: HexString | null, txBlock: HexString | number): Promise<UserMessageSent>;
/**
* @deprecated Use `getReplyEvent` instead
*/
listenToReplies(programId: HexString, bufferSize?: number): (messageId: HexString) => Promise<UserMessageSentData>;
/**
* ## Send message to the program and get the reply.
* This method is immutable and doesn't send any extrinsic.
* @param params Message parameters
* @param meta (optional) Program metadata obtained using `ProgramMetadata.from` method.
* @param typeIndexOrTypeName (optional) Index of type in the registry. If not specified the type index from `meta.handle.input` will be used instead.
* @returns Reply info structure
*
* @example
* ```javascript
* const programId = '0x..';
* const origin = '0x...';
* const meta = ProgramMetadata.from('0x...');
* const result = await api.message.calculateReply({
* origin,
* destination: programId,
* payload: { myPayload: [] },
* value: 0
* }, meta);
*
* console.log(result.toJSON());
* console.log('reply payload:', meta.createType(meta.types.handle.output, result.payload).toJSON());
*/
calculateReply({ payload, origin, destination, value, gasLimit, at }: ICalculateReplyForHandleOptions, meta?: ProgramMetadata, typeIndexOrTypeName?: number | string): Promise<ReplyInfo>;
/**
* ## Subscribe to User Message Sent Events
*
* Subscribe to real-time notifications of messages sent from programs to users.
* Provides server-side filtering capabilities for efficient event tracking without client-side processing.
*
* The subscription automatically filters out acknowledgment messages and only returns actual message events.
*
* @param filter - Filter criteria for subscribed messages
* @param filter.source - Optional: Program ID to filter messages from. If not specified, all programs are tracked.
* @param filter.destination - Optional: User address to filter messages sent to. If not specified, all destinations are tracked.
* @param filter.payloadFilters - Optional: Array of PayloadFilter objects to filter messages by their payload content.
* @param filter.fromBlock - Optional: Block number to start listening from. Defaults to current block.
* @param filter.finalizedOnly - Optional: If true, only process finalized blocks. Defaults to false.
*
* @param callback - Function called when a matching message is detected.
* The callback receives a readonly UserMessageSentSubscriptionItem containing:
* - id: Unique message identifier (HexString)
* - source: Program ID that sent the message (HexString)
* - destination: User address that received the message (HexString)
* - payload: Message payload in hex format (HexString)
* - value: Value transferred with the message (bigint)
* - block: Block hash where the message was processed (HexString)
* - index: Index of the message within the block (number)
* - reply: Optional reply details if the message is a reply:
* - to: Original message ID being replied to (HexString)
* - code: Human-readable reply code/status (string)
* - codeRaw: Raw reply code in hex format (HexString)
*
* @returns Unsubscribe function. Call this to stop receiving message notifications.
*
* @throws RpcMethodNotSupportedError - If the connected node does not support the subscription method.
*
* @example
* ```typescript
* // Subscribe to all messages from a specific program
* const unsubscribe = await api.message.subscribeUserMessageSent(
* { source: '0x...' },
* (item) => {
* console.log('Message ID:', item.id);
* console.log('From program:', item.source);
* console.log('To user:', item.destination);
* console.log('Payload:', item.payload);
* }
* );
*
* // Later, stop listening
* unsubscribe();
* ```
*
* @example
* ```typescript
* // Subscribe with comprehensive filtering
* const payloadFilter = new PayloadFilter();
* payloadFilter.setBytes('0xdeadbeef');
*
* const unsubscribe = await api.message.subscribeUserMessageSent(
* {
* source: '0x...',
* destination: '0x...',
* payloadFilters: [payloadFilter],
* fromBlock: 12345,
* finalizedOnly: true
* },
* async (item) => {
* console.log(`Block: ${item.block}, Message: ${item.id}`);
* if (item.reply) {
* console.log(`This is a reply with code: ${item.reply.code}`);
* }
* }
* );
* ```
*/
subscribeUserMessageSent(filter: UserMessageSentSubscriptionFilter, callback: (item: Readonly<UserMessageSentSubscriptionItem>) => void | Promise<void>): Promise<() => void>;
}