diff --git a/bindings/nodejs/lib/client/client-method-handler.ts b/bindings/nodejs/lib/client/client-method-handler.ts index 06da03a745..fb28a4a006 100644 --- a/bindings/nodejs/lib/client/client-method-handler.ts +++ b/bindings/nodejs/lib/client/client-method-handler.ts @@ -9,10 +9,15 @@ import { } from '../bindings'; import type { IClientOptions, __ClientMethods__ } from '../types/client'; -/** The MethodHandler which sends the commands to the Rust side. */ +/** + * The MethodHandler which sends the commands to the Rust side. + */ export class ClientMethodHandler { methodHandler: ClientMethodHandler; + /** + * @param options client options or a client method handler. + */ constructor(options: IClientOptions | ClientMethodHandler) { // The rust client object is not extensible if (Object.isExtensible(options)) { @@ -26,6 +31,12 @@ export class ClientMethodHandler { return destroyClient(this.methodHandler); } + /** + * Call a client method. + * + * @param method The client method. + * @returns A promise that resolves to a JSON string response holding the result of the client method. + */ async callMethod(method: __ClientMethods__): Promise { return callClientMethodAsync( JSON.stringify(method), @@ -33,7 +44,12 @@ export class ClientMethodHandler { ); } - // MQTT + /** + * Listen to MQTT events. + * + * @param topics The topics to listen to. + * @param callback The callback to be called when an MQTT event is received. + */ async listen( topics: string[], callback: (error: Error, result: string) => void, diff --git a/bindings/nodejs/lib/client/client.ts b/bindings/nodejs/lib/client/client.ts index 58f2bb6183..94d00edb84 100644 --- a/bindings/nodejs/lib/client/client.ts +++ b/bindings/nodejs/lib/client/client.ts @@ -61,6 +61,9 @@ import { plainToInstance } from 'class-transformer'; export class Client { private methodHandler: ClientMethodHandler; + /** + * @param options client options or a client method handler. + */ constructor(options: IClientOptions | ClientMethodHandler) { this.methodHandler = new ClientMethodHandler(options); } @@ -70,8 +73,7 @@ export class Client { } /** - * Returns the node information together with the url of the used node - * @returns { Promise }. + * Get the node information together with the url of the used node. */ async getInfo(): Promise { const response = await this.methodHandler.callMethod({ @@ -82,7 +84,7 @@ export class Client { } /** - * Gets the network related information such as network_id and min_pow_score + * Get network related information such as protocol parameters and minimum pow score. */ async getNetworkInfo(): Promise { const response = await this.methodHandler.callMethod({ @@ -92,7 +94,9 @@ export class Client { return JSON.parse(response).payload; } - /** Fetch basic output IDs based on query parameters */ + /** + * Fetch basic output IDs based on the given query parameters. + */ async basicOutputIds( queryParameters: QueryParameter[], ): Promise { @@ -106,7 +110,9 @@ export class Client { return JSON.parse(response).payload; } - /** Get output from a known outputID */ + /** + * Get output from a given output ID. + */ async getOutput(outputId: OutputId): Promise { const response = await this.methodHandler.callMethod({ name: 'getOutput', @@ -119,7 +125,9 @@ export class Client { return plainToInstance(OutputResponse, parsed.payload); } - /** Fetch OutputResponse from provided OutputIds (requests are sent in parallel) */ + /** + * Fetch OutputResponse from given output IDs. Requests are sent in parallel. + */ async getOutputs(outputIds: OutputId[]): Promise { const response = await this.methodHandler.callMethod({ name: 'getOutputs', @@ -132,7 +140,13 @@ export class Client { return plainToInstance(OutputResponse, parsed.payload); } - /** Build and post a block */ + /** + * Build and post a block. + * + * @param secretManager One of the supported secret managers. + * @param options Options on how to build a block. + * @returns The block ID and the posted block itself. + */ async buildAndPostBlock( secretManager?: SecretManagerType, options?: IBuildBlockOptions, @@ -164,8 +178,9 @@ export class Client { } /** - * Returns tips that are ideal for attaching a block. - * The tips can be considered as non-lazy and are therefore ideal for attaching a block. + * Request tips from the node. + * The tips can be considered as non-lazy and are therefore ideal for attaching a block to the Tangle. + * @returns An array of tips represented by their block IDs. */ async getTips(): Promise { const response = await this.methodHandler.callMethod({ @@ -176,7 +191,10 @@ export class Client { } /** - * Post block in JSON format, returns the block ID. + * Post a block in JSON format. + * + * @param block The block to post. + * @returns The block ID once the block has been posted. */ async postBlock(block: Block): Promise { const response = await this.methodHandler.callMethod({ @@ -190,7 +208,10 @@ export class Client { } /** - * Get block as JSON. + * Get a block in JSON format. + * + * @param blockId The corresponding block ID of the requested block. + * @returns The requested block. */ async getBlock(blockId: BlockId): Promise { const response = await this.methodHandler.callMethod({ @@ -205,7 +226,10 @@ export class Client { } /** - * Get block metadata. + * Get the metadata of a block. + * + * @param blockId The corresponding block ID of the requested block metadata. + * @returns The requested block metadata. */ async getBlockMetadata(blockId: BlockId): Promise { const response = await this.methodHandler.callMethod({ @@ -219,7 +243,11 @@ export class Client { } /** - * Find inputs from addresses for a provided amount (useful for offline signing) + * Find inputs from addresses for a given amount (useful for offline signing). + * + * @param addresses A list of included addresses. + * @param amount The amount to find inputs for. + * @returns An array of UTXO inputs. */ async findInputs( addresses: string[], @@ -238,7 +266,11 @@ export class Client { } /** - * Prepare a transaction for signing + * Prepare a transaction for signing. + * + * @param secretManager One of the supported secret managers. + * @param options Options to build a block. + * @returns An instance of `PreparedTransactionData`. */ async prepareTransaction( secretManager?: SecretManagerType, @@ -259,7 +291,11 @@ export class Client { } /** - * Sign a transaction + * Sign a transaction. + * + * @param secretManager One of the supported secret managers. + * @param preparedTransactionData An instance of `PreparedTransactionData`. + * @returns The corresponding transaction payload. */ async signTransaction( secretManager: SecretManagerType, @@ -278,7 +314,12 @@ export class Client { } /** - * Create a signature unlock using the provided `secretManager`. + * Create a signature unlock using the given secret manager. + * + * @param secretManager One of the supported secret managers. + * @param transactionEssenceHash The hash of the transaction essence. + * @param chain A BIP44 chain + * @returns The corresponding unlock condition. */ async signatureUnlock( secretManager: SecretManagerType, @@ -298,7 +339,10 @@ export class Client { } /** - * Submit a payload in a block + * Submit a payload in a block. + * + * @param payload The payload to post. + * @returns The block ID followed by the block containing the payload. */ async postBlockPayload(payload: Payload): Promise<[BlockId, Block]> { const response = await this.methodHandler.callMethod({ @@ -324,7 +368,7 @@ export class Client { } /** - * Get the network id of the node we're connecting to. + * Get the ID of the network the node is connected to. */ async getNetworkId(): Promise { const response = await this.methodHandler.callMethod({ @@ -335,7 +379,7 @@ export class Client { } /** - * Returns the bech32_hrp. + * Get the Bech32 HRP (human readable part) of the network the node is connected to. */ async getBech32Hrp(): Promise { const response = await this.methodHandler.callMethod({ @@ -346,7 +390,7 @@ export class Client { } /** - * Returns the min PoW score. + * Get the minimum PoW score. */ async getMinPowScore(): Promise { const response = await this.methodHandler.callMethod({ @@ -357,7 +401,7 @@ export class Client { } /** - * Returns the tips interval. + * Get the tips interval. */ async getTipsInterval(): Promise { const response = await this.methodHandler.callMethod({ @@ -368,14 +412,14 @@ export class Client { } /** - * Returns the token supply. + * Get the token supply. */ async getTokenSupply(): Promise { return (await this.getProtocolParameters()).tokenSupply; } /** - * Returns the protocol parameters. + * Get the protocol parameters. */ async getProtocolParameters(): Promise { const response = await this.methodHandler.callMethod({ @@ -386,7 +430,7 @@ export class Client { } /** - * Returns if local pow should be used or not. + * Check whether local pow should be used or not. */ async getLocalPow(): Promise { const response = await this.methodHandler.callMethod({ @@ -397,7 +441,7 @@ export class Client { } /** - * Get fallback to local proof of work timeout. + * Check whether to fallback to local proof of work in case the node doesn't support remote PoW. */ async getFallbackToLocalPow(): Promise { const response = await this.methodHandler.callMethod({ @@ -408,7 +452,9 @@ export class Client { } /** - * Get health of node by input url. + * Get the health of a node. + * + * @param url The URL of the node. */ async getHealth(url: string): Promise { const response = await this.methodHandler.callMethod({ @@ -422,7 +468,10 @@ export class Client { } /** - * Get info of node with input url. + * Get the info about the node. + * + * @param url The URL of the node. + * @param auth An authentication object (e.g. JWT). */ async getNodeInfo(url: string, auth?: IAuth): Promise { const response = await this.methodHandler.callMethod({ @@ -437,7 +486,7 @@ export class Client { } /** - * Get peers. + * Get the peers of the node. */ async getPeers(): Promise { const response = await this.methodHandler.callMethod({ @@ -449,6 +498,9 @@ export class Client { /** * Post block as raw bytes, returns the block ID. + * + * @param block The block. + * @returns The ID of the posted block. */ async postBlockRaw(block: Block): Promise { const response = await this.methodHandler.callMethod({ @@ -463,6 +515,9 @@ export class Client { /** * Get block as raw bytes. + * + * @param blockId The block ID of the requested block. + * @returns The raw bytes of the requested block. */ async getBlockRaw(blockId: BlockId): Promise { const response = await this.methodHandler.callMethod({ @@ -476,7 +531,10 @@ export class Client { } /** - * Look up a milestone by a given milestone index. + * Get a milestone payload by its ID. + * + * @param milestoneId The ID of the requested milestone. + * @returns The corresponding milestone payload. */ async getMilestoneById(milestoneId: string): Promise { const response = await this.methodHandler.callMethod({ @@ -490,7 +548,10 @@ export class Client { } /** - * Returns all UTXO changes that happened at a specific milestone. + * Get all UTXO changes of a milestone by its ID. + * + * @param milestoneId The ID of the milestone that applied the UTXO changes. + * @returns A milestone UTXO changes response. */ async getUtxoChangesById( milestoneId: string, @@ -504,8 +565,12 @@ export class Client { return JSON.parse(response).payload; } + /** - * Look up a milestone by a given milestone index. + * Get a milestone payload by its index. + * + * @param index The index of the requested milestone. + * @returns The corresponding milestone payload. */ async getMilestoneByIndex(index: number): Promise { const response = await this.methodHandler.callMethod({ @@ -519,7 +584,10 @@ export class Client { } /** - * Returns all UTXO changes that happened at a specific milestone. + * Get all UTXO changes of a milestone by its index. + * + * @param index The index of the milestone that applied the UTXO changes. + * @returns A milestone UTXO changes response. */ async getUtxoChangesByIndex( index: number, @@ -535,7 +603,7 @@ export class Client { } /** - * Get receipts. + * Get all receipts. */ async getReceipts(): Promise { const response = await this.methodHandler.callMethod({ @@ -546,7 +614,9 @@ export class Client { } /** - * Get the receipts by the given milestone index. + * Get the receipts at a given milestone index. + * + * @param milestoneIndex The index of the milestone that migrated funds to the new network. */ async getReceiptsMigratedAt( milestoneIndex: number, @@ -573,7 +643,10 @@ export class Client { } /** - * Returns the included block of the transaction. + * Get the included block of a given transaction. + * + * @param transactionId The ID of the transaction. + * @returns The included block that contained the transaction. */ async getIncludedBlock(transactionId: string): Promise { const response = await this.methodHandler.callMethod({ @@ -587,7 +660,10 @@ export class Client { } /** - * Returns the metadata of the included block of the transaction. + * Get the metadata of the included block of a given transaction. + * + * @param transactionId The ID of the transaction. + * @returns The included block that contained the transaction. */ async getIncludedBlockMetadata(transactionId: string): Promise { const response = await this.methodHandler.callMethod({ @@ -601,7 +677,11 @@ export class Client { } /** - * Transforms a hex encoded address to a bech32 encoded address. + * Convert a hex encoded address to a Bech32 encoded address. + * + * @param hex The hexadecimal string representation of an address. + * @param bech32Hrp The Bech32 HRP (human readable part) to be used. + * @returns The corresponding Bech32 address. */ async hexToBech32(hex: string, bech32Hrp?: string): Promise { const response = await this.methodHandler.callMethod({ @@ -616,7 +696,11 @@ export class Client { } /** - * Transforms an alias id to a bech32 encoded address. + * Convert an Alias ID to a Bech32 encoded address. + * + * @param aliasId An Alias ID. + * @param bech32Hrp The Bech32 HRP (human readable part) to be used. + * @returns The corresponding Bech32 address. */ async aliasIdToBech32( aliasId: string, @@ -634,7 +718,11 @@ export class Client { } /** - * Transforms an nft id to a bech32 encoded address. + * Convert an NFT ID to a Bech32 encoded address. + * + * @param nftId An NFT ID. + * @param bech32Hrp The Bech32 HRP (human readable part) to be used. + * @returns The corresponding Bech32 address. */ async nftIdToBech32(nftId: string, bech32Hrp?: string): Promise { const response = await this.methodHandler.callMethod({ @@ -649,7 +737,11 @@ export class Client { } /** - * Transforms a hex encoded public key to a bech32 encoded address. + * Convert a hex encoded public key to a Bech32 encoded address. + * + * @param hex The hexadecimal string representation of a public key. + * @param bech32Hrp The Bech32 HRP (human readable part) to be used. + * @returns The corresponding Bech32 address. */ async hexPublicKeyToBech32Address( hex: string, @@ -667,7 +759,10 @@ export class Client { } /** - * Fetch alias output IDs + * Get the corresponding output IDs given a list of Alias query parameters. + * + * @param queryParameters An array of `AliasQueryParameter`s. + * @returns A paginated query response of corresponding output IDs. */ async aliasOutputIds( queryParameters: AliasQueryParameter[], @@ -683,7 +778,10 @@ export class Client { } /** - * Fetch alias output ID + * Get the corresponding output ID from an Alias ID. + * + * @param aliasId An Alias ID. + * @returns The corresponding output ID. */ async aliasOutputId(aliasId: string): Promise { const response = await this.methodHandler.callMethod({ @@ -697,7 +795,10 @@ export class Client { } /** - * Fetch NFT output IDs + * Get the corresponding output IDs given a list of NFT query parameters. + * + * @param queryParameters An array of `NftQueryParameter`s. + * @returns A paginated query response of corresponding output IDs. */ async nftOutputIds( queryParameters: NftQueryParameter[], @@ -713,7 +814,10 @@ export class Client { } /** - * Fetch NFT output ID + * Get the corresponding output ID from an NFT ID. + * + * @param nftId An NFT ID. + * @returns The corresponding output ID. */ async nftOutputId(nftId: string): Promise { const response = await this.methodHandler.callMethod({ @@ -727,7 +831,10 @@ export class Client { } /** - * Fetch Foundry Output IDs + * Get the corresponding output IDs given a list of Foundry query parameters. + * + * @param queryParameters An array of `FoundryQueryParameter`s. + * @returns A paginated query response of corresponding output IDs. */ async foundryOutputIds( queryParameters: FoundryQueryParameter[], @@ -743,7 +850,10 @@ export class Client { } /** - * Fetch Foundry Output ID + * Get the corresponding output ID from a Foundry ID. + * + * @param foundryId A Foundry ID. + * @returns The corresponding output ID. */ async foundryOutputId(foundryId: string): Promise { const response = await this.methodHandler.callMethod({ @@ -757,8 +867,11 @@ export class Client { } /** - * Try to get OutputResponse from provided OutputIds (requests are sent + * Get outputs from provided output IDs (requests are sent * in parallel and errors are ignored, can be useful for spent outputs) + * + * @param outputIds An array of output IDs. + * @returns An array of corresponding output responses. */ async getOutputsIgnoreErrors( outputIds: string[], @@ -774,7 +887,10 @@ export class Client { } /** - * Find all blocks by provided block IDs. + * Find blocks by their IDs. + * + * @param blockIds An array of `BlockId`s. + * @returns An array of corresponding blocks. */ async findBlocks(blockIds: BlockId[]): Promise { const response = await this.methodHandler.callMethod({ @@ -788,8 +904,12 @@ export class Client { } /** - * Retries (promotes or reattaches) a block for provided block id. Block should be - * retried only if they are valid and haven't been confirmed for a while. + * Retry (promote or reattach) a block given its block ID. + * + * **Note**: Blocks should be retried only if they are valid and haven't been confirmed for some time. + * + * @param blockId The ID of the block to retry. + * @returns The included block. */ async retry(blockId: BlockId): Promise<[BlockId, Block]> { const response = await this.methodHandler.callMethod({ @@ -804,9 +924,13 @@ export class Client { } /** - * Retries (promotes or reattaches) a block for provided block id until it's included (referenced by a - * milestone). Default interval is 5 seconds and max attempts is 40. Returns the included block at first - * position and additional reattached blocks + * Retry (promote or reattach) a block given its block ID until it's included + * (i.e. referenced by a milestone). + * + * @param blockId The ID of the block to retry. + * @param interval A retry interval in seconds. Defaults to 5. + * @param maxAttempts A maximum number of retries. Defaults to 40. + * @returns The included block at first position and additional reattached blocks. */ async retryUntilIncluded( blockId: BlockId, @@ -831,8 +955,11 @@ export class Client { } /** - * Function to consolidate all funds from a range of addresses to the address with the lowest index in that range - * Returns the address to which the funds got consolidated, if any were available + * Consolidate all funds from a range of addresses to the address with the lowest index in that range. + * + * @param secretManager One of supported secret managers. + * @param generateAddressesOptions Options for generating addresses. + * @returns The address to which the funds got consolidated, if any were available. */ async consolidateFunds( secretManager: SecretManagerType, @@ -850,8 +977,12 @@ export class Client { } /** - * Reattaches blocks for provided block id. Blocks can be reattached only if they are valid and haven't been - * confirmed for a while. + * Reattach a block. + * + * **Note**: Blocks can be reattached only if they are valid and haven't been confirmed for some time. + * + * @param blockId The ID of the block to reattach. + * @returns The included block. */ async reattach(blockId: BlockId): Promise<[BlockId, Block]> { const response = await this.methodHandler.callMethod({ @@ -866,7 +997,10 @@ export class Client { } /** - * Reattach a block without checking if it should be reattached + * Reattach a block without checking whether it should be reattached. + * + * @param blockId The ID of the block to reattach. + * @returns The included block. */ async reattachUnchecked(blockId: BlockId): Promise<[BlockId, Block]> { const response = await this.methodHandler.callMethod({ @@ -881,8 +1015,13 @@ export class Client { } /** - * Promotes a block. The method should validate if a promotion is necessary through get_block. If not, the - * method should error out and should not allow unnecessary promotions. + * Promote a block. + * + * **NOTE**: The method validates whether a promotion is necessary through `get_block`. If not, the + * method will error out and will not do unnecessary promotions. + * + * @param blockId The ID of the block to promote. + * @returns The included block. */ async promote(blockId: BlockId): Promise<[BlockId, Block]> { const response = await this.methodHandler.callMethod({ @@ -896,7 +1035,10 @@ export class Client { return [parsed.payload[0], block]; } /** - * Promote a block without checking if it should be promoted + * Promote a block without checking if it should be promoted. + * + * @param blockId The ID of the block to promote. + * @returns The included block. */ async promoteUnchecked(blockId: BlockId): Promise<[BlockId, Block]> { const response = await this.methodHandler.callMethod({ @@ -911,7 +1053,7 @@ export class Client { } /** - * Returns the unhealthy nodes. + * Return the unhealthy nodes. */ async unhealthyNodes(): Promise> { const response = await this.methodHandler.callMethod({ @@ -922,7 +1064,9 @@ export class Client { } /** - * Build a Basic Output. + * Build a basic output. + * + * @param params An instance of `BasicOutputBuilderParams`. */ async buildBasicOutput( params: BasicOutputBuilderParams, @@ -940,7 +1084,9 @@ export class Client { } /** - * Build an Alias Output. + * Build an alias output. + * + * @param params An instance of `AliasOutputBuilderParams`. */ async buildAliasOutput( params: AliasOutputBuilderParams, @@ -958,7 +1104,9 @@ export class Client { } /** - * Build a Foundry Output. + * Build a foundry output. + * + * @param params An instance of `FoundryOutputBuilderParams`. */ async buildFoundryOutput( params: FoundryOutputBuilderParams, @@ -976,7 +1124,9 @@ export class Client { } /** - * Build an Nft Output. + * Build an NFT output. + * + * @param params An instance of `NftOutputBuilderParams`. */ async buildNftOutput(params: NftOutputBuilderParams): Promise { if (params.amount && typeof params.amount === 'bigint') { @@ -992,7 +1142,9 @@ export class Client { } /** - * Listen to MQTT topics. + * Listen to MQTT events. + * + * @param topics An array of MQTT topics to listen to. */ async listenMqtt( topics: string[], @@ -1002,7 +1154,9 @@ export class Client { } /** - * Stop listening for provided MQTT topics. + * Stop listening to certain MQTT events. + * + * @param topics An array of MQTT topics to stop listening to. */ async clearMqttListeners(topics: string[]): Promise { await this.methodHandler.callMethod({ @@ -1015,8 +1169,9 @@ export class Client { /** * Calculate the minimum required storage deposit for an output. - * @param output output to calculate the deposit amount for. - * @returns The amount. + * + * @param output The output to calculate the minimum deposit amount for. + * @returns The minimum required amount. */ async minimumRequiredStorageDeposit(output: Output): Promise { const response = await this.methodHandler.callMethod({ @@ -1029,7 +1184,13 @@ export class Client { } /** - * Request funds from a faucet, for example `https://faucet.testnet.shimmer.network/api/enqueue` or `http://localhost:8091/api/enqueue`. + * Request funds from a faucet. + * + * Example URLs: `https://faucet.testnet.shimmer.network/api/enqueue` or `http://localhost:8091/api/enqueue`. + * + * @param url The URL of the faucet. + * @param address The address to send the funds to. + * @returns The faucet response. */ async requestFundsFromFaucet( url: string, @@ -1045,6 +1206,7 @@ export class Client { /** * Extension method which provides request methods for plugins. + * * @param basePluginPath The base path for the plugin eg indexer/v1/ . * @param method The http method. * @param endpoint The path for the plugin request. diff --git a/bindings/nodejs/lib/secret_manager/secret-manager-method-handler.ts b/bindings/nodejs/lib/secret_manager/secret-manager-method-handler.ts index a203676ed6..639aa6a036 100644 --- a/bindings/nodejs/lib/secret_manager/secret-manager-method-handler.ts +++ b/bindings/nodejs/lib/secret_manager/secret-manager-method-handler.ts @@ -11,10 +11,13 @@ import { __SecretManagerMethods__, } from '../types/secret_manager'; -/** The MethodHandler which sends the commands to the Rust side. */ +/** The MethodHandler which sends the commands to the Rust backend. */ export class SecretManagerMethodHandler { methodHandler: SecretManagerMethodHandler; + /** + * @param options A secret manager type or a secret manager method handler. + */ constructor(options: SecretManagerType | SecretManagerMethodHandler) { // The rust secret manager object is not extensible if (Object.isExtensible(options)) { @@ -24,6 +27,12 @@ export class SecretManagerMethodHandler { } } + /** + * Call a secret manager method. + * + * @param method One of the supported secret manager methods. + * @returns The JSON response of the method. + */ async callMethod(method: __SecretManagerMethods__): Promise { return callSecretManagerMethodAsync( JSON.stringify(method), diff --git a/bindings/nodejs/lib/secret_manager/secret-manager.ts b/bindings/nodejs/lib/secret_manager/secret-manager.ts index 96574bb445..0a04e2031b 100644 --- a/bindings/nodejs/lib/secret_manager/secret-manager.ts +++ b/bindings/nodejs/lib/secret_manager/secret-manager.ts @@ -26,11 +26,19 @@ import { plainToInstance } from 'class-transformer'; export class SecretManager { private methodHandler: SecretManagerMethodHandler; + /** + * @param options A secret manager type or a secret manager method handler. + */ constructor(options: SecretManagerType | SecretManagerMethodHandler) { this.methodHandler = new SecretManagerMethodHandler(options); } - /** Generate ed25519 addresses */ + /** + * Generate Ed25519 addresses. + * + * @param generateAddressesOptions Options to generate addresses. + * @returns An array of generated addresses. + */ async generateEd25519Addresses( generateAddressesOptions: IGenerateAddressesOptions, ): Promise { @@ -44,7 +52,12 @@ export class SecretManager { return JSON.parse(response).payload; } - /** Generate EVM addresses */ + /** + * Generate EVM addresses. + * + * @param generateAddressesOptions Options to generate addresses. + * @returns An array of generated addresses. + */ async generateEvmAddresses( generateAddressesOptions: IGenerateAddressesOptions, ): Promise { @@ -59,7 +72,9 @@ export class SecretManager { } /** - * Store a mnemonic in the Stronghold vault + * Store a mnemonic in the Stronghold vault. + * + * @param mnemonic The mnemonic to store. */ async storeMnemonic(mnemonic: string): Promise { const response = await this.methodHandler.callMethod({ @@ -73,7 +88,10 @@ export class SecretManager { } /** - * Sign a transaction + * Sign a transaction. + * + * @param preparedTransactionData An instance of `PreparedTransactionData`. + * @returns The corresponding transaction payload. */ async signTransaction( preparedTransactionData: PreparedTransactionData, @@ -91,6 +109,10 @@ export class SecretManager { /** * Create a signature unlock using the provided `secretManager`. + * + * @param transactionEssenceHash The hash of the transaction essence. + * @param chain A BIP44 chain. + * @returns The corresponding unlock. */ async signatureUnlock( transactionEssenceHash: HexEncodedString, @@ -109,6 +131,10 @@ export class SecretManager { /** * Signs a message with an Ed25519 private key. + * + * @param message The message to sign. + * @param chain A BIP44 chain. + * @returns The corresponding signature. */ async signEd25519( message: HexEncodedString, @@ -126,6 +152,10 @@ export class SecretManager { /** * Signs a message with an Secp256k1Ecdsa private key. + * + * @param message The message to sign. + * @param chain A BIP44 chain. + * @returns The corresponding signature. */ async signSecp256k1Ecdsa( message: HexEncodedString, @@ -142,7 +172,7 @@ export class SecretManager { } /** - * Get the status of a Ledger Nano + * Get the status of a Ledger Nano. */ async getLedgerNanoStatus(): Promise { const response = await this.methodHandler.callMethod({ diff --git a/bindings/nodejs/lib/types/block/address.ts b/bindings/nodejs/lib/types/block/address.ts index ff3da06b8b..412cc922e2 100644 --- a/bindings/nodejs/lib/types/block/address.ts +++ b/bindings/nodejs/lib/types/block/address.ts @@ -5,20 +5,32 @@ import { plainToInstance } from 'class-transformer'; import { HexEncodedString } from '../utils'; import { AliasId, NftId } from './id'; +/** + * Address type variants. + */ enum AddressType { + /** An Ed25519 address. */ Ed25519 = 0, + /** An Alias address. */ Alias = 8, + /** An NFT address. */ Nft = 16, } +/** + * The base class for addresses. + */ abstract class Address { readonly type: AddressType; + /** + * @param type The type of the address. + */ constructor(type: AddressType) { this.type = type; } /** - * The type of address. + * Get the type of address. */ getType(): AddressType { return this.type; @@ -26,6 +38,9 @@ abstract class Address { abstract toString(): string; + /** + * Parse an address from a JSON string. + */ public static parse(data: any): Address { if (data.type == AddressType.Ed25519) { return plainToInstance( @@ -41,17 +56,20 @@ abstract class Address { } } /** - * Ed25519 Address. + * An Ed25519 Address. */ class Ed25519Address extends Address { readonly pubKeyHash: HexEncodedString; + /** + * @param address An Ed25519 address as hex-encoded string. + */ constructor(address: HexEncodedString) { super(AddressType.Ed25519); this.pubKeyHash = address; } /** - * The public key hash. + * Get the public key hash. */ getPubKeyHash(): HexEncodedString { return this.pubKeyHash; @@ -62,14 +80,20 @@ class Ed25519Address extends Address { } } +/** + * An Alias address. + */ class AliasAddress extends Address { readonly aliasId: AliasId; + /** + * @param address An Alias address as Alias ID. + */ constructor(address: AliasId) { super(AddressType.Alias); this.aliasId = address; } /** - * The alias id. + * Get the alias ID. */ getAliasId(): AliasId { return this.aliasId; @@ -80,16 +104,19 @@ class AliasAddress extends Address { } } /** - * NFT address. + * An NFT address. */ class NftAddress extends Address { readonly nftId: NftId; + /** + * @param address An NFT address as NFT ID. + */ constructor(address: NftId) { super(AddressType.Nft); this.nftId = address; } /** - * The NFT Id. + * Get the NFT ID. */ getNftId(): NftId { return this.nftId; diff --git a/bindings/nodejs/lib/types/block/id.ts b/bindings/nodejs/lib/types/block/id.ts index 019c491ec4..61a7212d40 100644 --- a/bindings/nodejs/lib/types/block/id.ts +++ b/bindings/nodejs/lib/types/block/id.ts @@ -3,12 +3,27 @@ import { HexEncodedString } from '../utils'; +/** + * An Alias ID represented as hex-encoded string. + */ export type AliasId = HexEncodedString; +/** + * An NFT ID represented as hex-encoded string. + */ export type NftId = HexEncodedString; +/** + * A Block ID represented as hex-encoded string. + */ export type BlockId = HexEncodedString; +/** + * A Token ID represented as hex-encoded string. + */ export type TokenId = HexEncodedString; +/** + * A Foundry ID represented as hex-encoded string. + */ export type FoundryId = HexEncodedString; diff --git a/bindings/nodejs/lib/types/block/input/input.ts b/bindings/nodejs/lib/types/block/input/input.ts index 59cd37077a..a71cd72c0a 100644 --- a/bindings/nodejs/lib/types/block/input/input.ts +++ b/bindings/nodejs/lib/types/block/input/input.ts @@ -5,22 +5,30 @@ import { HexEncodedString } from '../../utils'; import { OutputId } from '../output'; /** - * All of the input types. + * All of the transaction input types. */ enum InputType { + /** A UTXO input. */ UTXO = 0, + /** The treasury input. */ Treasury = 1, } +/** + * The base class for transaction inputs. + */ abstract class Input { readonly type: InputType; + /** + * @param type The type of input. + */ constructor(type: InputType) { this.type = type; } /** - * The type of input. + * Get the type of input. */ getType(): InputType { return this.type; @@ -28,7 +36,7 @@ abstract class Input { } /** - * Treasury Input. + * A Treasury input. */ class TreasuryInput extends Input { /** @@ -36,6 +44,9 @@ class TreasuryInput extends Input { */ milestoneId: HexEncodedString; + /** + * @param milestoneId The milestone id of the input. + */ constructor(milestoneId: HexEncodedString) { super(InputType.Treasury); this.milestoneId = milestoneId; @@ -43,11 +54,11 @@ class TreasuryInput extends Input { } /** - * UTXO Transaction Input. + * A UTXO transaction input. */ class UTXOInput extends Input { /** - * The transaction Id. + * The transaction ID. */ transactionId: HexEncodedString; /** @@ -55,6 +66,10 @@ class UTXOInput extends Input { */ transactionOutputIndex: number; + /** + * @param transactionId The ID of the transaction it is an input of. + * @param transactionOutputIndex The index of the input within the transaction. + */ constructor( transactionId: HexEncodedString, transactionOutputIndex: number, @@ -65,7 +80,7 @@ class UTXOInput extends Input { } /** - * Creates a `UTXOInput` from an output id. + * Create a `UTXOInput` from a given output ID. */ // eslint-disable-next-line @typescript-eslint/no-unused-vars static fromOutputId(outputId: OutputId): UTXOInput { diff --git a/bindings/nodejs/lib/types/block/output/feature.ts b/bindings/nodejs/lib/types/block/output/feature.ts index 41a042b82f..45c36c3474 100644 --- a/bindings/nodejs/lib/types/block/output/feature.ts +++ b/bindings/nodejs/lib/types/block/output/feature.ts @@ -8,27 +8,35 @@ import { Address, AddressDiscriminator } from '../address'; * All of the feature block types. */ enum FeatureType { + /** A Sender feature. */ Sender = 0, + /** An Issuer feature. */ Issuer = 1, + /** A Metadata feature. */ Metadata = 2, + /** A Tag feature. */ Tag = 3, } +/** The base class for features. */ abstract class Feature { readonly type: FeatureType; + /** + * @param type The type of feature. + */ constructor(type: FeatureType) { this.type = type; } /** - * The type of feature. + * Get the type of feature. */ getType(): FeatureType { return this.type; } } /** - * Sender feature. + * A Sender feature. */ class SenderFeature extends Feature { @Type(() => Address, { @@ -36,19 +44,22 @@ class SenderFeature extends Feature { }) readonly address: Address; + /** + * @param sender The Sender address stored with the feature. + */ constructor(sender: Address) { super(FeatureType.Sender); this.address = sender; } /** - * The address. + * Get the sender address. */ getSender(): Address { return this.address; } } /** - * Issuer feature. + * An Issuer feature. */ class IssuerFeature extends Feature { @Type(() => Address, { @@ -56,51 +67,63 @@ class IssuerFeature extends Feature { }) readonly address: Address; + /** + * @param issuer The Issuer address stored with the feature. + */ constructor(issuer: Address) { super(FeatureType.Issuer); this.address = issuer; } /** - * The address. + * Get the Issuer address. */ getIssuer(): Address { return this.address; } } /** - * Metadata feature. + * A Metadata feature. */ class MetadataFeature extends Feature { + /** Defines metadata (arbitrary binary data) that will be stored in the output. */ readonly data: string; + /** + * @param data The metadata stored with the feature. + */ constructor(data: string) { super(FeatureType.Metadata); this.data = data; } /** - * Defines metadata (arbitrary binary data) that will be stored in the output. + * Get the metadata. */ getData(): string { return this.data; } } /** - * Tag feature. + * A Tag feature. */ class TagFeature extends Feature { + /** Defines a tag for the data. */ readonly tag: string; + /** + * @param tag The tag stored with the feature. + */ constructor(tag: string) { super(FeatureType.Tag); this.tag = tag; } /** - * Defines a tag for the data. + * Get the tag. */ getTag(): string { return this.tag; } } + const FeatureDiscriminator = { property: 'type', subTypes: [ @@ -110,6 +133,7 @@ const FeatureDiscriminator = { { value: TagFeature, name: FeatureType.Tag as any }, ], }; + export { FeatureDiscriminator, Feature, diff --git a/bindings/nodejs/lib/types/block/output/output.ts b/bindings/nodejs/lib/types/block/output/output.ts index b7ba62f3cc..ccda08b337 100644 --- a/bindings/nodejs/lib/types/block/output/output.ts +++ b/bindings/nodejs/lib/types/block/output/output.ts @@ -19,18 +19,30 @@ export type OutputId = string; * All of the output types. */ enum OutputType { + /** A Treasury output. */ Treasury = 2, + /** A Basic output. */ Basic = 3, + /** An Alias output. */ Alias = 4, + /** A Foundry output. */ Foundry = 5, + /** An NFT output. */ Nft = 6, } +/** + * The base class for outputs. + */ abstract class Output /*implements ICommonOutput*/ { readonly amount: string; readonly type: OutputType; + /** + * @param type The type of output. + * @param amount The amount of the output as big-integer or string. + */ constructor(type: OutputType, amount: bigint | string) { this.type = type; if (typeof amount == 'bigint') { @@ -41,19 +53,22 @@ abstract class Output /*implements ICommonOutput*/ { } /** - * The type of output. + * Get the type of output. */ getType(): OutputType { return this.type; } /** - * The amount of the output. + * Get the amount of the output. */ getAmount(): bigint { return BigInt(this.amount); } + /** + * Parse an output from a plain JS JSON object. + */ public static parse(data: any): Output { if (data.type == OutputType.Treasury) { return plainToInstance( @@ -74,7 +89,7 @@ abstract class Output /*implements ICommonOutput*/ { } /** - * Common output properties. + * The base class for common outputs. */ abstract class CommonOutput extends Output /*implements ICommonOutput*/ { @Type(() => UnlockCondition, { @@ -89,6 +104,11 @@ abstract class CommonOutput extends Output /*implements ICommonOutput*/ { }) readonly features?: Feature[]; + /** + * @param type The type of output. + * @param amount The amount of the output. + * @param unlockConditions Conditions to unlock the output. + */ constructor( type: OutputType, amount: bigint, @@ -122,35 +142,50 @@ abstract class CommonOutput extends Output /*implements ICommonOutput*/ { } /** - * Features contained by the output. + * Get the features contained by the output. */ getFeatures(): Feature[] | undefined { return this.features; } } /** - * Treasury Output. + * A Treasury output. */ class TreasuryOutput extends Output /*implements ITreasuryOutput */ { + /** + * @param amount The amount of the output. + */ constructor(amount: bigint) { super(OutputType.Treasury, amount); } } /** - * Basic output. + * A Basic output. */ class BasicOutput extends CommonOutput /*implements IBasicOutput*/ { + /** + * @param amount The amount of the output. + * @param unlockConditions The unlock conditions for the output. + */ constructor(amount: bigint, unlockConditions: UnlockCondition[]) { super(OutputType.Basic, amount, unlockConditions); } } +/** + * Base class for immutable feature outputs. + */ abstract class ImmutableFeaturesOutput extends CommonOutput { @Type(() => Feature, { discriminator: FeatureDiscriminator, }) readonly immutableFeatures?: Feature[]; + /** + * @param type The type of output. + * @param amount The amount of the output. + * @param unlockConditions The unlock conditions for the output. + */ constructor( type: OutputType, amount: bigint, @@ -166,9 +201,17 @@ abstract class ImmutableFeaturesOutput extends CommonOutput { } } +/** + * Base class for state metadata outputs. + */ abstract class StateMetadataOutput extends ImmutableFeaturesOutput /*implements IBasicOutput*/ { readonly stateMetadata?: HexEncodedString; + /** + * @param type The type of output. + * @param amount The amount of the output. + * @param unlockConditions The unlock conditions for the output. + */ constructor( type: OutputType, amount: bigint, @@ -184,11 +227,31 @@ abstract class StateMetadataOutput extends ImmutableFeaturesOutput /*implements } } +/** + * An Alias output. + */ class AliasOutput extends StateMetadataOutput /*implements IAliasOutput*/ { + /** + * Unique identifier of the alias, which is the BLAKE2b-256 hash of the Output ID that created it. + * Unless its a newly created alias, then the id is zeroed. + */ readonly aliasId: HexEncodedString; + /** + * A counter that must increase by 1 every time the alias is state transitioned. + */ readonly stateIndex: number; + /** + * A counter that denotes the number of foundries created by this alias account. + */ readonly foundryCounter: number; + /** + * @param unlockConditions The unlock conditions of the output. + * @param amount The amount of the output. + * @param aliasId The Alias ID as hex-encoded string. + * @param stateIndex A counter that must increase by 1 every time the alias is state transitioned. + * @param foundryCounter A counter that denotes the number of foundries created by this alias account. + */ constructor( unlockConditions: UnlockCondition[], amount: bigint, @@ -202,31 +265,39 @@ class AliasOutput extends StateMetadataOutput /*implements IAliasOutput*/ { this.foundryCounter = foundryCounter; } /** - * Unique identifier of the alias, which is the BLAKE2b-160 hash of the Output ID that created it. - * Unless its a newly created alias, then the id is zeroed. + * Get the Alias ID of the output. */ getAliasId(): HexEncodedString { return this.aliasId; } /** - * A counter that must increase by 1 every time the alias is state transitioned. + * Get the state index of the output. */ getStateIndex(): number { return this.stateIndex; } /** - * A counter that denotes the number of foundries created by this alias account. + * Get the Foundry counter of the output. */ getFoundryCounter(): number { return this.foundryCounter; } } /** - * NFT output. + * An NFT output. */ class NftOutput extends ImmutableFeaturesOutput /*implements INftOutput*/ { + /** + * Unique identifier of the NFT, which is the BLAKE2b-256 hash of the Output ID that created it. + * Unless its newly minted, then the id is zeroed. + */ readonly nftId: HexEncodedString; + /** + * @param amount The amount of the output. + * @param nftId The NFT ID as hex-encoded string. + * @param unlockConditions The unlock conditions of the output. + */ constructor( amount: bigint, nftId: HexEncodedString, @@ -236,24 +307,35 @@ class NftOutput extends ImmutableFeaturesOutput /*implements INftOutput*/ { this.nftId = nftId; } /** - * Unique identifier of the NFT, which is the BLAKE2b-160 hash of the Output ID that created it. - * Unless its newly minted, then the id is zeroed. + * Get the NFT ID of the output. */ getNftId(): HexEncodedString { return this.nftId; } } /** - * Foundry output. + * A Foundry output. */ class FoundryOutput extends ImmutableFeaturesOutput /*implements IFoundryOutput*/ { + /** + * The serial number of the Foundry with respect to the controlling alias. + */ readonly serialNumber: number; + /** + * The token scheme for the Foundry. + */ @Type(() => TokenScheme, { discriminator: TokenSchemeDiscriminator, }) readonly tokenScheme: TokenScheme; + /** + * @param amount The amount of the output. + * @param serialNumber The serial number of the Foundry with respect to the controlling alias. + * @param unlockConditions The unlock conditions of the output. + * @param tokenScheme The token scheme for the Foundry. + */ constructor( amount: bigint, serialNumber: number, @@ -265,13 +347,13 @@ class FoundryOutput extends ImmutableFeaturesOutput /*implements IFoundryOutput* this.tokenScheme = tokenScheme; } /** - * The serial number of the foundry with respect to the controlling alias. + * Get the serial number of the Foundry. */ getSerialNumber(): number { return this.serialNumber; } /** - * The token scheme for the foundry. + * Get the token scheme for the Foundry. */ getTokenScheme(): TokenScheme { return this.tokenScheme; diff --git a/bindings/nodejs/lib/types/block/output/token-scheme.ts b/bindings/nodejs/lib/types/block/output/token-scheme.ts index 0602ab43a2..6a26bf3147 100644 --- a/bindings/nodejs/lib/types/block/output/token-scheme.ts +++ b/bindings/nodejs/lib/types/block/output/token-scheme.ts @@ -3,19 +3,29 @@ import { hexToBigInt } from '../../utils/hex-encoding'; +/** + * All of the token scheme types. + */ enum TokenSchemeType { + /** A simple token scheme. */ Simple = 0, } +/** + * The base class for token schemes. + */ abstract class TokenScheme { readonly type: TokenSchemeType; + /** + * @param type The type of token scheme. + */ constructor(type: TokenSchemeType) { this.type = type; } /** - * The type of token scheme. + * Get the type of token scheme. */ getType(): TokenSchemeType { return this.type; @@ -23,13 +33,18 @@ abstract class TokenScheme { } /** - * Simple token scheme. + * A simple token scheme. */ class SimpleTokenScheme extends TokenScheme { readonly mintedTokens: bigint; readonly meltedTokens: bigint; readonly maximumSupply: bigint; + /** + * @param mintedTokens The number of tokens that were minted. + * @param meltedTokens The number of tokens that were melted. + * @param maximumSupply The maximum supply of the token. + */ constructor( mintedTokens: bigint, meltedTokens: bigint, @@ -62,21 +77,21 @@ class SimpleTokenScheme extends TokenScheme { } /** - * Amount of tokens minted. + * Get the amount of tokens minted. */ getMintedTokens(): bigint { return this.mintedTokens; } /** - * Amount of tokens melted. + * Get the amount of tokens melted. */ getMeltedTokens(): bigint { return this.meltedTokens; } /** - * Maximum supply of tokens controlled. + * Get the maximum supply of tokens. */ getMaximumSupply(): bigint { return this.maximumSupply; diff --git a/bindings/nodejs/lib/types/block/output/unlock-condition.ts b/bindings/nodejs/lib/types/block/output/unlock-condition.ts index d6595e070e..00dc88a3ff 100644 --- a/bindings/nodejs/lib/types/block/output/unlock-condition.ts +++ b/bindings/nodejs/lib/types/block/output/unlock-condition.ts @@ -8,28 +8,41 @@ import { Address, AddressDiscriminator, AliasAddress } from '../address'; * All of the unlock condition types. */ enum UnlockConditionType { + /** An address unlock condition. */ Address = 0, + /** A storage deposit return unlock condition. */ StorageDepositReturn = 1, + /** A timelock unlock condition. */ Timelock = 2, + /** An expiration unlock condition. */ Expiration = 3, + /** A state controller address unlock condition. */ StateControllerAddress = 4, + /** A governor address unlock condition. */ GovernorAddress = 5, + /** An immutable alias address unlock condition. */ ImmutableAliasAddress = 6, } abstract class UnlockCondition { readonly type: UnlockConditionType; + /** + * @param type The type of the unlock condition. + */ constructor(type: UnlockConditionType) { this.type = type; } /** - * The type of unlock condition. + * Get the type of unlock condition. */ getType(): UnlockConditionType { return this.type; } + /** + * Parse an unlock condition from a plain JS JSON object. + */ public static parse(data: any): UnlockCondition { if (data.type == UnlockConditionType.Address) { return plainToInstance( @@ -71,35 +84,54 @@ abstract class UnlockCondition { } } +/** + * An address unlock condition. + */ class AddressUnlockCondition extends UnlockCondition /*implements IAddressUnlockCondition*/ { + /** + * An address unlocked with a private key. + */ @Type(() => Address, { discriminator: AddressDiscriminator, }) readonly address: Address; + /** + * @param address The address that needs to be unlocked with a private key. + */ constructor(address: Address) { super(UnlockConditionType.Address); this.address = address; } /** - * The address. + * Get the address. */ getAddress(): Address { return this.address; } } /** - * Storage Deposit Return Unlock Condition. + * A Storage Deposit Return Unlock Condition. */ class StorageDepositReturnUnlockCondition extends UnlockCondition /*implements IStorageDepositReturnUnlockCondition*/ { + /** + * The amount the consuming transaction must deposit to `returnAddress`. + */ readonly amount: string; + /** + * The address to return the amount to. + */ @Type(() => Address, { discriminator: AddressDiscriminator, }) readonly returnAddress: Address; + /** + * @param returnAddress The address to return the amount to. + * @param amount The amount the consuming transaction must deposit to `returnAddress`. + */ constructor(returnAddress: Address, amount: bigint | string) { super(UnlockConditionType.StorageDepositReturn); if (typeof amount == 'bigint') { @@ -110,120 +142,147 @@ class StorageDepositReturnUnlockCondition extends UnlockCondition /*implements I this.returnAddress = returnAddress; } /** - * Amount of tokens the consuming transaction must deposit to the address defined in return address. + * Get the amount. */ getAmount(): bigint { return BigInt(this.amount); } /** - * The return address. + * Get the return address. */ getReturnAddress(): Address { return this.returnAddress; } } /** - * Timelock Unlock Condition. + * A Timelock Unlock Condition. */ class TimelockUnlockCondition extends UnlockCondition /*implements ITimelockUnlockCondition*/ { + /** + * The Unix time (seconds since Unix epoch) starting from which the output can be consumed. + */ readonly unixTime: number; + /** + * @param unixTime The Unix timestamp marking the end of the timelock. + */ constructor(unixTime: number) { super(UnlockConditionType.Timelock); this.unixTime = unixTime; } /** - * Unix time (seconds since Unix epoch) starting from which the output can be consumed. + * Get the end of the timelock as Unix time. */ getUnixTime(): number { return this.unixTime; } } +/** + * An Expiration Unlock Condition. + */ class ExpirationUnlockCondition extends UnlockCondition /*implements IExpirationUnlockCondition*/ { + /** + * The return address if the output was not claimed in time. + */ @Type(() => Address, { discriminator: AddressDiscriminator, }) readonly returnAddress: Address; + /** + * Before this timestamp, the condition is allowed to unlock the output, + * after that only the address defined in return address. + */ readonly unixTime: number; + /** + * @param returnAddress The address that can unlock the expired output. + * @param unixTime The Unix timestamp marking the end of the claim period. + */ constructor(returnAddress: Address, unixTime: number) { super(UnlockConditionType.Expiration); this.returnAddress = returnAddress; this.unixTime = unixTime; } /** - * Before this unix time, the condition is allowed to unlock the output, - * after that only the address defined in return address. + * Get the end of the expiration period as Unix time. */ getUnixTime(): number { return this.unixTime; } /** - * The return address. + * Get the return address. */ getReturnAddress(): Address { return this.returnAddress; } } /** - * State Controller Address Unlock Condition. + * A State Controller Address Unlock Condition. */ class StateControllerAddressUnlockCondition extends UnlockCondition /*implements IStateControllerAddressUnlockCondition*/ { @Type(() => Address, { discriminator: AddressDiscriminator, }) readonly address: Address; + /** + * @param address The State Controller address that is allowed to do state transitions. + */ constructor(address: Address) { super(UnlockConditionType.StateControllerAddress); this.address = address; } /** - * The address. + * Get the State Controller address. */ getAddress(): Address { return this.address; } } /** - * Governor Unlock Condition. + * A Governor Address Unlock Condition. */ class GovernorAddressUnlockCondition extends UnlockCondition /*implements IGovernorAddressUnlockCondition*/ { @Type(() => Address, { discriminator: AddressDiscriminator, }) readonly address: Address; + /** + * @param address The governor address that is allowed to do governance transitions. + */ constructor(address: Address) { super(UnlockConditionType.GovernorAddress); this.address = address; } /** - * The address. + * Get the Governor address. */ getAddress(): Address { return this.address; } } /** - * Immutable Alias Unlock Condition. + * An Immutable Alias Address Unlock Condition. */ class ImmutableAliasAddressUnlockCondition extends UnlockCondition /*implements IImmutableAliasAddressUnlockCondition*/ { @Type(() => Address, { discriminator: AddressDiscriminator, }) readonly address: Address; - + /** + * @param address The Immutable Alias address that owns the output. + */ constructor(address: AliasAddress) { super(UnlockConditionType.ImmutableAliasAddress); this.address = address; } /** - * The address. + * Get the Immutable Alias address. */ getAddress(): Address { return this.address; diff --git a/bindings/nodejs/lib/types/block/payload/milestone/milestone.ts b/bindings/nodejs/lib/types/block/payload/milestone/milestone.ts index a0aa56e140..65f02a007b 100644 --- a/bindings/nodejs/lib/types/block/payload/milestone/milestone.ts +++ b/bindings/nodejs/lib/types/block/payload/milestone/milestone.ts @@ -10,6 +10,9 @@ import { HexEncodedString } from '../../../utils/hex-encoding'; import { Ed25519Signature } from '../../signature'; import { Payload, PayloadType } from '../payload'; +/** + * A milestone payload. + */ class MilestonePayload extends Payload { /** * The index name. diff --git a/bindings/nodejs/lib/types/block/payload/payload.ts b/bindings/nodejs/lib/types/block/payload/payload.ts index f498600e47..3203c52570 100644 --- a/bindings/nodejs/lib/types/block/payload/payload.ts +++ b/bindings/nodejs/lib/types/block/payload/payload.ts @@ -2,28 +2,34 @@ // SPDX-License-Identifier: Apache-2.0 /** - * All of the payload types. + * All of the block payload types. */ enum PayloadType { - /// A milestone payload. + /** A milestone payload. */ Milestone = 7, - /// A tagged data payload. + /** A tagged data payload. */ TaggedData = 5, - /// A transaction payload. + /** A transaction payload. */ Transaction = 6, - /// A treasury transaction payload. + /** A treasury transaction payload. */ TreasuryTransaction = 4, } +/** + * The base class for block payloads. + */ abstract class Payload { readonly type: PayloadType; + /** + * @param type The type of payload. + */ constructor(type: PayloadType) { this.type = type; } /** - * The type of payload. + * Get the type of payload. */ getType(): PayloadType { return this.type; diff --git a/bindings/nodejs/lib/types/block/payload/tagged/tagged.ts b/bindings/nodejs/lib/types/block/payload/tagged/tagged.ts index 62ca79986c..c698504671 100644 --- a/bindings/nodejs/lib/types/block/payload/tagged/tagged.ts +++ b/bindings/nodejs/lib/types/block/payload/tagged/tagged.ts @@ -5,7 +5,7 @@ import { HexEncodedString } from '../../../utils/hex-encoding'; import { Payload, PayloadType } from '../payload'; /** - * Tagged data payload. + * A Tagged Data payload. */ class TaggedDataPayload extends Payload { /** @@ -16,6 +16,10 @@ class TaggedDataPayload extends Payload { * The index data. */ data: HexEncodedString; + /** + * @param tag A tag as hex-encoded string. + * @param data Index data as hex-encoded string. + */ constructor(tag: HexEncodedString, data: HexEncodedString) { super(PayloadType.TaggedData); this.tag = tag; diff --git a/bindings/nodejs/lib/types/block/payload/transaction/essence.ts b/bindings/nodejs/lib/types/block/payload/transaction/essence.ts index 66fe8b00d2..c17b409652 100644 --- a/bindings/nodejs/lib/types/block/payload/transaction/essence.ts +++ b/bindings/nodejs/lib/types/block/payload/transaction/essence.ts @@ -12,18 +12,27 @@ import { Payload } from '../payload'; * All of the essence types. */ enum TransactionEssenceType { + /** + * A regular transaction essence. + */ Regular = 1, } +/** + * The base class for transaction essences. + */ abstract class TransactionEssence { readonly type: TransactionEssenceType; + /** + * @param type The type of transaction essence. + */ constructor(type: TransactionEssenceType) { this.type = type; } /** - * The type of essence. + * Get the type of essence. */ getType(): TransactionEssenceType { return this.type; @@ -53,6 +62,14 @@ class RegularTransactionEssence extends TransactionEssence { }) payload: Payload | undefined; + /** + * @param networkId The ID of the network the transaction was issued to. + * @param inputsCommitment The hash of all inputs. + * @param inputs The inputs of the transaction. + * @param outputs The outputs of the transaction. + * @param payload An optional Tagged Data payload. + * + */ constructor( networkId: number, inputsCommitment: HexEncodedString, diff --git a/bindings/nodejs/lib/types/block/payload/transaction/transaction.ts b/bindings/nodejs/lib/types/block/payload/transaction/transaction.ts index 01ae62af7d..867e304287 100644 --- a/bindings/nodejs/lib/types/block/payload/transaction/transaction.ts +++ b/bindings/nodejs/lib/types/block/payload/transaction/transaction.ts @@ -29,6 +29,10 @@ class TransactionPayload extends Payload { }) unlocks: Unlock[]; + /** + * @param essence The transaction essence. + * @param unlocks The unlocks of the transaction. + */ constructor(essence: TransactionEssence, unlocks: Unlock[]) { super(PayloadType.Transaction); this.essence = essence; diff --git a/bindings/nodejs/lib/types/block/payload/transaction/unlock.ts b/bindings/nodejs/lib/types/block/payload/transaction/unlock.ts index 45b7f0f2ce..41bd290656 100644 --- a/bindings/nodejs/lib/types/block/payload/transaction/unlock.ts +++ b/bindings/nodejs/lib/types/block/payload/transaction/unlock.ts @@ -8,21 +8,39 @@ import { Ed25519Signature } from '../../signature'; * All of the unlock types. */ enum UnlockType { + /** + * A signature unlock. + */ Signature = 0, + /** + * A reference unlock. + */ Reference = 1, + /** + * An Alias unlock. + */ Alias = 2, + /** + * An NFT unlock. + */ Nft = 3, } +/** + * The base class for unlocks. + */ abstract class Unlock { readonly type: UnlockType; + /** + * @param type The type of unlock. + */ constructor(type: UnlockType) { this.type = type; } /** - * The type of unlock. + * Get the type of unlock. */ getType(): UnlockType { return this.type; @@ -39,6 +57,9 @@ class SignatureUnlock extends Unlock { @Type(() => Ed25519Signature) signature: Ed25519Signature; + /** + * @param signature An Ed25519 signature. + */ constructor(signature: Ed25519Signature) { super(UnlockType.Signature); this.signature = signature; @@ -55,6 +76,9 @@ class ReferenceUnlock extends Unlock { */ reference: number; + /** + * @param reference An index referencing a previous unlock. + */ constructor(reference: number) { super(UnlockType.Reference); this.reference = reference; @@ -70,6 +94,9 @@ class AliasUnlock extends Unlock { */ reference: number; + /** + * @param reference An index referencing a previous unlock. + */ constructor(reference: number) { super(UnlockType.Alias); this.reference = reference; @@ -85,6 +112,9 @@ class NftUnlock extends Unlock { */ reference: number; + /** + * @param reference An index referencing a previous unlock. + */ constructor(reference: number) { super(UnlockType.Nft); this.reference = reference; diff --git a/bindings/nodejs/lib/types/block/payload/treasury/treasury.ts b/bindings/nodejs/lib/types/block/payload/treasury/treasury.ts index b2d9edd81c..250b07a9bd 100644 --- a/bindings/nodejs/lib/types/block/payload/treasury/treasury.ts +++ b/bindings/nodejs/lib/types/block/payload/treasury/treasury.ts @@ -4,7 +4,7 @@ import { TreasuryOutput } from '../../output'; import { Payload, PayloadType } from '../payload'; /** - * Receipt payload. + * A treasury transaction payload. */ class TreasuryTransactionPayload extends Payload { /** @@ -18,6 +18,10 @@ class TreasuryTransactionPayload extends Payload { @Type(() => TreasuryOutput) output: TreasuryOutput; + /** + * @param input A Treasury input. + * @param output A Treasury output. + */ constructor(input: TreasuryInput, output: TreasuryOutput) { super(PayloadType.Transaction); this.input = input; diff --git a/bindings/nodejs/lib/types/block/signature.ts b/bindings/nodejs/lib/types/block/signature.ts index bf7c811eaa..542e4eee3d 100644 --- a/bindings/nodejs/lib/types/block/signature.ts +++ b/bindings/nodejs/lib/types/block/signature.ts @@ -8,18 +8,27 @@ import { HexEncodedString } from '../utils'; * All of the signature types. */ enum SignatureType { + /** + * An Ed25519 signature. + */ Ed25519 = 0, } +/** + * The base class for signatures. + */ abstract class Signature { readonly type: SignatureType; + /** + * @param type The type of signature. + */ constructor(type: SignatureType) { this.type = type; } /** - * The type of signature. + * Get the type of signature. */ getType(): SignatureType { return this.type; @@ -27,7 +36,7 @@ abstract class Signature { } /** - * Ed25519Signature signature. + * An Ed25519 signature. */ class Ed25519Signature extends Signature { /** @@ -39,6 +48,10 @@ class Ed25519Signature extends Signature { */ signature: HexEncodedString; + /** + * @param publicKey A Ed25519 public key as hex-encoded string. + * @param signature A Ed25519 signature as hex-encoded string. + */ constructor(publicKey: HexEncodedString, signature: HexEncodedString) { super(SignatureType.Ed25519); this.publicKey = publicKey; diff --git a/bindings/nodejs/lib/types/client/build-block-options.ts b/bindings/nodejs/lib/types/client/build-block-options.ts index 6440613384..2bf8c5ba3e 100644 --- a/bindings/nodejs/lib/types/client/build-block-options.ts +++ b/bindings/nodejs/lib/types/client/build-block-options.ts @@ -7,29 +7,42 @@ import type { Burn } from './burn'; import { UTXOInput } from '../block/input'; import { Output } from '../block/output'; -/** Options to build a new block, possibly with payloads */ +/** + * Options to build a new block, possibly with payloads. + */ export interface IBuildBlockOptions { + /** A coin type. */ coinType?: CoinType; + /** An account index. */ accountIndex?: number; + /** An initial address index. */ initialAddressIndex?: number; + /** A list of inputs. */ inputs?: UTXOInput[]; + /** An input range. */ inputRange?: IRange; - /** Bech32 encoded output address and amount */ + /** Bech32 encoded output address and amount. */ output?: IClientBlockBuilderOutputAddress; - /** Hex encoded output address and amount */ + /** Hex encoded output address and amount. */ outputHex?: IClientBlockBuilderOutputAddress; + /** A list of outputs. */ outputs?: Output[]; + /** A custom remainder address. */ customRemainderAddress?: string; + /** A tag. */ tag?: string; + /** Some metadata. */ data?: string; - /** Parent block IDs */ + /** Some parent block IDs. */ parents?: string[]; - /** Explicit burning of aliases, nfts, foundries and native tokens */ + /** Parameters for explicit burning of aliases, nfts, foundries and native tokens. */ burn?: Burn; } -/** Address with base coin amount */ +/** Address with base coin amount. */ export interface IClientBlockBuilderOutputAddress { + /** An address. */ address: string; + /** Some base coin amount. */ amount: bigint | string; } diff --git a/bindings/nodejs/lib/types/client/client-options.ts b/bindings/nodejs/lib/types/client/client-options.ts index 4ba44ff0be..9036e532cd 100644 --- a/bindings/nodejs/lib/types/client/client-options.ts +++ b/bindings/nodejs/lib/types/client/client-options.ts @@ -8,7 +8,9 @@ export interface IClientOptions { primaryNode?: string | INode; /** Node which will be tried first when using remote PoW, even before the primary_node */ primaryPowNode?: string | INode; + /** A list of nodes. */ nodes?: Array; + /** A list of permanodes. */ permanodes?: Array; /** If the node health status should be ignored */ ignoreNodeHealth?: boolean; @@ -38,6 +40,8 @@ export interface IClientOptions { /** Time duration */ export interface IDuration { + /** Seconds. */ secs: number; + /** Nanoseconds. */ nanos: number; } diff --git a/bindings/nodejs/lib/types/client/constants.ts b/bindings/nodejs/lib/types/client/constants.ts index ea080f7f1f..754c7f2e00 100644 --- a/bindings/nodejs/lib/types/client/constants.ts +++ b/bindings/nodejs/lib/types/client/constants.ts @@ -7,7 +7,10 @@ export const SHIMMER_TESTNET_BECH32_HRP = 'rms'; /** BIP44 Coin Types for IOTA and Shimmer. */ export enum CoinType { + /** The IOTA coin. */ IOTA = 4218, + /** The Shimmer coin. */ Shimmer = 4219, + /** The Ether coin. */ Ether = 60, } diff --git a/bindings/nodejs/lib/types/client/ledger-nano-status.ts b/bindings/nodejs/lib/types/client/ledger-nano-status.ts index 86197e54fd..c252e9fecc 100644 --- a/bindings/nodejs/lib/types/client/ledger-nano-status.ts +++ b/bindings/nodejs/lib/types/client/ledger-nano-status.ts @@ -1,22 +1,33 @@ /** The status of a Ledger Nano */ export interface LedgerNanoStatus { + /** Ledger is available and ready to be used. */ connected: boolean; + /** Ledger is connected and locked, true/false for IOTA/Shimmer, undefined for the rest. */ locked?: boolean; + /** Ledger blind signing enabled */ blindSigningEnabled: boolean; + /** Ledger opened app. */ app?: LedgerApp; + /** Ledger device */ device?: LedgerDeviceType; + /** Buffer size on device */ bufferSize?: number; } /** The current opened app */ export interface LedgerApp { + /** Opened app name. */ name: string; + /** Opened app version. */ version: string; } /** The Ledger Device Type */ export enum LedgerDeviceType { + /** Device Type Nano S */ LedgerNanoS = 'ledgerNanoS', + /** Device Type Nano X */ LedgerNanoX = 'ledgerNanoX', + /** Device Type Nano S Plus */ LedgerNanoSPlus = 'ledgerNanoSPlus', } diff --git a/bindings/nodejs/lib/types/client/network.ts b/bindings/nodejs/lib/types/client/network.ts index 4e51aedcc6..f57c024479 100644 --- a/bindings/nodejs/lib/types/client/network.ts +++ b/bindings/nodejs/lib/types/client/network.ts @@ -7,7 +7,9 @@ import { INodeInfoProtocol } from '../models/info'; * Network types. */ export enum Network { + /** The mainnet. */ Mainnet, + /** The testnet */ Testnet, } @@ -15,7 +17,9 @@ export enum Network { * Basic Auth or JWT. */ export interface IAuth { + /** JWT authentication parameters. */ jwt?: string; + /** Basic authentication parameters. */ basicAuthNamePwd?: [string, string]; } @@ -23,11 +27,15 @@ export interface IAuth { * Options for the MQTT broker. */ export interface IMqttBrokerOptions { + /** Whether the MQTT broker should be automatically disconnected when all topics are unsubscribed or not. */ automaticDisconnect?: boolean; - /** timeout in seconds */ + /** Sets the timeout in seconds used for the MQTT operations. */ timeout?: number; + /** Sets whether websockets should be used instead of regular TCP for the MQTT operations. */ useWs?: boolean; + /** Sets the port used for the MQTT operations. */ port?: number; + /** Sets the maximum number of reconnection attempts. 0 is unlimited. */ maxReconnectionAttempts?: number; } @@ -35,8 +43,11 @@ export interface IMqttBrokerOptions { * A node object for the client. */ export interface INode { + /** The URL of the node. */ url: string; + /** The authentication parameters. */ auth?: IAuth; + /** Whether the node is disabled or not. */ disabled?: boolean; } diff --git a/bindings/nodejs/lib/types/client/output_builder_params/alias-output-params.ts b/bindings/nodejs/lib/types/client/output_builder_params/alias-output-params.ts index 1346f43a9b..1bcc627839 100644 --- a/bindings/nodejs/lib/types/client/output_builder_params/alias-output-params.ts +++ b/bindings/nodejs/lib/types/client/output_builder_params/alias-output-params.ts @@ -4,12 +4,27 @@ import { Feature, HexEncodedString } from '../..'; import type { BasicOutputBuilderParams } from './basic-output-params'; /** - * Options for building an Alias Output + * Options for building an Alias Output. */ export interface AliasOutputBuilderParams extends BasicOutputBuilderParams { + /** + * Unique identifier of an alias, which is the BLAKE2b-256 hash of the Output ID that created it. + */ aliasId: HexEncodedString; + /** + * A counter that must increase by 1 every time the alias is state transitioned. + */ stateIndex?: number; + /** + * Metadata that can only be changed by the state controller. + */ stateMetadata?: HexEncodedString; + /** + * A counter that denotes the number of foundries created by this alias account. + */ foundryCounter?: number; + /** + * A list of immutable features. + */ immutableFeatures?: Feature[]; } diff --git a/bindings/nodejs/lib/types/client/output_builder_params/foundry-output-params.ts b/bindings/nodejs/lib/types/client/output_builder_params/foundry-output-params.ts index d8d42ab4bd..52f3508f09 100644 --- a/bindings/nodejs/lib/types/client/output_builder_params/foundry-output-params.ts +++ b/bindings/nodejs/lib/types/client/output_builder_params/foundry-output-params.ts @@ -4,13 +4,21 @@ import { Feature, SimpleTokenScheme } from '../..'; import type { BasicOutputBuilderParams } from './basic-output-params'; /** - * Options for building a Foundry Output + * Options for building a Foundry Output. */ export interface FoundryOutputBuilderParams extends BasicOutputBuilderParams { /** * The serial number of the foundry with respect to the controlling alias. */ serialNumber: number; + /** + * Defines the supply control scheme of the tokens controlled by the foundry. + * Currently only a simple scheme is supported. + */ tokenScheme: SimpleTokenScheme; + /** + * Features that add utility to the output but do not impose unlocking conditions. + * These features need to be kept in future transitions of the UTXO state machine. + */ immutableFeatures?: Feature[]; } diff --git a/bindings/nodejs/lib/types/client/output_builder_params/nft-output-params.ts b/bindings/nodejs/lib/types/client/output_builder_params/nft-output-params.ts index e376cf0e5b..a377b0e2bc 100644 --- a/bindings/nodejs/lib/types/client/output_builder_params/nft-output-params.ts +++ b/bindings/nodejs/lib/types/client/output_builder_params/nft-output-params.ts @@ -7,6 +7,13 @@ import type { BasicOutputBuilderParams } from './basic-output-params'; * Options for building an Nft Output */ export interface NftOutputBuilderParams extends BasicOutputBuilderParams { + /** + * Unique identifier of an NFT, which is the BLAKE2b-256 hash of the Output ID that created it. + */ nftId: HexEncodedString; + /** + * Features that add utility to the output but do not impose unlocking conditions. + * These features need to be kept in future transitions of the UTXO state machine. + */ immutableFeatures?: Feature[]; } diff --git a/bindings/nodejs/lib/types/client/prepared-transaction-data.ts b/bindings/nodejs/lib/types/client/prepared-transaction-data.ts index 64dc9354f5..437f2bf6f8 100644 --- a/bindings/nodejs/lib/types/client/prepared-transaction-data.ts +++ b/bindings/nodejs/lib/types/client/prepared-transaction-data.ts @@ -12,7 +12,7 @@ import { IOutputMetadataResponse } from '../models/api'; import { Bip44 } from '../secret_manager'; /** - * Helper struct for offline signing + * Helper struct for offline signing. */ export class PreparedTransactionData { /** @@ -33,7 +33,7 @@ export class PreparedTransactionData { } /** - * Data for transaction inputs for signing and ordering of unlock blocks + * Data for transaction inputs for signing and ordering of unlock blocks. */ export class InputSigningData { /** @@ -53,20 +53,23 @@ export class InputSigningData { chain?: Bip44; } +/** + * Data for a remainder output, used for Ledger Nano. + */ export class Remainder { /** - * The remainder output + * The remainder output. */ @Type(() => Output, { discriminator: OutputDiscriminator, }) output!: Output; /** - * The chain derived from seed, for the remainder addresses + * The chain derived from seed, for the remainder addresses. */ chain?: Bip44; /** - * The remainder address + * The remainder address. */ @Type(() => Address, { discriminator: AddressDiscriminator, diff --git a/bindings/nodejs/lib/types/client/range.ts b/bindings/nodejs/lib/types/client/range.ts index ce7bf078e9..8212a1f866 100644 --- a/bindings/nodejs/lib/types/client/range.ts +++ b/bindings/nodejs/lib/types/client/range.ts @@ -3,6 +3,8 @@ /** A range with start and end values. */ export interface IRange { + /** The start index. */ start: number; + /** The end index. */ end: number; } diff --git a/bindings/nodejs/lib/types/models/milestone_options/milestone-options.ts b/bindings/nodejs/lib/types/models/milestone_options/milestone-options.ts index b094b12683..130832fe88 100644 --- a/bindings/nodejs/lib/types/models/milestone_options/milestone-options.ts +++ b/bindings/nodejs/lib/types/models/milestone_options/milestone-options.ts @@ -5,19 +5,24 @@ * All of the milestone option types. */ enum MilestoneOptionType { + /** The Receipt milestone option. */ Receipt = 0, + /** The ProtocolParams milestone option. */ ProtocolParams = 1, } abstract class MilestoneOption { readonly type: MilestoneOptionType; + /** + * @param type The type of milestone option. + */ constructor(type: MilestoneOptionType) { this.type = type; } /** - * The type of milestone option. + * Get the type of milestone option. */ getType(): MilestoneOptionType { return this.type; diff --git a/bindings/nodejs/lib/types/models/milestone_options/protocol-params-milestone-option.ts b/bindings/nodejs/lib/types/models/milestone_options/protocol-params-milestone-option.ts index 9559037376..d2771d114f 100644 --- a/bindings/nodejs/lib/types/models/milestone_options/protocol-params-milestone-option.ts +++ b/bindings/nodejs/lib/types/models/milestone_options/protocol-params-milestone-option.ts @@ -4,7 +4,7 @@ import { MilestoneOption, MilestoneOptionType } from './milestone-options'; /** - * Protocol Parameters Milestone Option. + * A Protocol Parameters Milestone Option. */ export class ProtocolParamsMilestoneOption extends MilestoneOption { /** @@ -20,6 +20,11 @@ export class ProtocolParamsMilestoneOption extends MilestoneOption { */ params: string; + /** + * @param targetMilestoneIndex The milestone index at which these protocol parameters become active. + * @param protocolVersion The to be applied protocol version. + * @param params The protocol parameters in binary form. Hex-encoded with 0x prefix. + */ constructor( targetMilestoneIndex: number, protocolVersion: number, diff --git a/bindings/nodejs/lib/types/models/milestone_options/receipt-milestone-option.ts b/bindings/nodejs/lib/types/models/milestone_options/receipt-milestone-option.ts index 95928d8e75..7aa5977086 100644 --- a/bindings/nodejs/lib/types/models/milestone_options/receipt-milestone-option.ts +++ b/bindings/nodejs/lib/types/models/milestone_options/receipt-milestone-option.ts @@ -7,7 +7,7 @@ import { MigratedFunds } from '../migrated-funds'; import { MilestoneOption, MilestoneOptionType } from './milestone-options'; /** - * Receipt milestone option. + * A Receipt milestone option. */ export class ReceiptMilestoneOption extends MilestoneOption { /** @@ -19,16 +19,22 @@ export class ReceiptMilestoneOption extends MilestoneOption { */ final: boolean; /** - * The index data. + * The funds which were migrated. */ @Type(() => MigratedFunds) funds: MigratedFunds[]; /** - * The TreasuryTransaction used to fund the funds. + * The Treasury Transaction used to provide the funds. */ @Type(() => TreasuryTransactionPayload) transaction: TreasuryTransactionPayload; + /** + * @param migratedAt The milestone index at which the funds were migrated in the legacy network. + * @param final Whether this Receipt is the final one for a given migrated at index. + * @param funds The funds which were migrated. + * @param transaction The Treasury Transaction used to provide the funds. + */ constructor( migratedAt: number, final: boolean, diff --git a/bindings/nodejs/lib/types/secret_manager/secret-manager.ts b/bindings/nodejs/lib/types/secret_manager/secret-manager.ts index 9f42477673..34c777485a 100644 --- a/bindings/nodejs/lib/types/secret_manager/secret-manager.ts +++ b/bindings/nodejs/lib/types/secret_manager/secret-manager.ts @@ -11,11 +11,13 @@ export interface LedgerNanoSecretManager { /** Secret manager that uses a mnemonic. */ export interface MnemonicSecretManager { + /** The underlying mnemonic. */ mnemonic: string; } /** Secret manager that uses a seed. */ export interface SeedSecretManager { + /** The underlying seed. */ hexSeed: string; } @@ -24,6 +26,7 @@ export type PlaceholderSecretManager = 'placeholder'; /** Secret manager that uses Stronghold. */ export interface StrongholdSecretManager { + /** The underlying Stronghold snapshot. */ stronghold: { password?: string; snapshotPath?: string; @@ -48,9 +51,14 @@ export interface Secp256k1EcdsaSignature { signature: HexEncodedString; } +/** A BIP44 chain. */ export interface Bip44 { + /** The coin type segment. */ coinType?: number; + /** The account segment. */ account?: number; + /** The change segment. */ change?: number; + /** The address index segment. */ addressIndex?: number; } diff --git a/bindings/nodejs/lib/types/wallet/account.ts b/bindings/nodejs/lib/types/wallet/account.ts index f7d1382b24..fa1db3473e 100644 --- a/bindings/nodejs/lib/types/wallet/account.ts +++ b/bindings/nodejs/lib/types/wallet/account.ts @@ -47,17 +47,25 @@ export interface BaseCoinBalance { /** The required storage deposit per output type */ export interface RequiredStorageDeposit { + /** The required amount for Alias outputs. */ alias: bigint; + /** The required amount for Basic outputs. */ basic: bigint; + /** The required amount for Foundry outputs. */ foundry: bigint; + /** The required amount for NFT outputs. */ nft: bigint; } /** The balance of a native token */ export interface NativeTokenBalance { + /** The native token id. */ tokenId: HexEncodedString; + /** Some metadata of the native token. */ metadata?: string; + /** The total native token balance. */ total: bigint; + /** The available amount of the total native token balance. */ available: bigint; } @@ -103,48 +111,67 @@ export interface SyncOptions { /** Specifies what outputs should be synced for the ed25519 addresses from the account. */ export interface AccountSyncOptions { + /** Whether to sync Basic outputs. */ basicOutputs?: boolean; + /** Whether to sync Alias outputs. */ aliasOutputs?: boolean; + /** Whether to sync NFT outputs. */ nftOutputs?: boolean; } /** Specifies what outputs should be synced for the address of an alias output. */ export interface AliasSyncOptions { + /** Whether to sync Basic outputs. */ basicOutputs?: boolean; + /** Whether to sync Alias outputs. */ aliasOutputs?: boolean; + /** Whether to sync NFT outputs. */ nftOutputs?: boolean; + /** Whether to sync foundry outputs. */ foundryOutputs?: boolean; } /** Specifies what outputs should be synced for the address of an nft output. */ export interface NftSyncOptions { + /** Whether to sync Basic outputs. */ basicOutputs?: boolean; + /** Whether to sync Alias outputs. */ aliasOutputs?: boolean; + /** Whether to sync NFT outputs. */ nftOutputs?: boolean; } -/** The account object */ +/** The account object. */ export interface AccountMeta { + /** The account index. */ index: number; + /** The type of coin managed with the account. */ coinType: CoinType; + /** The alias name of the account. */ alias: string; + /** All public addresses. */ publicAddresses: AccountAddress[]; + /** All internal addresses. */ internalAddresses: AccountAddress[]; + /** All addresses with unspent outputs. */ addressesWithUnspentOutputs: AddressWithUnspentOutputs[]; + /** All outputs of the account. */ outputs: { [outputId: string]: OutputData }; - /** Output IDs of unspent outputs that are currently used as input for transactions */ + /** All IDs of unspent outputs that are currently used as inputs for transactions. */ lockedOutputs: Set; + /** All unspent outputs of the account. */ unspentOutputs: { [outputId: string]: OutputData }; + /** All transactions of the account. */ transactions: { [transactionId: string]: Transaction }; - /** Transaction IDs of pending transactions */ + /** All pending transactions of the account. */ pendingTransactions: Set; - /** Incoming transactions with their inputs if available and not already pruned */ + /** All incoming transactions of the account (with their inputs if available and not already pruned). */ incomingTransactions: { [transactionId: string]: [Transaction]; }; } -/** The account metadata */ +/** The account metadata. */ export interface AccountMetadata { /** The account alias */ alias: string; @@ -154,10 +181,13 @@ export interface AccountMetadata { index: number; } -/** Options for account creation */ +/** Options for account creation. */ export interface CreateAccountPayload { + /** An account alias name. */ alias?: string; + /** The Bech32 HRP (human readable part) to use. */ bech32Hrp?: string; + /** Account addresses to use. */ addresses?: AccountAddress[]; } diff --git a/bindings/nodejs/lib/types/wallet/address.ts b/bindings/nodejs/lib/types/wallet/address.ts index 66c5d661c1..36424b58ca 100644 --- a/bindings/nodejs/lib/types/wallet/address.ts +++ b/bindings/nodejs/lib/types/wallet/address.ts @@ -3,44 +3,78 @@ /** An Address of the Account */ export interface AccountAddress { + /** The Bech32 address. */ address: string; + /** The address key index. */ keyIndex: number; + /** Whether the address is a public or an internal (change) address. */ internal: boolean; + /** Whether the address was already used before. */ used: boolean; } /** Address with a base token amount */ export interface SendParams { + /** The Bech32 address to send the amount to. */ address: string; + /** The amount to send. */ amount: bigint | string; + /** + * Bech32 encoded address, to which the storage deposit will be returned if one is necessary + * given the provided amount. If a storage deposit is needed and a return address is not provided, it will + * default to the first address of the account. + */ returnAddress?: string; + /** + * Expiration in seconds, after which the output will be available for the sender again, if not spent by the + * receiver already. The expiration will only be used if one is necessary given the provided amount. If an + * expiration is needed but not provided, it will default to one day. + */ expiration?: number; } /** Address with unspent outputs */ export interface AddressWithUnspentOutputs { + /** The Bech32 address. */ address: string; + /** The address key index. */ keyIndex: number; + /** Whether the address is a public or an internal (change) address. */ internal: boolean; + /** The IDs of associated unspent outputs. */ outputIds: string[]; } /** Address with native tokens */ export interface SendNativeTokensParams { + /** The Bech32 address. */ address: string; + /** The Native Tokens to send. */ nativeTokens: [string, bigint][]; + /** + * Bech32 encoded address, to which the storage deposit will be returned. + * Default will use the first address of the account. + */ returnAddress?: string; + /** + * Expiration in seconds, after which the output will be available for the sender again, if not spent by the + * receiver before. Default is 1 day. + */ expiration?: number; } /** Address with an NftId */ export interface SendNftParams { + /** The Bech32 address. */ address: string; + /** The ID of the NFT to send. */ nftId: string; } /** Options for address generation, useful with a Ledger Nano SecretManager */ export interface GenerateAddressOptions { + /** Whether to generate a public or an internal (change) address. */ internal: boolean; + /** Whether to display the generated address on Ledger Nano devices. */ ledgerNanoPrompt: boolean; } diff --git a/bindings/nodejs/lib/types/wallet/consolidation-params.ts b/bindings/nodejs/lib/types/wallet/consolidation-params.ts index 6025a94788..aeeb52c9b4 100644 --- a/bindings/nodejs/lib/types/wallet/consolidation-params.ts +++ b/bindings/nodejs/lib/types/wallet/consolidation-params.ts @@ -3,10 +3,10 @@ /** Parameters for consolidation */ export interface ConsolidationParams { - // Ignores the output_threshold if set to `true`. + /** Ignores the output threshold if set to `true`. */ force: boolean; - // Consolidates if the output number is >= the output_threshold. + /** Consolidates if the output number is >= the output_threshold. */ outputThreshold?: number; - // Address to which the consolidated output should be sent. + /** Address to which the consolidated output should be sent. */ targetAddress?: string; } diff --git a/bindings/nodejs/lib/types/wallet/event.ts b/bindings/nodejs/lib/types/wallet/event.ts index 73e45e1e97..1b167dc3de 100644 --- a/bindings/nodejs/lib/types/wallet/event.ts +++ b/bindings/nodejs/lib/types/wallet/event.ts @@ -7,15 +7,28 @@ import { InputSigningData, Remainder } from '../client'; import { TransactionEssence, TransactionPayload } from '../block'; import { OutputResponse } from '../models'; +/** + * A Transaction ID represented as hex-encoded string. + */ export type TransactionId = string; +/** + * An wallet account event. + */ class Event { /** * The account index for which the event was emitted. */ accountIndex: number; + /** + * The wallet event. + */ event: WalletEvent; + /** + * @param accountIndex The account index. + * @param event The wallet event. + */ constructor(accountIndex: number, event: WalletEvent) { this.accountIndex = accountIndex; this.event = event; @@ -26,42 +39,71 @@ class Event { * All of the wallet event types. */ enum WalletEventType { + /** Consolidation is required. */ ConsolidationRequired = 0, + /** Nano Ledger has generated an address. */ LedgerAddressGeneration = 1, + /** A new output was created. */ NewOutput = 2, + /** An output was spent. */ SpentOutput = 3, + /** A transaction was included into the ledger. */ TransactionInclusion = 4, + /** A progress update while submitting a transaction. */ TransactionProgress = 5, } +/** + * The base class for wallet events. + */ abstract class WalletEvent { type: WalletEventType; + /** + * @param type The type of wallet event. + */ constructor(type: WalletEventType) { this.type = type; } } +/** + * A 'consolidation required' wallet event. + */ class ConsolidationRequiredWalletEvent extends WalletEvent { constructor() { super(WalletEventType.ConsolidationRequired); } } +/** + * A 'ledger address generation' wallet event. + */ class LedgerAddressGenerationWalletEvent extends WalletEvent { address: string; + /** + * @param address The generated address. + */ constructor(address: string) { super(WalletEventType.LedgerAddressGeneration); this.address = address; } } +/** + * A 'new output' wallet event. + */ class NewOutputWalletEvent extends WalletEvent { output: OutputData; transaction?: TransactionPayload; transactionInputs?: OutputResponse[]; + /** + * @param output The new output. + * @param transaction The transaction that created the output. Might be pruned and not available. + * @param transactionInputs The inputs for the transaction that created the output. Might be pruned and not available. + */ constructor( output: OutputData, transaction?: TransactionPayload, @@ -74,19 +116,32 @@ class NewOutputWalletEvent extends WalletEvent { } } +/** + * A 'spent output' wallet event. + */ class SpentOutputWalletEvent extends WalletEvent { output: OutputData; + /** + * @param output The spent output. + */ constructor(output: OutputData) { super(WalletEventType.SpentOutput); this.output = output; } } +/** + * A 'transaction inclusion' wallet event. + */ class TransactionInclusionWalletEvent extends WalletEvent { transactionId: TransactionId; inclusionState: InclusionState; + /** + * @param transactionId The transaction ID. + * @param inclusionState The inclusion state of the transaction. + */ constructor(transactionId: TransactionId, inclusionState: InclusionState) { super(WalletEventType.TransactionInclusion); this.transactionId = transactionId; @@ -98,52 +153,88 @@ class TransactionInclusionWalletEvent extends WalletEvent { * All of the transaction progress types. */ enum TransactionProgressType { + /** Performing input selection. */ SelectingInputs = 0, + /** Generating remainder value deposit address. */ GeneratingRemainderDepositAddress = 1, + /** Prepared transaction. */ PreparedTransaction = 2, + /** Prepared transaction essence hash hex encoded, required for blindsigning with a Ledger Nano. */ PreparedTransactionEssenceHash = 3, + /** Signing the transaction. */ SigningTransaction = 4, + /** Performing PoW. */ PerformingPow = 5, + /** Broadcasting. */ Broadcasting = 6, } +/** + * A 'transaction progress' wallet event. + */ class TransactionProgressWalletEvent extends WalletEvent { progress: TransactionProgress; + /** + * @param progress The progress of the transaction. + */ constructor(progress: TransactionProgress) { super(WalletEventType.TransactionProgress); this.progress = progress; } } +/** + * The base class for transaction progresses. + */ abstract class TransactionProgress { type: TransactionProgressType; + /** + * @param type The type of transaction progress. + */ constructor(type: TransactionProgressType) { this.type = type; } } +/** + * A 'selecting inputs' progress. + */ class SelectingInputsProgress extends TransactionProgress { constructor() { super(TransactionProgressType.SelectingInputs); } } +/** + * A 'generating remainder deposit address' progress. + */ class GeneratingRemainderDepositAddressProgress extends TransactionProgress { address: string; + /** + * @param address The generated remainder deposit address. + */ constructor(address: string) { super(TransactionProgressType.GeneratingRemainderDepositAddress); this.address = address; } } +/** + * A 'prepared transaction' progress. + */ class PreparedTransactionProgress extends TransactionProgress { essence: TransactionEssence; inputsData: InputSigningData[]; remainder?: Remainder; + /** + * @param essence The essence of the prepared transaction. + * @param inputsData Input signing parameters. + * @param remainder Remainder output parameters. + */ constructor( essence: TransactionEssence, inputsData: InputSigningData[], @@ -156,27 +247,42 @@ class PreparedTransactionProgress extends TransactionProgress { } } +/** + * A 'prepared transaction essence hash' progress. + */ class PreparedTransactionEssenceHashProgress extends TransactionProgress { hash: string; + /** + * @param hash The hash of the transaction essence. + */ constructor(hash: string) { super(TransactionProgressType.PreparedTransactionEssenceHash); this.hash = hash; } } +/** + * A 'signing transaction' progress. + */ class SigningTransactionProgress extends TransactionProgress { constructor() { super(TransactionProgressType.SigningTransaction); } } +/** + * A 'performing PoW' progress. + */ class PerformingPowProgress extends TransactionProgress { constructor() { super(TransactionProgressType.PerformingPow); } } +/** + * A 'broadcasting' progress. + */ class BroadcastingProgress extends TransactionProgress { constructor() { super(TransactionProgressType.Broadcasting); diff --git a/bindings/nodejs/lib/types/wallet/output-params.ts b/bindings/nodejs/lib/types/wallet/output-params.ts index fb3261355e..8ab28b27b2 100644 --- a/bindings/nodejs/lib/types/wallet/output-params.ts +++ b/bindings/nodejs/lib/types/wallet/output-params.ts @@ -4,44 +4,69 @@ import { INativeToken } from '../models'; import { HexEncodedString } from '../utils/hex-encoding'; -/** Options for the creation of an output */ +/** Options for the creation of an output. */ export interface OutputParams { + /** A recipient address. */ recipientAddress: string; + /** An amount. */ amount: bigint | string; + /** Assets to include. */ assets?: Assets; + /** Features to include. */ features?: Features; + /** Unlocks to include. */ unlocks?: Unlocks; + /** The storage deposit strategy to use. */ storageDeposit?: StorageDeposit; } -/** Assets to include in the output */ +/** Assets to include in the output. */ export interface Assets { + /** Native Token assets to include. */ nativeTokens?: INativeToken[]; + /** The NFT to include. */ nftId?: HexEncodedString; } -/** Features to include in the output */ +/** Features to include in the output. */ export interface Features { + /** A Tag feature to include. */ tag?: HexEncodedString; + /** A Metadata feature to include. */ metadata?: HexEncodedString; + /** A Sender feature to include. */ sender?: string; + /** An Issuer feature to include. */ issuer?: string; } -/** Time unlocks to include in the output */ +/** Time unlocks to include in the output. */ export interface Unlocks { + /** The expiration Unix timestamp that marks the end of the expiration period. */ expirationUnixTime?: number; + /** The timelock Unix timestamp that marks the end of the locking period. */ timelockUnixTime?: number; } -/** Storage deposit strategy to be used for the output */ +/** Storage deposit strategy to be used for the output. */ export interface StorageDeposit { + /** + * The return strategy. + */ returnStrategy?: ReturnStrategy; + /** + * Determines whether the storage deposit will automatically add excess small funds when necessary. + * For example, given an account has 20 tokens and wants to send 15 tokens, and the minimum storage deposit + * is 10 tokens, it wouldn't be possible to create an output with the 5 token remainder. If this flag is enabled, + * the 5 tokens will be added to the output automatically. + */ useExcessIfLow?: boolean; } -/** Return strategy for the storage deposit */ +/** Return strategy for the storage deposit. */ export enum ReturnStrategy { + /** A storage deposit return unlock condition will be added with the required minimum storage deposit. */ Return = 'Return', + /** The recipient address will get the additional amount to reach the minimum storage deposit gifted. */ Gift = 'Gift', } diff --git a/bindings/nodejs/lib/types/wallet/output.ts b/bindings/nodejs/lib/types/wallet/output.ts index c559ceac9e..86e14fc55a 100644 --- a/bindings/nodejs/lib/types/wallet/output.ts +++ b/bindings/nodejs/lib/types/wallet/output.ts @@ -43,6 +43,8 @@ export class OutputData { /** A Segment of the BIP32 path*/ export interface Segment { + /** Whether the segment is hardened. */ hardened: boolean; + /** The bytes of the segment. */ bs: Uint8Array; } diff --git a/bindings/nodejs/lib/types/wallet/participation.ts b/bindings/nodejs/lib/types/wallet/participation.ts index 373096d579..9c0a84e887 100644 --- a/bindings/nodejs/lib/types/wallet/participation.ts +++ b/bindings/nodejs/lib/types/wallet/participation.ts @@ -4,54 +4,103 @@ import type { INode } from '../client'; import type { OutputId } from '../block/output'; +/** + * An object containing an account's entire participation overview. + */ export interface ParticipationOverview { participations: Participations; } +/** + * Output participations for events. + */ export interface Participations { [eventId: ParticipationEventId]: { [outputId: OutputId]: TrackedParticipationOverview; }; } +/** + * Holds the information for each tracked participation. + */ export interface TrackedParticipationOverview { + /** Amount of tokens that were included in the output the participation was made. */ amount: string; + /** IDs of the answers to the questions of a ballot, in the same order. */ answers: number[]; + /** ID of the block that included the transaction that created the output the participation was made. */ blockId: string; + /** Milestone index the participation ended. 0 if the participation is still active. */ endMilestoneIndex: number; + /** Milestone index the participation started. */ startMilestoneIndex: number; } +/** + * A participation event. + */ export interface ParticipationEvent { + /** The event ID. */ id: ParticipationEventId; + /** Information about a voting or staking event. */ data: ParticipationEventData; } +/** + * Options when registering participation events. + */ export interface ParticipationEventRegistrationOptions { + /** The node to register participation events. */ node: INode; + /** + * The events to register. + * If empty, then every event being tracked by the node will be registered. */ eventsToRegister?: ParticipationEventId[]; + /** The events to ignore. */ eventsToIgnore?: ParticipationEventId[]; } +/** + * A participation event with the provided client nodes. + */ export interface ParticipationEventWithNodes { + /** The event id */ id: ParticipationEventId; + /** Information about a voting or staking event */ data: ParticipationEventData; + /** Provided client nodes for this event. */ nodes: INode[]; } +/** + * A participation event ID represented as hex-encoded string. + */ export type ParticipationEventId = string; +/** + * Maps participation event IDs to their corresponding event data with nodes. + */ export type ParticipationEventMap = { [id: ParticipationEventId]: ParticipationEventWithNodes; }; +/** + * The participation event status. + */ export interface ParticipationEventStatus { + /** The milestone index the status was calculated for. */ milestoneIndex: number; + /** The overall status of the event. */ status: EventStatus; + /** The answer status of the different questions of the event. */ questions?: QuestionStatus[]; + /** Checksum is the SHA256 checksum of all the question and answer status or the staking amount and rewards calculated for this milestone index. */ checksum: string; } +/** + * All possible event status. + */ export enum EventStatus { Upcoming = 'upcoming', Commencing = 'commencing', @@ -59,57 +108,111 @@ export enum EventStatus { Ended = 'ended', } +/** + * Metadata about a participation event. + */ export interface ParticipationEventData { + /** The name of the event. */ name: string; + /** The milestone index the commencing period starts. */ milestoneIndexCommence: number; + /** The milestone index the holding period starts. */ milestoneIndexStart: number; + /** The milestone index the event ends. */ milestoneIndexEnd: number; + /** The payload of the event (voting or staking). */ payload: ParticipationEventPayload; + /** Some additional description text about the event. */ additionalInfo: string; } +/** + * Possible participation event payloads (voting or staking). + */ export type ParticipationEventPayload = | VotingEventPayload | StakingEventPayload; +/** + * A voting event payload. + */ export interface VotingEventPayload { + /** The type of the event (voting). */ type: ParticipationEventType.Voting; + /** The questions to vote on. */ questions: Question[]; } +/** + * A staking event payload. + */ export interface StakingEventPayload { + /** The type of the event (statking). */ type: ParticipationEventType.Staking; + /** The description text of the staking event. */ text: string; + /** The symbol of the rewarded tokens. */ symbol: string; + /** Used in combination with Denominator to calculate the rewards per milestone per staked tokens. */ numerator: string; + /** Used in combination with Numerator to calculate the rewards per milestone per staked tokens. */ denominator: string; + /** The minimum rewards required to be included in the staking results. */ requiredMinimumRewards: string; + /** Additional description text about the staking event. */ additionalInfo: string; } +/** + * Defines a single question inside a Ballot that can have multiple answers. + */ export interface Question { + /** The text of the question. */ text: string; + /** The possible answers to the question. */ answers: Answer[]; + /** Some additional description text about the question. */ additionalInfo: string; } +/** + * The answer in a voting event. + */ export interface Answer { + /** The value that should be used to pick this answer. It must be unique for each answer in a given question. Reserved values are 0 and 255. */ value: number; + /** The text of the answer. */ text: string; + /** Some additional description text about the answer. */ additionalInfo: string; } +/** + * The question status. + */ export interface QuestionStatus { + /** The status of the answers. */ answers: AnswerStatus[]; } +/** + * The answer status. + */ export interface AnswerStatus { + /** The value that identifies this answer. */ value: number; + /** The current voting weight of the answer. */ current: number; + /** The accumulated voting weight of the answer. */ accumulated: number; } +/** + * The types of participation events. + */ export enum ParticipationEventType { + /** A voting event. */ Voting = 0, + /** A staking event. */ Staking = 1, } diff --git a/bindings/nodejs/lib/types/wallet/prepared-create-token-transaction-data.ts b/bindings/nodejs/lib/types/wallet/prepared-create-token-transaction-data.ts index ed00f95307..a41161cba2 100644 --- a/bindings/nodejs/lib/types/wallet/prepared-create-token-transaction-data.ts +++ b/bindings/nodejs/lib/types/wallet/prepared-create-token-transaction-data.ts @@ -5,7 +5,7 @@ import { Type } from 'class-transformer'; import { Transaction } from './transaction'; import { PreparedTransactionData } from '../client/prepared-transaction-data'; -/** The result of preparing an operation to create a native token */ +/** The result of preparing an operation to create a native token. */ export class PreparedCreateNativeTokenTransactionData { /** The token id of the minted token */ tokenId!: string; @@ -14,7 +14,7 @@ export class PreparedCreateNativeTokenTransactionData { transaction!: PreparedTransactionData; } -/** The result of an operation to create a native token */ +/** The result of an operation to create a native token. */ export class CreateNativeTokenTransaction { /** The token id of the minted token */ tokenId!: string; diff --git a/bindings/nodejs/lib/types/wallet/prepared-create-token-transaction.ts b/bindings/nodejs/lib/types/wallet/prepared-create-token-transaction.ts index 1eace7d6ff..0e708f812a 100644 --- a/bindings/nodejs/lib/types/wallet/prepared-create-token-transaction.ts +++ b/bindings/nodejs/lib/types/wallet/prepared-create-token-transaction.ts @@ -11,6 +11,10 @@ import { PreparedTransaction } from './prepared-transaction'; export class PreparedCreateNativeTokenTransaction extends PreparedTransaction { readonly _tokenId: string; + /** + * @param preparedData Prepared data to create a Native Token. + * @param account A wallet account. + */ constructor( preparedData: PreparedCreateNativeTokenTransactionData, account: Account, diff --git a/bindings/nodejs/lib/types/wallet/prepared-transaction.ts b/bindings/nodejs/lib/types/wallet/prepared-transaction.ts index 042b6ed75e..53ef46827b 100644 --- a/bindings/nodejs/lib/types/wallet/prepared-transaction.ts +++ b/bindings/nodejs/lib/types/wallet/prepared-transaction.ts @@ -18,6 +18,10 @@ export class PreparedTransaction { readonly _preparedData: PreparedTransactionData; readonly _account: Account; + /** + * @param preparedData Prepared data to sign and submit a transaction. + * @param account A wallet account. + */ constructor(preparedData: PreparedTransactionData, account: Account) { this._preparedData = preparedData; this._account = account; diff --git a/bindings/nodejs/lib/types/wallet/signed-transaction-essence.ts b/bindings/nodejs/lib/types/wallet/signed-transaction-essence.ts index 46bbbb4a57..a41593d372 100644 --- a/bindings/nodejs/lib/types/wallet/signed-transaction-essence.ts +++ b/bindings/nodejs/lib/types/wallet/signed-transaction-essence.ts @@ -7,8 +7,10 @@ import { InputSigningData } from '../client'; /** The signed transaction with inputs data */ export class SignedTransactionEssence { + /** A transaction payload. */ @Type(() => TransactionPayload) transactionPayload!: TransactionPayload; + /** Signed inputs data. */ @Type(() => InputSigningData) inputsData!: InputSigningData; } diff --git a/bindings/nodejs/lib/types/wallet/transaction-options.ts b/bindings/nodejs/lib/types/wallet/transaction-options.ts index 9b1a6915ef..d82d0614ac 100644 --- a/bindings/nodejs/lib/types/wallet/transaction-options.ts +++ b/bindings/nodejs/lib/types/wallet/transaction-options.ts @@ -4,45 +4,64 @@ import { TaggedDataPayload } from '../block/payload/tagged'; import { Burn } from '../client'; -/** Options for the transaction creation */ +/** Options for creating a transaction. */ export interface TransactionOptions { + /** The strategy applied for base coin remainders. */ remainderValueStrategy?: RemainderValueStrategy; + /** An optional tagged data payload. */ taggedDataPayload?: TaggedDataPayload; - /** Custom inputs that should be used for the transaction */ + /** + * Custom inputs that should be used for the transaction. + * If custom inputs are provided, only those are used. + * If also other additional inputs should be used, `mandatoryInputs` should be used instead. + */ customInputs?: string[]; + /** Inputs that must be used for the transaction. */ mandatoryInputs?: string[]; + /** Specifies what needs to be burned during input selection. */ burn?: Burn; - /** Optional note, that is only stored locally */ + /** Optional note, that is only stored locally. */ note?: string; + /** Whether to allow sending a micro amount. */ allowMicroAmount: boolean; } -/** The RemainderValueStrategy */ +/** The possible remainder value strategies. */ export type RemainderValueStrategy = | ChangeAddress | ReuseAddress | CustomAddress; -/** ChangeAddress variant of RemainderValueStrategy */ +/** + * Allows to move the remainder value to a change address. + */ export type ChangeAddress = { + /** The name of the strategy. */ strategy: 'ChangeAddress'; + /** Only required for `CustomAddress`. */ value: null; }; -/** ReuseAddress variant of RemainderValueStrategy */ +/** + * Allows to keep the remainder value on the source address. + */ export type ReuseAddress = { + /** The name of the strategy. */ strategy: 'ReuseAddress'; + /** Only required for `CustomAddress`. */ value: null; }; /** CustomAddress variant of RemainderValueStrategy */ export type CustomAddress = { + /** The name of the strategy. */ strategy: 'CustomAddress'; value: string; }; -/** Native token options for creating */ +/** Options for creating Native Tokens. */ export interface CreateNativeTokenParams { + /** The Alias ID of the corresponding Foundry. */ aliasId?: string; /** Hex encoded number */ circulatingSupply: bigint; @@ -52,7 +71,7 @@ export interface CreateNativeTokenParams { foundryMetadata?: string; } -/** Nft options for minting */ +/** Options for minting NFTs. */ export interface MintNftParams { /** Bech32 encoded address to which the Nft will be minted. Default will use the * first address of the account diff --git a/bindings/nodejs/lib/types/wallet/transaction.ts b/bindings/nodejs/lib/types/wallet/transaction.ts index dad368962a..c3b7c59c85 100644 --- a/bindings/nodejs/lib/types/wallet/transaction.ts +++ b/bindings/nodejs/lib/types/wallet/transaction.ts @@ -7,13 +7,13 @@ import { OutputResponse } from '../models/api'; /** Possible InclusionStates of transactions sent with the wallet */ export enum InclusionState { - /** The transaction is pending */ + /** The transaction is pending. */ Pending = 'Pending', - /** The transaction is confirmed */ + /** The transaction is confirmed. */ Confirmed = 'Confirmed', - /** The transaction is conflicting */ + /** The transaction is conflicting. */ Conflicting = 'Conflicting', - /** The transaction and its in- and outputs are pruned, so it's unknown if it got confirmed or was conflicting */ + /** The transaction and its in- and outputs are pruned, so it's unknown if it got confirmed or was conflicting. */ UnknownPruned = 'UnknownPruned', } @@ -36,6 +36,10 @@ export class Transaction { incoming!: boolean; /** Note that can be set when sending a transaction and is only stored locally */ note?: string; + /** + * Outputs that are used as input in the transaction. + * May not be all, because some may have already been deleted from the node. + */ @Type(() => OutputResponse) inputs!: OutputResponse[]; } diff --git a/bindings/nodejs/lib/types/wallet/wallet.ts b/bindings/nodejs/lib/types/wallet/wallet.ts index 11b81103d0..6b4c48451b 100644 --- a/bindings/nodejs/lib/types/wallet/wallet.ts +++ b/bindings/nodejs/lib/types/wallet/wallet.ts @@ -1,10 +1,14 @@ import { IClientOptions, CoinType } from '../client'; import { SecretManagerType } from '../secret_manager/secret-manager'; -/** Options for the Wallet builder */ +/** Options for the Wallet builder. */ export interface WalletOptions { + /** The path to the wallet database. */ storagePath?: string; + /** The node client options. */ clientOptions?: IClientOptions; + /** The type of coin stored with the wallet. */ coinType?: CoinType; + /** The secret manager to use. */ secretManager?: SecretManagerType; } diff --git a/bindings/nodejs/lib/utils/utils.ts b/bindings/nodejs/lib/utils/utils.ts index 3bb2922db8..eaa9f19106 100644 --- a/bindings/nodejs/lib/utils/utils.ts +++ b/bindings/nodejs/lib/utils/utils.ts @@ -22,7 +22,7 @@ import { AliasId, BlockId, FoundryId, NftId, TokenId } from '../types/block/id'; /** Utils class for utils. */ export class Utils { /** - * Generates a new mnemonic. + * Generate a new mnemonic. */ static generateMnemonic(): string { return callUtilsMethod({ @@ -31,7 +31,10 @@ export class Utils { } /** - * Returns a hex encoded seed for a mnemonic. + * Convert a mnemonic to a hex encoded seed. + * + * @param mnemonic A mnemonic string. + * @returns The seed as hex-encoded string. */ static mnemonicToHexSeed(mnemonic: string): HexEncodedString { return callUtilsMethod({ @@ -43,7 +46,10 @@ export class Utils { } /** - * Computes the alias id for the given alias output id. + * Compute the alias ID from a given Alias output ID. + * + * @param outputId The output ID as hex-encoded string. + * @returns The Alias ID. */ static computeAliasId(outputId: string): AliasId { return callUtilsMethod({ @@ -55,7 +61,12 @@ export class Utils { } /** - * Computes the foundry id. + * Compute the Foundry ID. + * + * @param aliasId The Alias ID associated with the Foundry. + * @param serialNumber The serial number of the Foundry. + * @param tokenSchemeType The Token scheme type. Currently only a simple scheme is supported. + * @returns The Foundry ID. */ static computeFoundryId( aliasId: AliasId, @@ -73,7 +84,10 @@ export class Utils { } /** - * Computes the NFT id for the given NFT output id. + * Compute the NFT ID from the given NFT output ID. + * + * @param outputId The output ID as hex-encoded string. + * @returns The NFT ID. */ static computeNftId(outputId: string): NftId { return callUtilsMethod({ @@ -85,9 +99,10 @@ export class Utils { } /** - * Computes the inputCommitment from the output objects that are used as inputs to fund the transaction. + * Compute the input commitment from the output objects that are used as inputs to fund the transaction. + * * @param inputs The output objects used as inputs for the transaction. - * @returns The inputs commitment. + * @returns The inputs commitment hash as hex-encoded string. */ static computeInputsCommitment(inputs: Output[]): HexEncodedString { return callUtilsMethod({ @@ -99,10 +114,11 @@ export class Utils { } /** - * Computes the output ID from transaction id and output index. - * @param transactionId The id of the transaction. + * Compute the output ID from transaction ID and output index. + * + * @param transactionId The ID of the transaction. * @param outputIndex The index of the output. - * @returns The output id. + * @returns The output ID. */ static computeOutputId(id: TransactionId, index: number): OutputId { return callUtilsMethod({ @@ -115,7 +131,8 @@ export class Utils { } /** - * Computes the required storage deposit of an output. + * Compute the required storage deposit of an output. + * * @param output The output. * @param rent Rent cost of objects which take node resources. * @returns The required storage deposit. @@ -132,7 +149,8 @@ export class Utils { } /** - * Computes a tokenId from the aliasId, serial number and token scheme type. + * Compute a Token iD from the aliasId, serial number and token scheme type. + * * @param aliasId The alias that controls the foundry. * @param serialNumber The serial number of the foundry. * @param tokenSchemeType The tokenSchemeType of the foundry. @@ -154,7 +172,10 @@ export class Utils { } /** - * Returns a valid Address parsed from a String. + * Parse a Bech32 address from a string. + * + * @param address A Bech32 address as string. + * @returns A Bech32 address. */ static parseBech32Address(address: string): Address { const addr = callUtilsMethod({ @@ -167,7 +188,10 @@ export class Utils { } /** - * Returns a block ID (Blake2b256 hash of the block bytes) + * Compute the block ID (Blake2b256 hash of the block bytes) of a block. + * + * @param block A block. + * @returns The corresponding block ID. */ static blockId(block: Block): BlockId { return callUtilsMethod({ @@ -179,7 +203,10 @@ export class Utils { } /** - * Returns a Milestone ID (Blake2b256 hash of the milestone essence) + * Compute the milestone ID (Blake2b256 hash of the milestone essence) of a milestone payload. + * + * @param payload A milestone payload. + * @returns The milestone ID. */ static milestoneId(payload: MilestonePayload): MilestoneId { return callUtilsMethod({ @@ -191,9 +218,10 @@ export class Utils { } /** - * Returns the transaction ID (Blake2b256 hash of the provided transaction payload) - * @param payload The transaction payload. - * @returns The transaction id. + * Compute the transaction ID (Blake2b256 hash of the provided transaction payload) of a transaction payload. + * + * @param payload A transaction payload. + * @returns The transaction ID. */ static transactionId(payload: TransactionPayload): TransactionId { return callUtilsMethod({ @@ -205,7 +233,10 @@ export class Utils { } /** - * Transforms bech32 to hex. + * Convert a Bech32 address to a hex-encoded string. + * + * @param bech32 A Bech32 address. + * @returns The hex-encoded string. */ static bech32ToHex(bech32: string): string { return callUtilsMethod({ @@ -217,7 +248,11 @@ export class Utils { } /** - * Transforms a hex encoded address to a bech32 encoded address. + * Convert a hex-encoded address string to a Bech32-encoded address string. + * + * @param hex A hex-encoded address string. + * @param bech32Hrp The Bech32 HRP (human readable part) to use. + * @returns The Bech32-encoded address string. */ static hexToBech32(hex: string, bech32Hrp: string): string { return callUtilsMethod({ @@ -230,7 +265,11 @@ export class Utils { } /** - * Transforms an alias id to a bech32 encoded address. + * Convert an Alias ID to a Bech32-encoded address string. + * + * @param aliasId An Alias ID. + * @param bech32Hrp The Bech32 HRP (human readable part) to use. + * @returns The Bech32-encoded address string. */ static aliasIdToBech32(aliasId: string, bech32Hrp: string): string { return callUtilsMethod({ @@ -243,7 +282,11 @@ export class Utils { } /** - * Transforms an nft id to a bech32 encoded address. + * Convert an NFT ID to a Bech32-encoded address string. + * + * @param nftId An NFT ID. + * @param bech32Hrp The Bech32 HRP (human readable part) to use. + * @returns The Bech32-encoded address string. */ static nftIdToBech32(nftId: string, bech32Hrp: string): string { return callUtilsMethod({ @@ -256,7 +299,11 @@ export class Utils { } /** - * Transforms a hex encoded public key to a bech32 encoded address. + * Convert a hex-encoded public key to a Bech32-encoded address string. + * + * @param hex A hex-encoded public key. + * @param bech32Hrp The Bech32 HRP (human readable part) to use. + * @returns The Bech32-encoded address string. */ static hexPublicKeyToBech32Address(hex: string, bech32Hrp: string): string { return callUtilsMethod({ @@ -269,7 +316,9 @@ export class Utils { } /** - * Checks if a String is a valid bech32 encoded address. + * Checks whether an address string is a valid Bech32-encoded address. + * + * @param address An address string. */ static isAddressValid(address: string): boolean { return callUtilsMethod({ @@ -282,6 +331,9 @@ export class Utils { /** * Compute the hash of a transaction essence. + * + * @param essence A transaction essence. + * @returns The hash of the transaction essence as a hex-encoded string. */ static hashTransactionEssence( essence: TransactionEssence, @@ -295,7 +347,10 @@ export class Utils { } /** - * Verifies an ed25519 signature against a message. + * Verify an Ed25519 signature against a message. + * + * @param signature An Ed25519 signature. + * @param message A hex-encoded message. */ static verifyEd25519Signature( signature: Ed25519Signature, @@ -311,7 +366,10 @@ export class Utils { } /** - * Verifies a Secp256k1Ecdsa signature against a message. + * Verify a Secp256k1Ecdsa signature against a message. + * @param publicKey A hex-encoded public key. + * @param signature A hex-encoded signature. + * @param message A hex-encoded message. */ static verifySecp256k1EcdsaSignature( publicKey: HexEncodedString, @@ -330,6 +388,8 @@ export class Utils { /** * Verify if a mnemonic is a valid BIP39 mnemonic. + * + * @param mnemonic A mnemonic string. */ static verifyMnemonic(mnemonic: string): void { return callUtilsMethod({ diff --git a/bindings/nodejs/lib/wallet/account.ts b/bindings/nodejs/lib/wallet/account.ts index 6404084ef3..8961e9f133 100644 --- a/bindings/nodejs/lib/wallet/account.ts +++ b/bindings/nodejs/lib/wallet/account.ts @@ -57,6 +57,10 @@ export class Account { private meta: AccountMeta; private methodHandler: WalletMethodHandler; + /** + * @param accountMeta An instance of `AccountMeta`. + * @param methodHandler A instance of `WalletMethodHandler`. + */ constructor(accountMeta: AccountMeta, methodHandler: WalletMethodHandler) { this.meta = accountMeta; this.methodHandler = methodHandler; @@ -317,6 +321,11 @@ export class Account { ); } + /** + * Deregister a participation event. + * + * @param eventId The id of the participation event to deregister. + */ async deregisterParticipationEvent( eventId: ParticipationEventId, ): Promise { @@ -334,6 +343,7 @@ export class Account { /** * Destroy an alias output. + * * @param aliasId The AliasId. * @param transactionOptions The options to define a `RemainderValueStrategy` * or custom inputs. @@ -367,6 +377,7 @@ export class Account { /** * Function to destroy a foundry output with a circulating supply of 0. * Native tokens in the foundry (minted by other foundries) will be transacted to the controlling alias. + * * @param foundryId The FoundryId. * @param transactionOptions The options to define a `RemainderValueStrategy` * or custom inputs. @@ -398,7 +409,8 @@ export class Account { } /** - * Generate new unused ed25519 addresses. + * Generate new unused Ed25519 addresses. + * * @param amount The amount of addresses to generate. * @param options Options for address generation. * @returns The addresses. @@ -422,6 +434,7 @@ export class Account { /** * Get the account balance. + * * @returns The account balance. */ async getBalance(): Promise { @@ -486,6 +499,11 @@ export class Account { return plainToInstance(OutputData, parsed.payload); } + /** + * Get a participation event. + * + * @param eventId The ID of the event to get. + */ async getParticipationEvent( eventId: ParticipationEventId, ): Promise { @@ -501,6 +519,12 @@ export class Account { return JSON.parse(response).payload; } + /** + * Get IDs of participation events of a certain type. + * + * @param node The node to get events from. + * @param eventType The type of events to get. + */ async getParticipationEventIds( node: INode, eventType?: ParticipationEventType, @@ -518,6 +542,9 @@ export class Account { return JSON.parse(response).payload; } + /** + * Get all participation events. + */ async getParticipationEvents(): Promise { const response = await this.methodHandler.callAccountMethod( this.meta.index, @@ -528,6 +555,11 @@ export class Account { return JSON.parse(response).payload; } + /** + * Get the participation event status by its ID. + * + * @param eventId The ID of the event status to get. + */ async getParticipationEventStatus( eventId: ParticipationEventId, ): Promise { @@ -546,6 +578,7 @@ export class Account { /** * Get a `FoundryOutput` by native token ID. It will try to get the foundry from * the account, if it isn't in the account it will try to get it from the node. + * * @param tokenId The native token ID to get the foundry for. * @returns The `FoundryOutput` that minted the token. */ @@ -564,6 +597,7 @@ export class Account { /** * Get outputs with additional unlock conditions. + * * @param outputs The type of outputs to claim. * @returns The output IDs of the unlockable outputs. */ @@ -582,6 +616,7 @@ export class Account { /** * Get a transaction stored in the account. + * * @param transactionId The ID of the transaction to get. * @returns The transaction. */ @@ -602,6 +637,7 @@ export class Account { /** * Get the transaction with inputs of an incoming transaction stored in the account * List might not be complete, if the node pruned the data already + * * @param transactionId The ID of the transaction to get. * @returns The transaction. */ @@ -621,6 +657,7 @@ export class Account { /** * List all the addresses of the account. + * * @returns The addresses. */ async addresses(): Promise { @@ -636,6 +673,7 @@ export class Account { /** * List the addresses of the account with unspent outputs. + * * @returns The addresses. */ async addressesWithUnspentOutputs(): Promise { @@ -651,6 +689,7 @@ export class Account { /** * List all outputs of the account. + * * @param filterOptions Options to filter the to be returned outputs. * @returns The outputs with metadata. */ @@ -669,6 +708,7 @@ export class Account { /** * List all the pending transactions of the account. + * * @returns The transactions. */ async pendingTransactions(): Promise { @@ -684,6 +724,7 @@ export class Account { /** * List all incoming transactions of the account. + * * @returns The incoming transactions with their inputs. */ async incomingTransactions(): Promise { @@ -699,6 +740,7 @@ export class Account { /** * List all the transactions of the account. + * * @returns The transactions. */ async transactions(): Promise { @@ -714,6 +756,7 @@ export class Account { /** * List all the unspent outputs of the account. + * * @param filterOptions Options to filter the to be returned outputs. * @returns The outputs with metadata. */ @@ -731,6 +774,7 @@ export class Account { /** * Get the accounts metadata. + * * @returns The accounts metadata. */ getMetadata(): AccountMetadata { @@ -743,6 +787,7 @@ export class Account { /** * Mint additional native tokens. + * * @param tokenId The native token id. * @param mintAmount To be minted amount. * @param transactionOptions The options to define a `RemainderValueStrategy` @@ -777,6 +822,7 @@ export class Account { /** * Create a native token. + * * @param params The options for creating a native token. * @param transactionOptions The options to define a `RemainderValueStrategy` * or custom inputs. @@ -816,7 +862,8 @@ export class Account { } /** - * Mint nfts. + * Mint NFTs. + * * @param params The options for minting nfts. * @param transactionOptions The options to define a `RemainderValueStrategy` * or custom inputs. @@ -848,6 +895,7 @@ export class Account { /** * Prepare an output for sending, useful for offline signing. + * * @param options The options for preparing an output. If the amount is * below the minimum required storage deposit, by default the remaining * amount will automatically be added with a `StorageDepositReturn` `UnlockCondition`, @@ -883,6 +931,7 @@ export class Account { /** * Prepare to send base coins, useful for offline signing. + * * @param params Address with amounts to send. * @param options The options to define a `RemainderValueStrategy` * or custom inputs. @@ -918,6 +967,7 @@ export class Account { /** * Prepare a transaction, useful for offline signing. + * * @param outputs Outputs to use in the transaction. * @param options The options to define a `RemainderValueStrategy` * or custom inputs. @@ -946,6 +996,12 @@ export class Account { ); } + /** + * Register participation events. + * + * @param options Options to register participation events. + * @returns A mapping between event IDs and their corresponding event data. + */ async registerParticipationEvents( options: ParticipationEventRegistrationOptions, ): Promise { @@ -986,6 +1042,7 @@ export class Account { /** * Send base coins to an address. + * * @param amount Amount of coins. * @param address Receiving address. * @param transactionOptions The options to define a `RemainderValueStrategy` @@ -1017,6 +1074,7 @@ export class Account { /** * Send base coins with amounts from input addresses. + * * @param params Addresses with amounts. * @param transactionOptions The options to define a `RemainderValueStrategy` * or custom inputs. @@ -1047,6 +1105,7 @@ export class Account { /** * Send native tokens. + * * @param params Addresses amounts and native tokens. * @param transactionOptions The options to define a `RemainderValueStrategy` * or custom inputs. @@ -1076,7 +1135,8 @@ export class Account { } /** - * Send nft. + * Send NFT. + * * @param params Addresses and nft ids. * @param transactionOptions The options to define a `RemainderValueStrategy` * or custom inputs. @@ -1107,6 +1167,7 @@ export class Account { /** * Send outputs in a transaction. + * * @param outputs The outputs to send. * @param transactionOptions The options to define a `RemainderValueStrategy` * or custom inputs. @@ -1133,6 +1194,7 @@ export class Account { /** * Set the alias for the account + * * @param alias The account alias to set. */ async setAlias(alias: string): Promise { @@ -1147,6 +1209,7 @@ export class Account { /** * Set the fallback SyncOptions for account syncing. * If storage is enabled, will persist during restarts. + * * @param options The sync options to set. */ async setDefaultSyncOptions(options: SyncOptions): Promise { @@ -1160,6 +1223,7 @@ export class Account { /** * Sign a prepared transaction, useful for offline signing. + * * @param preparedTransactionData The prepared transaction data to sign. * @returns The signed transaction essence. */ @@ -1183,6 +1247,7 @@ export class Account { /** * Sign a prepared transaction, and send it. + * * @param preparedTransactionData The prepared transaction data to sign and submit. * @returns The transaction. */ @@ -1204,6 +1269,7 @@ export class Account { /** * Validate the transaction, submit it to a node and store it in the account. + * * @param signedTransactionData A signed transaction to submit and store. * @returns The sent transaction. */ @@ -1245,6 +1311,13 @@ export class Account { return this.adjustBalancePayload(payload); } + /** + * Prepare a vote. + * + * @param eventId The participation event ID. + * @param answers Answers for a voting event, can be empty. + * @returns An instance of `PreparedTransaction`. + */ async prepareVote( eventId?: ParticipationEventId, answers?: number[], @@ -1268,6 +1341,12 @@ export class Account { ); } + /** + * Prepare stop participating in an event. + * + * @param eventId The event ID to stop participating in. + * @returns An instance of `PreparedTransaction`. + */ async prepareStopParticipating( eventId: ParticipationEventId, ): Promise { @@ -1291,8 +1370,9 @@ export class Account { /** * Calculates the voting overview of an account. + * * @param eventIds Optional, filters participations only for provided events. - * @returns ParticipationOverview + * @returns An instance of `ParticipationOverview` */ async getParticipationOverview( eventIds?: ParticipationEventId[], @@ -1309,6 +1389,12 @@ export class Account { return JSON.parse(response).payload; } + /** + * Prepare to increase the voting power. + * + * @param amount The amount to increase the voting power by. + * @returns An instance of `PreparedTransaction`. + */ async prepareVotingPower(amount: string): Promise { const response = await this.methodHandler.callAccountMethod( this.meta.index, @@ -1328,6 +1414,12 @@ export class Account { ); } + /** + * Prepare to decrease the voting power. + * + * @param amount The amount to decrease the voting power by. + * @returns An instance of `PreparedTransaction`. + */ async prepareDecreaseVotingPower( amount: string, ): Promise { diff --git a/bindings/nodejs/lib/wallet/wallet-method-handler.ts b/bindings/nodejs/lib/wallet/wallet-method-handler.ts index edf904c2d0..7c18c80b52 100644 --- a/bindings/nodejs/lib/wallet/wallet-method-handler.ts +++ b/bindings/nodejs/lib/wallet/wallet-method-handler.ts @@ -24,6 +24,9 @@ import { SecretManager } from '../secret_manager'; export class WalletMethodHandler { methodHandler: any; + /** + * @param options The wallet options. + */ constructor(options?: WalletOptions) { const walletOptions = { storagePath: options?.storagePath, @@ -35,6 +38,11 @@ export class WalletMethodHandler { this.methodHandler = createWallet(JSON.stringify(walletOptions)); } + /** + * Call a wallet method on the Rust backend. + * + * @param method The wallet method to call. + */ async callMethod(method: __Method__): Promise { return callWalletMethodAsync( // mapToObject is required to convert maps to array since they otherwise get serialized as `[{}]` even if not empty @@ -60,6 +68,12 @@ export class WalletMethodHandler { }); } + /** + * Call an account method on the Rust backend. + * + * @param accountIndex The account index. + * @param method The account method to call. + */ async callAccountMethod( accountIndex: AccountId, method: __AccountMethod__, @@ -73,6 +87,12 @@ export class WalletMethodHandler { }); } + /** + * Listen to wallet events. + * + * @param eventTypes The wallet event types to listen for. + * @param callback The callback function to call when an event is received. + */ async listen( eventTypes: WalletEventType[], callback: (error: Error, event: Event) => void, @@ -84,6 +104,9 @@ export class WalletMethodHandler { return destroyWallet(this.methodHandler); } + /** + * Get the client associated with the wallet. + */ async getClient(): Promise { return new Promise((resolve, reject) => { getClientFromWallet(this.methodHandler).then((result: any) => { @@ -96,6 +119,9 @@ export class WalletMethodHandler { }); } + /** + * Get the secret manager associated with the wallet. + */ async getSecretManager(): Promise { return new Promise((resolve, reject) => { getSecretManagerFromWallet(this.methodHandler).then( diff --git a/bindings/nodejs/lib/wallet/wallet.ts b/bindings/nodejs/lib/wallet/wallet.ts index 318f221bc0..ec292a58bd 100644 --- a/bindings/nodejs/lib/wallet/wallet.ts +++ b/bindings/nodejs/lib/wallet/wallet.ts @@ -22,6 +22,9 @@ import { SecretManager } from '../secret_manager'; export class Wallet { private methodHandler: WalletMethodHandler; + /** + * @param options Wallet options. + */ constructor(options: WalletOptions) { this.methodHandler = new WalletMethodHandler(options); } diff --git a/bindings/nodejs/package.json b/bindings/nodejs/package.json index b8fd9dbcb2..0554c57253 100644 --- a/bindings/nodejs/package.json +++ b/bindings/nodejs/package.json @@ -20,7 +20,7 @@ "rebuild": "node scripts/neon-build && tsc && node scripts/strip.js", "install": "prebuild-install --runtime napi --tag-prefix='iota-sdk-nodejs-v' && tsc || npm run rebuild", "test": "jest", - "create-api-docs": "typedoc ./lib/index.ts --githubPages false --disableSources --excludePrivate --excludeInternal --plugin typedoc-plugin-markdown --theme markdown --hideBreadcrumbs --entryDocument api_ref.md --readme none --hideGenerator --sort source-order --exclude ./**/src/index.ts" + "create-api-docs": "typedoc ./lib/index.ts --githubPages false --disableSources --excludePrivate --excludeInternal --plugin typedoc-plugin-markdown --theme markdown --hideBreadcrumbs --entryDocument api_ref.md --readme none --hideGenerator --sort source-order" }, "author": "IOTA Foundation ", "license": "Apache-2.0", diff --git a/sdk/examples/client/output/alias.rs b/sdk/examples/client/output/alias.rs index c34d9640e9..4c94c58469 100644 --- a/sdk/examples/client/output/alias.rs +++ b/sdk/examples/client/output/alias.rs @@ -78,7 +78,7 @@ async fn main() -> Result<()> { let _ = client.retry_until_included(&block.id(), None, None).await?; ////////////////////////////////// - // create second transaction with the actual AliasId (BLAKE2b-160 hash of the Output ID that created the alias) + // create second transaction with the actual AliasId (BLAKE2b-256 hash of the Output ID that created the alias) ////////////////////////////////// let alias_output_id = get_alias_output_id(block.payload().unwrap())?; let alias_id = AliasId::from(&alias_output_id); diff --git a/sdk/examples/client/output/recursive_alias.rs b/sdk/examples/client/output/recursive_alias.rs index 6b1e261201..c8700efcd4 100644 --- a/sdk/examples/client/output/recursive_alias.rs +++ b/sdk/examples/client/output/recursive_alias.rs @@ -77,7 +77,7 @@ async fn main() -> Result<()> { let _ = client.retry_until_included(&block_1.id(), None, None).await?; ////////////////////////////////// - // create second transaction with the actual AliasId (BLAKE2b-160 hash of the Output ID that created the alias) and + // create second transaction with the actual AliasId (BLAKE2b-256 hash of the Output ID that created the alias) and // make both alias outputs controlled by the first one ////////////////////////////////// let alias_output_ids = get_new_alias_output_ids(block_1.payload().unwrap())?;