From c1398f1043fcdcecc760c8ca7c3ae76220a2cb71 Mon Sep 17 00:00:00 2001 From: Ivaylo Nikolov Date: Tue, 14 Jan 2025 13:54:36 +0200 Subject: [PATCH 1/4] docs: first batch of documentation Signed-off-by: Ivaylo Nikolov --- Taskfile.yml | 3 +++ package.json | 4 +++- src/Cache.js | 4 +++- src/account/AccountBalance.js | 3 +++ src/account/AccountInfoFlow.js | 9 +++++++++ src/account/AccountInfoQuery.js | 1 + src/client/Client.js | 4 ++++ src/client/NativeClient.js | 1 - src/contract/ContractByteCodeQuery.js | 6 ++++++ src/contract/ContractCallQuery.js | 6 ++++++ src/contract/ContractCreateFlow.js | 12 ++++++++++++ src/network/AddressBookQuery.js | 6 ++++++ src/token/AssessedCustomFee.js | 5 +++++ src/token/TokenAirdropTransaction.js | 7 +++++++ src/token/TokenCancelAirdropTransaction.js | 6 ++++++ src/token/TokenClaimAirdropTransaction.js | 5 +++++ 16 files changed, 79 insertions(+), 3 deletions(-) diff --git a/Taskfile.yml b/Taskfile.yml index 885a277a4..210d0e57a 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -35,6 +35,9 @@ tasks: docs: cmds: - npx typedoc + --plugin typedoc-plugin-coverage + --coverageOutputType json + --logLevel Verbose --excludeInternal --excludePrivate --excludeProtected diff --git a/package.json b/package.json index f67c7c6ba..a60ab80f3 100644 --- a/package.json +++ b/package.json @@ -69,6 +69,7 @@ "pino-pretty": "^10.0.0", "protobufjs": "7.2.5", "rfc4648": "^1.5.3", + "typedoc-plugin-coverage": "^3.4.1", "utf8": "^3.0.0" }, "devDependencies": { @@ -128,5 +129,6 @@ "expo": { "optional": true } - } + }, + "packageManager": "pnpm@9.14.4+sha512.c8180b3fbe4e4bca02c94234717896b5529740a6cbadf19fa78254270403ea2f27d4e1d46a08a0f56c89b63dc8ebfd3ee53326da720273794e6200fcf0d184ab" } diff --git a/src/Cache.js b/src/Cache.js index fb4c0f17f..8ae6a6113 100644 --- a/src/Cache.js +++ b/src/Cache.js @@ -53,7 +53,9 @@ */ /** - * This variable is strictly designed to prevent cyclic dependencies. + * Cache class is designed to prevent cyclic dependencies in the Hedera JavaScript SDK. + * It stores various conversion functions and configuration values that are used across + * different parts of the SDK. */ class Cache { constructor() { diff --git a/src/account/AccountBalance.js b/src/account/AccountBalance.js index d2e9d8a6c..96a086c6e 100644 --- a/src/account/AccountBalance.js +++ b/src/account/AccountBalance.js @@ -38,6 +38,9 @@ import * as HashgraphProto from "@hashgraph/proto"; * @property {TokenBalanceJson[]} tokens */ +/** + * Represents the balance of an account on the Hedera network, including both HBAR and token balances. + */ export default class AccountBalance { /** * @private diff --git a/src/account/AccountInfoFlow.js b/src/account/AccountInfoFlow.js index 5c2673a8d..81d95d0a9 100644 --- a/src/account/AccountInfoFlow.js +++ b/src/account/AccountInfoFlow.js @@ -29,6 +29,15 @@ import KeyList from "../KeyList.js"; * @typedef {import("../Signer.js").Signer} Signer */ +/** + * This class provides static methods to verify signatures and transactions by fetching the account's key + * from the network. It supports both Client and Signer-based operations. + * + * The class provides methods to: + * - Verify message signatures using account public key + * - Verify transaction signatures using account public key + * - Perform verifications using either a Client or Signer instance + */ export default class AccountInfoFlow { /** * @param {Client} client diff --git a/src/account/AccountInfoQuery.js b/src/account/AccountInfoQuery.js index db3d627e2..5704ae836 100644 --- a/src/account/AccountInfoQuery.js +++ b/src/account/AccountInfoQuery.js @@ -41,6 +41,7 @@ import Hbar from "../Hbar.js"; */ /** + * Retrieves the metadata of an account * @augments {Query} */ export default class AccountInfoQuery extends Query { diff --git a/src/client/Client.js b/src/client/Client.js index 3bceaf58c..d688f4387 100644 --- a/src/client/Client.js +++ b/src/client/Client.js @@ -63,6 +63,10 @@ import { convertToNumber } from "../util.js"; */ /** + * The `Client` class is the main entry point for interacting with the Hedera Hashgraph network. + * It provides methods for managing network connections, setting operators, handling transactions + * and queries, and configuring various client settings. + * * @abstract * @template {Channel} ChannelT * @template {MirrorChannel} MirrorChannelT diff --git a/src/client/NativeClient.js b/src/client/NativeClient.js index 9808050de..d7b435b03 100644 --- a/src/client/NativeClient.js +++ b/src/client/NativeClient.js @@ -32,7 +32,6 @@ import { /** * @typedef {import("./Client.js").ClientConfiguration} ClientConfiguration */ - export const Network = { /** * @param {string} name diff --git a/src/contract/ContractByteCodeQuery.js b/src/contract/ContractByteCodeQuery.js index d04742549..02ff7bf26 100644 --- a/src/contract/ContractByteCodeQuery.js +++ b/src/contract/ContractByteCodeQuery.js @@ -38,6 +38,12 @@ import ContractId from "./ContractId.js"; */ /** + * Query to retrieve the bytecode of a smart contract from the network. + * + * This query returns the bytecode of a smart contract instance that has been + * created on the Hedera network. The bytecode represents the compiled code + * that is executed by the Hedera network when the contract is called. + * * @augments {Query} */ export default class ContractByteCodeQuery extends Query { diff --git a/src/contract/ContractCallQuery.js b/src/contract/ContractCallQuery.js index d9a7af600..59c08a266 100644 --- a/src/contract/ContractCallQuery.js +++ b/src/contract/ContractCallQuery.js @@ -40,6 +40,12 @@ import Status from "../Status.js"; */ /** + * A query that calls a function of a contract instance. It will consume the amount of gas + * specified, and return the result of the function call. + * + * This query will not update the state of the contract instance on the network, but will + * only retrieve information. To update the state, you must use ContractExecuteTransaction. + * * @augments {Query} */ export default class ContractCallQuery extends Query { diff --git a/src/contract/ContractCreateFlow.js b/src/contract/ContractCreateFlow.js index 244bec186..ed4d5fef8 100644 --- a/src/contract/ContractCreateFlow.js +++ b/src/contract/ContractCreateFlow.js @@ -49,6 +49,18 @@ import PublicKey from "../PublicKey.js"; * @typedef {import("long")} Long */ +/** + * A convenience flow that handles the creation of a smart contract on the Hedera network. + * This flow abstracts away the complexity of the contract creation process by: + * + * 1. Creating a file to store the contract bytecode + * 2. Uploading the contract bytecode in chunks if necessary + * 3. Creating the contract instance using the uploaded bytecode + * 4. Cleaning up by deleting the bytecode file (if operator key is available) + * + * This flow is particularly useful when deploying large contracts that exceed the 2048 byte + * limit of a single transaction. + */ export default class ContractCreateFlow { constructor() { /** @type {Uint8Array | null} */ diff --git a/src/network/AddressBookQuery.js b/src/network/AddressBookQuery.js index a3323a4e1..690f4b98f 100644 --- a/src/network/AddressBookQuery.js +++ b/src/network/AddressBookQuery.js @@ -39,6 +39,12 @@ import CACHE from "../Cache.js"; /** * @augments {Query} + * Query to get a list of Hedera network node addresses from a mirror node. + * + * This query can be used to retrieve node addresses either from a specific file ID + * or from the most recent address book if no file ID is specified. The response + * contains node metadata including IP addresses and ports for both node and mirror + * node services. */ export default class AddressBookQuery extends Query { /** diff --git a/src/token/AssessedCustomFee.js b/src/token/AssessedCustomFee.js index 260d70854..7ce60d062 100644 --- a/src/token/AssessedCustomFee.js +++ b/src/token/AssessedCustomFee.js @@ -35,6 +35,11 @@ import Long from "long"; * @property {string[]} payerAccountIds */ +/** + * Represents an assessed custom fee that has been evaluated and attached to a transaction. + * This includes details about who collects the fee, which token the fee is paid in, + * the amount of the fee, and which accounts are responsible for paying it. + */ export default class AssessedCustomFee { /** * @param {object} props diff --git a/src/token/TokenAirdropTransaction.js b/src/token/TokenAirdropTransaction.js index 805a69b7c..74506b97a 100644 --- a/src/token/TokenAirdropTransaction.js +++ b/src/token/TokenAirdropTransaction.js @@ -44,6 +44,13 @@ import AbstractTokenTransferTransaction from "./AbstractTokenTransferTransaction * @typedef {import("./NftId.js").default} NftId * @typedef {import("./TokenId.js").default} TokenId */ + +/** + * A transaction that allows the transfer of tokens to multiple accounts in a single transaction. + * This is a more efficient way to distribute tokens to multiple accounts compared to individual + * token transfer transactions. + * + */ export default class TokenAirdropTransaction extends AbstractTokenTransferTransaction { /** * @param {object} props diff --git a/src/token/TokenCancelAirdropTransaction.js b/src/token/TokenCancelAirdropTransaction.js index fd1822262..b59c77b29 100644 --- a/src/token/TokenCancelAirdropTransaction.js +++ b/src/token/TokenCancelAirdropTransaction.js @@ -37,6 +37,12 @@ import AirdropPendingTransaction from "./AirdropPendingTransaction.js"; * @typedef {import("../transaction/TransactionId.js").default} TransactionId * @typedef {import("../account/AccountId.js").default} AccountId */ + +/** + * A transaction that allows the cancellation of pending airdrops. + * This transaction can be used by authorized accounts to cancel airdrop operations + * that have been initiated but not yet claimed by recipients. + */ export default class TokenCancelAirdropTransaction extends AirdropPendingTransaction { /** * @param {object} props diff --git a/src/token/TokenClaimAirdropTransaction.js b/src/token/TokenClaimAirdropTransaction.js index 6e8704f3c..ceba4a184 100644 --- a/src/token/TokenClaimAirdropTransaction.js +++ b/src/token/TokenClaimAirdropTransaction.js @@ -39,6 +39,11 @@ import Transaction, { * @typedef {import("../account/AccountId.js").default} AccountId */ +/** + * A transaction that allows an account to claim tokens from a pending airdrop. + * This transaction is used to finalize the receipt of tokens that were distributed + * through an airdrop mechanism but require explicit claiming by the recipient. + */ export default class TokenClaimAirdropTransaction extends AirdropPendingTransaction { /** * @param {object} props From b60c577e1953bf8fd4f13532101b1746c249c800 Mon Sep 17 00:00:00 2001 From: Ivaylo Nikolov Date: Tue, 14 Jan 2025 16:32:58 +0200 Subject: [PATCH 2/4] docs: batch 2 Signed-off-by: Ivaylo Nikolov --- src/Cache.js | 3 +++ src/EvmAddress.js | 4 ++++ src/ExchangeRate.js | 5 +++++ src/ExchangeRates.js | 4 ++++ src/FeeComponents.js | 5 +++++ src/FeeData.js | 16 +++++++++++++++ src/FeeSchedule.js | 4 ++++ src/FeeSchedules.js | 5 +++++ src/Hbar.js | 4 ++++ src/HbarUnit.js | 6 ++++++ src/account/HbarAllowance.js | 4 ++++ src/client/NodeClient.js | 2 ++ src/contract/ContractCreateTransaction.js | 21 +++++++++++++++++++ src/contract/ContractDeleteTransaction.js | 24 ++++++++++++++++++++++ src/contract/ContractExecuteTransaction.js | 10 +++++++++ src/contract/ContractFunctionParameters.js | 8 ++++++++ src/contract/ContractFunctionSelector.js | 7 +++++++ src/contract/ContractInfoQuery.js | 2 ++ src/contract/ContractUpdateTransaction.js | 8 ++++++++ src/contract/DelegateContractId.js | 4 ++++ src/file/FileContentsQuery.js | 3 +++ src/file/FileInfoQuery.js | 2 ++ src/system/FreezeTransaction.js | 10 +++++++++ 23 files changed, 161 insertions(+) diff --git a/src/Cache.js b/src/Cache.js index 8ae6a6113..7081f2023 100644 --- a/src/Cache.js +++ b/src/Cache.js @@ -448,6 +448,9 @@ class Cache { } } +/** + * This variable is strictly designed to prevent cyclic dependencies. + */ const CACHE = new Cache(); export default CACHE; diff --git a/src/EvmAddress.js b/src/EvmAddress.js index 61f9276d2..654b59849 100644 --- a/src/EvmAddress.js +++ b/src/EvmAddress.js @@ -31,6 +31,10 @@ import { arrayEqual } from "./util.js"; * @typedef {import("./client/Client.js").default<*, *>} Client */ +/** + * Represents an Ethereum Virtual Machine (EVM) address. + * This class extends the Key class and provides functionality for handling EVM addresses. + */ export default class EvmAddress extends Key { /** * @internal diff --git a/src/ExchangeRate.js b/src/ExchangeRate.js index d54168c5f..a5b5b0c08 100644 --- a/src/ExchangeRate.js +++ b/src/ExchangeRate.js @@ -28,6 +28,11 @@ import Long from "long"; * @property {number} exchangeRateInCents */ +/** + * Represents an exchange rate between hbars and cents (USD). + * This class provides functionality for handling and converting exchange rates + * between Hedera's native HBAR currency and US cents. + */ export default class ExchangeRate { /** * @private diff --git a/src/ExchangeRates.js b/src/ExchangeRates.js index a0fa3fd62..ed57323d0 100644 --- a/src/ExchangeRates.js +++ b/src/ExchangeRates.js @@ -23,6 +23,10 @@ import * as HashgraphProto from "@hashgraph/proto"; const { proto } = HashgraphProto; +/** + * Represents a pair of exchange rates for HBAR to USD cents conversion. + * Contains both the current exchange rate and the next exchange rate that will take effect. + */ export default class ExchangeRates { /** * @private diff --git a/src/FeeComponents.js b/src/FeeComponents.js index f2ca3a165..205a642ca 100644 --- a/src/FeeComponents.js +++ b/src/FeeComponents.js @@ -21,6 +21,11 @@ import * as HashgraphProto from "@hashgraph/proto"; // eslint-disable-next-line @typescript-eslint/no-unused-vars import Long from "long"; + +/** + * A set of values the nodes use in determining transaction and query fees, and + * constants involved in fee calculations. + */ export default class FeeComponents { /** * @param {object} [props] diff --git a/src/FeeData.js b/src/FeeData.js index 4233520a6..5181e7445 100644 --- a/src/FeeData.js +++ b/src/FeeData.js @@ -22,6 +22,22 @@ import * as HashgraphProto from "@hashgraph/proto"; import FeeComponents from "./FeeComponents.js"; import FeeDataType from "./FeeDataType.js"; +/** + * A total fee, in component amounts charged for a transaction. + * + * Total fees are composed of three sets of components. + * - Node data, components that compensate the specific node that submitted + * the transaction. + * - Network data, components that compensate the Hedera network for gossiping + * the transaction and determining the consensus timestamp. + * - Service data, components that compensate the Hedera network for the ongoing + * maintenance and operation of the network, as well as ongoing development + * of network services. + * + * Fee components are recorded in thousandths of a tiny cent, and the network + * exchange rate converts these to tinybar amounts, which are what the network + * charges for transactions and what the network reports in the record stream. + */ export default class FeeData { /** * @param {object} [props] diff --git a/src/FeeSchedule.js b/src/FeeSchedule.js index a8fa7a922..30b0443a1 100644 --- a/src/FeeSchedule.js +++ b/src/FeeSchedule.js @@ -22,6 +22,10 @@ import * as HashgraphProto from "@hashgraph/proto"; import TransactionFeeSchedule from "./TransactionFeeSchedule.js"; import Timestamp from "./Timestamp.js"; +/** + * A set of fee schedules covering all transaction types and query types, along + * with a specific time at which this fee schedule will expire. + */ export default class FeeSchedule { /** * @param {object} [props] diff --git a/src/FeeSchedules.js b/src/FeeSchedules.js index 065f6c8ae..f62d5060e 100644 --- a/src/FeeSchedules.js +++ b/src/FeeSchedules.js @@ -21,6 +21,11 @@ import * as HashgraphProto from "@hashgraph/proto"; import FeeSchedule from "./FeeSchedule.js"; +/** + * Represents a pair of fee schedules on the Hedera network - the currently active fee schedule + * and the next upcoming fee schedule. This structure allows for transparent fee updates by making + * future fee changes visible before they take effect. + */ export default class FeeSchedules { /** * @param {object} [props] diff --git a/src/Hbar.js b/src/Hbar.js index 274321903..e7e39a872 100644 --- a/src/Hbar.js +++ b/src/Hbar.js @@ -28,6 +28,10 @@ import Long from "long"; * @typedef {import("./long.js").LongObject} LongObject */ +/** + * Represents a quantity of hbar (ℏ), the native currency of the Hedera network. + * Provides utilities for handling different hbar denominations and conversions. + */ export default class Hbar { /** * @param {number | string | Long | LongObject | BigNumber} amount diff --git a/src/HbarUnit.js b/src/HbarUnit.js index 64f3fc981..047b626c5 100644 --- a/src/HbarUnit.js +++ b/src/HbarUnit.js @@ -20,6 +20,12 @@ import BigNumber from "bignumber.js"; +/** + * Represents a unit of HBAR currency measurement in the Hedera network. + * Defines the various denominations of HBAR (tinybar, microbar, millibar, hbar, kilobar, megabar, gigabar) + * and provides utilities for converting between these units. Each unit has a name, symbol, and conversion + * rate to tinybar (the smallest unit of HBAR). + */ export default class HbarUnit { /** * @internal diff --git a/src/account/HbarAllowance.js b/src/account/HbarAllowance.js index 627b1ee30..0d7d8137d 100644 --- a/src/account/HbarAllowance.js +++ b/src/account/HbarAllowance.js @@ -36,6 +36,10 @@ import Hbar from "../Hbar.js"; * @typedef {import("../client/Client.js").default<*, *>} Client */ +/** + * Represents an HBAR allowance granted to a spender account by an owner account. + * This class manages the permissions for one account to spend HBAR on behalf of another account. + */ export default class HbarAllowance { /** * @internal diff --git a/src/client/NodeClient.js b/src/client/NodeClient.js index 4b2c3574e..1bf7b4fbb 100644 --- a/src/client/NodeClient.js +++ b/src/client/NodeClient.js @@ -77,6 +77,8 @@ export const MirrorNetwork = { /** * @augments {Client} + * Client for interacting with the Hedera network using Node.js. + * Extends the base Client class with Node.js specific implementations. */ export default class NodeClient extends Client { /** diff --git a/src/contract/ContractCreateTransaction.js b/src/contract/ContractCreateTransaction.js index 2b6644437..9ee84a325 100644 --- a/src/contract/ContractCreateTransaction.js +++ b/src/contract/ContractCreateTransaction.js @@ -49,6 +49,27 @@ import Key from "../Key.js"; * @typedef {import("../transaction/TransactionId.js").default} TransactionId */ +/** + * Create a new smart contract. + * + * If this transaction succeeds, the `ContractID` for the new smart contract + * SHALL be set in the transaction receipt.
+ * The contract is defined by the initial bytecode (or `initcode`). The + * `initcode` SHALL be stored either in a previously created file, or in the + * transaction body itself for very small contracts. + * + * As part of contract creation, the constructor defined for the new smart + * contract SHALL run with the parameters provided in the + * `constructorParameters` field.
+ * The gas to "power" that constructor MUST be provided via the `gas` field, + * and SHALL be charged to the payer for this transaction.
+ * If the contract _constructor_ stores information, it is charged gas for that + * storage. There is a separate fee in HBAR to maintain that storage until the + * expiration, and that fee SHALL be added to this transaction as part of the + * _transaction fee_, rather than gas. + * + */ + export default class ContractCreateTransaction extends Transaction { /** * @param {object} [props] diff --git a/src/contract/ContractDeleteTransaction.js b/src/contract/ContractDeleteTransaction.js index cb76439d9..bd10fcff7 100644 --- a/src/contract/ContractDeleteTransaction.js +++ b/src/contract/ContractDeleteTransaction.js @@ -42,6 +42,30 @@ import AccountId from "../account/AccountId.js"; * @typedef {import("../transaction/TransactionId.js").default} TransactionId */ +/** + * Delete a smart contract, and transfer any remaining HBAR balance to a + * designated account. + * + * If this call succeeds then all subsequent calls to that smart contract + * SHALL execute the `0x0` opcode, as required for EVM equivalence. + * + * ### Requirements + * - An account or smart contract MUST be designated to receive all remaining + * account balances. + * - The smart contract MUST have an admin key set. If the contract does not + * have `admin_key` set, then this transaction SHALL fail and response code + * `MODIFYING_IMMUTABLE_CONTRACT` SHALL be set. + * - If `admin_key` is, or contains, an empty `KeyList` key, it SHALL be + * treated the same as an admin key that is not set. + * - The `Key` set for `admin_key` on the smart contract MUST have a valid + * signature set on this transaction. + * - The designated receiving account MAY have `receiver_sig_required` set. If + * that field is set, the receiver account MUST also sign this transaction. + * - The field `permanent_removal` MUST NOT be set. That field is reserved for + * internal system use when purging the smart contract from state. Any user + * transaction with that field set SHALL be rejected and a response code + * `PERMANENT_REMOVAL_REQUIRES_SYSTEM_INITIATION` SHALL be set. + */ export default class ContractDeleteTransaction extends Transaction { /** * @param {object} [props] diff --git a/src/contract/ContractExecuteTransaction.js b/src/contract/ContractExecuteTransaction.js index dfccff350..c99e24259 100644 --- a/src/contract/ContractExecuteTransaction.js +++ b/src/contract/ContractExecuteTransaction.js @@ -53,6 +53,16 @@ import Long from "long"; * @property {ContractFunctionParameters} parameters */ +/** + * Call a function of a given smart contract, providing function parameter + * inputs as needed. + *

+ * Resource ("gas") charges SHALL include all relevant fees incurred by + * the contract execution, including any storage required.
+ * The total transaction fee SHALL incorporate all of the "gas" actually + * consumed as well as the standard fees for transaction handling, + * data transfers, signature verification, etc... + */ export default class ContractExecuteTransaction extends Transaction { /** * @param {object} [props] diff --git a/src/contract/ContractFunctionParameters.js b/src/contract/ContractFunctionParameters.js index b1f6156d7..f215a5b0d 100644 --- a/src/contract/ContractFunctionParameters.js +++ b/src/contract/ContractFunctionParameters.js @@ -33,6 +33,14 @@ import { arrayify } from "@ethersproject/bytes"; // eslint-disable-next-line @typescript-eslint/no-unused-vars import EvmAddress from "../EvmAddress.js"; +/** + * Class to help construct parameters for a Hedera smart contract function call. + * + * This class provides methods to add different types of parameters that will be passed to a smart contract function. + * It supports all Solidity parameter types including basic types (uint/int of various sizes, bool, address), + * arrays, strings, and bytes. + * + */ export default class ContractFunctionParameters { constructor() { /** diff --git a/src/contract/ContractFunctionSelector.js b/src/contract/ContractFunctionSelector.js index 03fea8f75..eaa628173 100644 --- a/src/contract/ContractFunctionSelector.js +++ b/src/contract/ContractFunctionSelector.js @@ -110,6 +110,13 @@ export const ArgumentType = { * @property {boolean} array */ +/** + * Class to help construct function selectors for Hedera smart contract function calls. + * Function selectors are the first 4 bytes of the Keccak-256 hash of the function's signature. + * + * This class provides methods to build function signatures by adding parameters of various Solidity types. + * It supports all standard Solidity parameter types and their array variants. + */ export default class ContractFunctionSelector { /** * @param {string} [name] diff --git a/src/contract/ContractInfoQuery.js b/src/contract/ContractInfoQuery.js index 27648c16f..e92d17ae6 100644 --- a/src/contract/ContractInfoQuery.js +++ b/src/contract/ContractInfoQuery.js @@ -42,6 +42,8 @@ import Hbar from "../Hbar.js"; */ /** + * * A query that returns information about a smart contract instance. + * This includes the account that it owns, the contract's bytecode, and the timestamp when it will expire. * @augments {Query} */ export default class ContractInfoQuery extends Query { diff --git a/src/contract/ContractUpdateTransaction.js b/src/contract/ContractUpdateTransaction.js index a8052734d..9ee87bf80 100644 --- a/src/contract/ContractUpdateTransaction.js +++ b/src/contract/ContractUpdateTransaction.js @@ -48,6 +48,14 @@ import Long from "long"; * @typedef {import("../transaction/TransactionId.js").default} TransactionId */ +/** + * Modify a smart contract.
+ * Any change other than updating the expiration time requires that the + * contract be modifiable (has a valid `adminKey`) and that the + * transaction be signed by the `adminKey` + *

+ * Fields _not set_ on the request SHALL NOT be modified. + */ export default class ContractUpdateTransaction extends Transaction { /** * @param {object} props diff --git a/src/contract/DelegateContractId.js b/src/contract/DelegateContractId.js index f1f055892..3c6752a4f 100644 --- a/src/contract/DelegateContractId.js +++ b/src/contract/DelegateContractId.js @@ -33,6 +33,10 @@ import * as hex from "../encoding/hex.js"; * @typedef {import("../client/Client.js").default<*, *>} Client */ +/** + * epresents a delegatable smart contract ID on the Hedera network. + * This class extends ContractId and provides additional functionality for delegatable contracts. + */ export default class DelegateContractId extends ContractId { /** * @param {number | Long | import("../EntityIdHelper").IEntityId} props diff --git a/src/file/FileContentsQuery.js b/src/file/FileContentsQuery.js index 130d0e762..c75f36005 100644 --- a/src/file/FileContentsQuery.js +++ b/src/file/FileContentsQuery.js @@ -40,6 +40,9 @@ import FileId from "./FileId.js"; /** * @augments {Query} + * Retrieve the content of a file in HFS.
+ * Note that this query retrieves _only_ the file content, not any of + * the metadata for the file. */ export default class FileContentsQuery extends Query { /** diff --git a/src/file/FileInfoQuery.js b/src/file/FileInfoQuery.js index d9a8b40ff..c07029ce9 100644 --- a/src/file/FileInfoQuery.js +++ b/src/file/FileInfoQuery.js @@ -43,6 +43,8 @@ import Hbar from "../Hbar.js"; /** * @augments {Query} + * Retrieve the metadata for a file in HFS.
+ * Note that this query does not retrieve the file _content_. */ export default class FileInfoQuery extends Query { /** diff --git a/src/system/FreezeTransaction.js b/src/system/FreezeTransaction.js index 28ac8830e..fe9bc8bfb 100644 --- a/src/system/FreezeTransaction.js +++ b/src/system/FreezeTransaction.js @@ -48,6 +48,16 @@ import FreezeType from "../FreezeType.js"; * @property {number} minute */ +/** + * Freeze, cancel, or prepare a freeze. + * This single transaction performs all of the functions supported + * by the network freeze service. These functions include actions to + * prepare an upgrade, prepare a telemetry upgrade, freeze the network, + * freeze the network for upgrade, or abort a scheduled freeze. + *

+ * The actual freeze action SHALL be determined by the `freeze_type` field + * of the `FreezeTransactionBody`.
+ */ export default class FreezeTransaction extends Transaction { /** * @param {object} [props] From cf31640f636da518064d55c42e0f02ed1f0d9280 Mon Sep 17 00:00:00 2001 From: Ivaylo Nikolov Date: Tue, 14 Jan 2025 17:06:02 +0200 Subject: [PATCH 3/4] docs: update airdrop transaction Signed-off-by: Ivaylo Nikolov --- src/token/TokenAirdropTransaction.js | 51 ++++++++++++++++++++++++++-- 1 file changed, 48 insertions(+), 3 deletions(-) diff --git a/src/token/TokenAirdropTransaction.js b/src/token/TokenAirdropTransaction.js index 74506b97a..fd18b06a6 100644 --- a/src/token/TokenAirdropTransaction.js +++ b/src/token/TokenAirdropTransaction.js @@ -46,10 +46,55 @@ import AbstractTokenTransferTransaction from "./AbstractTokenTransferTransaction */ /** - * A transaction that allows the transfer of tokens to multiple accounts in a single transaction. - * This is a more efficient way to distribute tokens to multiple accounts compared to individual - * token transfer transactions. + * Airdrop one or more tokens to one or more accounts. * + * ### Effects + * This distributes tokens from the balance of one or more sending account(s) + * to the balance of one or more recipient accounts. Accounts MAY receive the + * tokens in one of four ways. + * + * - An account already associated to the token to be distributed SHALL + * receive the airdropped tokens immediately to the recipient account + * balance.
+ * The fee for this transfer SHALL include the transfer, the airdrop fee, + * and any custom fees. + * - An account with available automatic association slots SHALL be + * automatically associated to the token, and SHALL immediately receive + * the airdropped tokens to the recipient account balance.
+ * The fee for this transfer SHALL include the transfer, the association, + * the cost to renew that association once, the airdrop fee, and + * any custom fees. + * - An account with "receiver signature required" set SHALL have a + * "Pending Airdrop" created and must claim that airdrop with a + * `claimAirdrop` transaction.
+ * The fee for this transfer SHALL include the transfer, the association, + * the cost to renew that association once, the airdrop fee, and + * any custom fees.
+ * If the pending airdrop is not claimed immediately, the `sender` SHALL + * pay the cost to renew the token association, and the cost to maintain + * the pending airdrop, until the pending airdrop is claimed or cancelled. + * - An account with no available automatic association slots SHALL have a + * "Pending Airdrop" created and must claim that airdrop with a + * `claimAirdrop` transaction.
+ * The fee for this transfer SHALL include the transfer, the association, + * the cost to renew that association once, the airdrop fee, and any custom + * fees.
+ * If the pending airdrop is not claimed immediately, the `sender` SHALL + * pay the cost to renew the token association, and the cost to maintain + * the pending airdrop, until the pending airdrop is claimed or cancelled. + * + * If an airdrop would create a pending airdrop for a fungible/common token, + * and a pending airdrop for the same sender, receiver, and token already + * exists, the existing pending airdrop SHALL be updated to add the new + * amount to the existing airdrop, rather than creating + * a new pending airdrop.
+ * Any airdrop that completes immediately SHALL be irreversible. Any airdrop + * that results in a "Pending Airdrop" MAY be canceled via a `cancelAirdrop` + * transaction.
+ * All transfer fees (including custom fees and royalties), as well as the + * rent cost for the first auto-renewal period for any automatic-association + * slot occupied by the airdropped tokens, SHALL be charged to the account + * paying for this transaction.
*/ export default class TokenAirdropTransaction extends AbstractTokenTransferTransaction { /** From f241c62c0f3174b15c97123877c46bae06c7cead Mon Sep 17 00:00:00 2001 From: Ivaylo Nikolov Date: Wed, 15 Jan 2025 14:53:41 +0200 Subject: [PATCH 4/4] fix: remove codecov reference Signed-off-by: Ivaylo Nikolov --- Taskfile.yml | 3 --- package.json | 4 +--- 2 files changed, 1 insertion(+), 6 deletions(-) diff --git a/Taskfile.yml b/Taskfile.yml index 210d0e57a..885a277a4 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -35,9 +35,6 @@ tasks: docs: cmds: - npx typedoc - --plugin typedoc-plugin-coverage - --coverageOutputType json - --logLevel Verbose --excludeInternal --excludePrivate --excludeProtected diff --git a/package.json b/package.json index 20bd61a87..49567c346 100644 --- a/package.json +++ b/package.json @@ -69,7 +69,6 @@ "pino-pretty": "^10.0.0", "protobufjs": "7.2.5", "rfc4648": "^1.5.3", - "typedoc-plugin-coverage": "^3.4.1", "utf8": "^3.0.0" }, "devDependencies": { @@ -129,6 +128,5 @@ "expo": { "optional": true } - }, - "packageManager": "pnpm@9.14.4+sha512.c8180b3fbe4e4bca02c94234717896b5529740a6cbadf19fa78254270403ea2f27d4e1d46a08a0f56c89b63dc8ebfd3ee53326da720273794e6200fcf0d184ab" + } }