@gear-js/api
Version:
A JavaScript library that provides functionality to connect GEAR Component APIs.
223 lines (222 loc) • 8.62 kB
TypeScript
import { AddressOrPair, SignerOptions } from '@polkadot/api/types';
import { ReplyCode } from './utils';
import { GearApi } from './GearApi';
import { HexString } from './types';
interface ICalculateReplyResult {
/**
* The encoded reply payload.
*/
readonly payload: HexString;
/**
* The value associated with the reply.
*/
readonly value: bigint;
/**
* The reply code as a ReplyCode object.
*/
readonly code: ReplyCode;
}
interface ITxResultBaseSuccess {
/**
* The transaction hash
*/
readonly txHash: HexString;
/**
* The block hash in which the transaction was included.
*/
readonly blockHash: HexString;
/**
* The block number in which the transaction was included.
*/
readonly blockNumber: number;
/**
* Indicates whether the transaction was succesful
*/
readonly success: true;
}
interface ITxResultBaseFailed extends Pick<ITxResultBaseSuccess, 'txHash'>, Partial<Pick<ITxResultBaseSuccess, 'blockHash' | 'blockNumber'>> {
success: false;
/**
* The error message if the transaction failed
*/
readonly error?: string;
}
type ITxResultBase = ITxResultBaseSuccess | ITxResultBaseFailed;
interface IMessageResponse {
/**
* The id of the message
*/
readonly id: HexString;
/**
* The encoded payload
*/
readonly payload: HexString;
/**
* The value associated with the message
*/
readonly value: bigint;
/**
* The reply code as a ReplyCode object
*/
readonly replyCode: ReplyCode;
}
interface ISendMessageResultSuccess extends ITxResultBaseSuccess {
/**
* The id of the message
*/
readonly id: HexString;
/**
* A function to get the response from the program
*/
readonly response: () => Promise<IMessageResponse>;
}
type ISendMessageResult = ISendMessageResultSuccess | ITxResultBaseFailed;
interface ISendMessageParams {
/**
* The payload to send
*/
readonly payload: HexString | Uint8Array;
/**
* The value to send with the message (default: 0)
*/
readonly value?: bigint | number;
/**
* The gas limit for the message (default: 'auto')
* - 'auto': calculate minimum required gas automatically
* - 'max': use maximum available block gas limit
* - number/bigint: specific gas limit value
*/
readonly gasLimit?: bigint | number | 'max' | 'auto';
/**
* Whether to use keep-alive for the transaction (default: true)
*/
readonly keepAlive?: boolean;
}
type ISentMessageInBatchSuccess = Pick<ISendMessageResultSuccess, 'id' | 'response' | 'success'>;
type ISentMessageInBatch = ISentMessageInBatchSuccess | Partial<Pick<ITxResultBaseFailed, 'success' | 'error'>>;
interface IBatchSendMessageResultSuccess extends ITxResultBaseSuccess {
/**
* Array of message IDs in the order they were sent
*/
readonly sentMessages: ISentMessageInBatch[];
}
type IBatchSendMessageResult = IBatchSendMessageResultSuccess | ITxResultBaseFailed;
/**
* # Program Class
* @param _id - The ID of the program.
* @param _api - An instance of the GearApi class
* @param _account - (optional) The account or address to be used for transactions.
* @param _signerOptions - (optional) Signer options for transactions.
*/
export declare class BaseGearProgram {
private _id;
private _api;
private _account?;
private _signerOptions?;
private _isInitialized;
readonly waitForInitialization: Promise<void>;
private _events;
private _storageUnsub;
constructor(_id: HexString, _api: GearApi, _account?: AddressOrPair, _signerOptions?: Partial<SignerOptions>);
/**
* ## Creates a new instance of the Program class and initializes it.
* @param programId - The program ID.
* @param api - The GearApi instance.
* @param account - (optional) The account or address to be used for transactions.
* @param signerOptions - (optional) Signer options for transactions.
* @returns An initialized Program instance.
*/
static new(programId: HexString, api: GearApi, account?: AddressOrPair, signerOptions?: Partial<SignerOptions>): Promise<BaseGearProgram>;
private _throwOnAccountNotSet;
private _init;
/**
* ## Subscribes to a specific event emitted by the program.
* @param action - The name of the event to subscribe to (e.g., 'programExited').
* @param callback - The callback function to execute when the event is triggered. Receives the inheritor ID as a parameter.
* @returns A function to unsubscribe from the event.
*/
on(action: 'programExited', callback: (inheritorId: HexString) => void | Promise<void>): Promise<() => void>;
/**
* ## Sets the account to be used for submitting transactions.
* @param account
* @param signerOptions
* @returns
*/
setAccount(account: AddressOrPair, signerOptions?: SignerOptions): BaseGearProgram;
private _submitTx;
get accountAddress(): HexString;
/**
* ## Gets the current program ID.
* @returns The program ID as a HexString.
*/
get id(): HexString;
/**
* Retrieves the current balance of the program.
* @returns The program's balance as a bigint.
*/
balance(): Promise<bigint>;
/**
* ## Transfers funds to the program to increase its balance.
* @param value - The amount to transfer as a bigint.
*/
topUp(value: bigint): Promise<Omit<ITxResultBase, 'events'>>;
/**
* ## Calculates the gas required for the message.
* @param payload - The encoded payload to send, as a HexString or Uint8Array.
* @param value - The value to send with the payload (default is 0).
* @param allowOtherPanics - Whether to allow panics in other programs during gas calculation (default is false).
* @returns Gas details.
*/
calculateGas(payload: HexString | Uint8Array, value?: bigint | number, allowOtherPanics?: boolean): Promise<{
minLimit: bigint;
reserved: bigint;
burned: bigint;
mayBeReturned: bigint;
waited: boolean;
}>;
/**
* ## Calculates the reply for a given payload and value.
* @param payload - The payload to send, as a HexString or Uint8Array.
* @param value - The value to send with the payload (default is 0).
* @param gasLimit - The gas limit for the reply ('max' or a specific value).
* @returns Reply details.
*/
calculateReply(payload: HexString | Uint8Array, value?: number, gasLimit?: bigint | number | 'max'): Promise<ICalculateReplyResult>;
/**
* ## Sends a message to the program.
* @param params - Message parameters object containing:
* @param params.payload - The payload to send, as a HexString or Uint8Array.
* @param params.value - The value to send with the message (default is 0).
* @param params.gasLimit - The gas limit for the message ('max', 'auto', or a specific value). If 'auto', it will be calculated automatically.
* @param params.keepAlive - Whether to use keep-alive for the transaction (default is true).
* @returns Promise resolving to the message sending result.
*/
sendMessage({ payload, value, gasLimit, keepAlive }: ISendMessageParams): Promise<ISendMessageResult>;
/**
* @deprecated - use sendMessage with ISendMessageParams instead
*/
sendMessage(payload: HexString | Uint8Array, value?: bigint | number, gasLimit?: bigint | number | 'max' | 'auto', keepAlive?: boolean): Promise<ISendMessageResult>;
/**
* ## Sends multiple messages to the program in a single batch transaction.
* @param messages - Array of message parameter objects to send in batch. Each object follows the ISendMessageParams interface.
* @returns Transaction result with message IDs and their individual success status.
*/
sendBatchMessages(messages: ISendMessageParams[]): Promise<IBatchSendMessageResult>;
private _waitForResponseHandler;
/**
* Resolves the gas limit based on the provided value or calculates it if needed.
* @param payload - The message payload.
* @param value - The value to send with the message.
* @param gasLimit - The requested gas limit or 'auto'/'max' option.
* @param keepAlive - Whether the message uses keep-alive semantics.
* @returns Resolved gas limit as a bigint.
* @private
*/
private _resolveGasLimit;
}
/**
* @deprecated - use BaseGearProgram instead
*/
export declare class Program extends BaseGearProgram {
}
export {};