Add more comments for documentation

README.md

@@ -47,7 +47,7 @@ import { MnemonicKey } from '@initia/initia.js'
 const key = new MnemonicKey({
     mnemonic: 'bird upset ...  evil cigar', // (optional) if null, generate a new Mnemonic key
     account: 0, // (optional) BIP44 account number. default = 0
-    index: 0, // (optional) BIP44 index number. defualt = 0
+    index: 0, // (optional) BIP44 index number. default = 0
     coinType: 118, // (optional) BIP44 coinType. default = 118
 })
 ```
@@ -111,7 +111,7 @@ import { MsgDelegate } from '@initia/initia.js'
 
 const msg = new MsgDelegate(
     'init1kdwzpz3wzvpdj90gtga4fw5zm9tk4cyrgnjauu', // delegator address
-    'init18sj3x80fdjc6gzfvwl7lf8sxcvuvqjpvcmp6np', // validator's operator addres
+    'init18sj3x80fdjc6gzfvwl7lf8sxcvuvqjpvcmp6np', // validator's operator address
     '100000uinit',                                 // delegate amount
 )
 ```
@@ -125,7 +125,7 @@ import { MsgUndelegate } from '@initia/initia.js'
 
 const msg = new MsgUndelegate(
     'init1kdwzpz3wzvpdj90gtga4fw5zm9tk4cyrgnjauu', // delegator address
-    'init18sj3x80fdjc6gzfvwl7lf8sxcvuvqjpvcmp6np', // validator's operator addres
+    'init18sj3x80fdjc6gzfvwl7lf8sxcvuvqjpvcmp6np', // validator's operator address
     '100000uinit',                                 // undelegate amount
 )
 ```

src/client/WebSocketClient.ts

@@ -136,7 +136,7 @@ export class WebSocketClient extends EventEmitter {
 
   /**
    * WebSocketClient constructor
-   * @param URL the websocket endpoint URL on the Tendermint RPC server.
+   * @param URL the websocket endpoint URL on the Tendermint RPC server
    *            Ex: ws://localhost:26657/websocket
    * @param reconnectCount 0 for not to attempt reconnect, -1 for infinite, > 0 for number of times to attempt
    * @param reconnectInterval retry interval in milliseconds

src/client/rest/RESTClient.ts

@@ -165,7 +165,9 @@ export class RESTClient {
     this.wasm = new WasmAPI(this.apiRequester)
   }
 
-  /** Creates a new wallet with the Key. */
+  /**
+   * Creates a new wallet with the Key.
+   */
   public wallet(key: Key): Wallet {
     return new Wallet(this, key)
   }

src/client/rest/api/IbcAPI.ts

@@ -180,7 +180,7 @@ export class IbcAPI extends BaseAPI {
 
   /**
    * Query the status of an IBC light client
-   * @param client_id client state unique ident.ifier
+   * @param client_id client state unique identifier
    */
   public async clientStatus(
     client_id: string,

src/client/rest/api/TxAPI.ts

@@ -409,7 +409,7 @@ export class TxAPI extends BaseAPI {
    * Broadcast the transaction using "sync" mode, then wait for its inclusion in a block.
    * This method polls txInfo using the txHash to confirm the transaction's execution.
    * @param tx transaction to broadcast
-   * @param timeout time in milliseconds to wait for transaction to be included in a block. defaults to 30000
+   * @param timeout time in milliseconds to wait for transaction to be included in a block (default: 30000)
    */
   public async broadcast(
     tx: Tx | string,

src/core/Coins.ts

@@ -210,7 +210,7 @@ export class Coins
   }
 
   /**
-   * Filters out the Coin objects that don't match the predicate
+   * Filters out the Coin objects that don't match the predicate.
    * @param fn predicate
    */
   public filter(fn: (c: Coin) => boolean): Coins {

src/core/PublicKey.ts

@@ -8,14 +8,20 @@ import { PubKey as ValConsPubKey_pb } from '@initia/initia.proto/cosmos/crypto/e
 import { PubKey as EthPubKey_pb } from '@initia/initia.proto/initia/crypto/v1beta1/ethsecp256k1/keys'
 import { bech32 } from 'bech32'
 
-// As discussed in https://github.com/binance-chain/javascript-sdk/issues/163
-// Prefixes listed here: https://github.com/tendermint/tendermint/blob/d419fffe18531317c28c29a292ad7d253f6cafdf/docs/spec/blockchain/encoding.md#public-key-cryptography
-// Last bytes is varint-encoded length prefix
+/**
+ * As discussed in https://github.com/binance-chain/javascript-sdk/issues/163
+ *
+ * Prefixes listed here: https://github.com/tendermint/tendermint/blob/d419fffe18531317c28c29a292ad7d253f6cafdf/docs/spec/blockchain/encoding.md#public-key-cryptography
+ *
+ * Last bytes is varint-encoded length prefix.
+ */
 const pubkeyAminoPrefixSecp256k1 = Buffer.from(
   'eb5ae987' + '21' /* fixed length */,
   'hex'
 )
-/** See https://github.com/tendermint/tendermint/commit/38b401657e4ad7a7eeb3c30a3cbf512037df3740 */
+/**
+ * See https://github.com/tendermint/tendermint/commit/38b401657e4ad7a7eeb3c30a3cbf512037df3740
+ */
 const pubkeyAminoPrefixMultisigThreshold = Buffer.from(
   '22c1f7e2' /* variable length not included */,
   'hex'
@@ -92,6 +98,13 @@ export namespace PublicKey {
   }
 }
 
+/**
+ * SimplePublicKey defines a secp256k1 public key.
+ * Key is the compressed form of the pubkey. The first byte depends is a 0x02 byte
+ * if the y-coordinate is the lexicographically largest of the two associated with
+ * the x-coordinate. Otherwise the first byte is a 0x03.
+ * This prefix is followed with the x-coordinate.
+ */
 export class SimplePublicKey extends JSONSerializable<
   SimplePublicKey.Amino,
   SimplePublicKey.Data,
@@ -175,6 +188,11 @@ export namespace SimplePublicKey {
   export type Proto = PubKey_pb
 }
 
+/**
+ * LegacyAminoMultisigPublicKey specifies a public key type
+ * which nests multiple public keys and a threshold.
+ * It uses legacy amino address rules.
+ */
 export class LegacyAminoMultisigPublicKey extends JSONSerializable<
   LegacyAminoMultisigPublicKey.Amino,
   LegacyAminoMultisigPublicKey.Data,
@@ -293,6 +311,13 @@ export namespace LegacyAminoMultisigPublicKey {
   export type Proto = LegacyAminoPubKey_pb
 }
 
+/**
+ * ValConsPublicKey is an ed25519 public key for handling Tendermint keys in SDK.
+ * It's needed for Any serialization and SDK compatibility.
+ * It must not be used in a non Tendermint key context because it doesn't implement
+ * ADR-28. Nevertheless, you will like to use ed25519 in app user level
+ * then you must create a new proto message and follow ADR-28 for Address construction.
+ */
 export class ValConsPublicKey extends JSONSerializable<
   ValConsPublicKey.Amino,
   ValConsPublicKey.Data,
@@ -371,6 +396,10 @@ export namespace ValConsPublicKey {
   export type Proto = ValConsPubKey_pb
 }
 
+/**
+ * EthPublicKey defines a type alias for an ecdsa.PublicKey that implements Tendermint's PubKey interface.
+ * It represents the 33-byte compressed public key format.
+ */
 export class EthPublicKey extends JSONSerializable<
   EthPublicKey.Amino,
   EthPublicKey.Data,

src/core/authz/authorizations/Authorization.ts

@@ -23,8 +23,7 @@ export class AuthorizationGrant extends JSONSerializable<
 > {
   /**
    * @param authorization
-   * @param expiration time when the grant will expire and will be pruned. If null, then the grant
-   * doesn't have a time expiration
+   * @param expiration time when the grant will expire and will be pruned (null to disable)
    */
   constructor(
     public authorization: Authorization,

src/core/authz/authorizations/ExecuteAuthorization.ts

@@ -78,6 +78,9 @@ export class ExecuteAuthorization extends JSONSerializable<
   }
 }
 
+/**
+ * ExecuteAuthorizationItem is the information for granting module execution.
+ */
 export class ExecuteAuthorizationItem extends JSONSerializable<
   any,
   ExecuteAuthorizationItem.Data,

src/core/authz/authorizations/StakeAuthorization.ts

@@ -121,6 +121,9 @@ export class StakeAuthorization extends JSONSerializable<
   }
 }
 
+/**
+ * StakeAuthorizationValidators defines list of validator addresses.
+ */
 export class StakeAuthorizationValidators extends JSONSerializable<
   StakeAuthorizationValidators.Amino,
   StakeAuthorizationValidators.Data,

src/core/bank/msgs/MsgSetSendEnabled.ts

@@ -19,7 +19,7 @@ export class MsgSetSendEnabled extends JSONSerializable<
   /**
    * @param authority
    * @param send_enabled the list of entries to add or update
-   * @param use_default_for a list of denoms that should use the params.default_send_enabled value
+   * @param use_default_for a list of denoms that should use the default_send_enabled value
    */
   constructor(
     public authority: AccAddress,

src/core/bech32.ts

@@ -148,7 +148,7 @@ export namespace ValPubKey {
 
 export namespace ValConsAddress {
   /**
-   * Checks if a string is a Initia validator consensus address
+   * Checks if a string is a Initia validator consensus address.
    * @param data string to check
    */
 

src/core/evm/EvmParams.ts

@@ -10,7 +10,7 @@ export class EvmParams extends JSONSerializable<
   EvmParams.Proto
 > {
   /**
-   * @param extra_eips the additional EIPs for the vm.Config
+   * @param extra_eips the additional EIPs for the config
    * @param allowed_publishers list of addresses with permission to distribute contracts
    * @param allow_custom_erc20 whether the chain allows custom erc20 tokens to be registered on cosmos bank interface
    * @param allowed_custom_erc20s

src/core/feegrant/allowances/AllowedMsgAllowance.ts

@@ -13,8 +13,8 @@ export class AllowedMsgAllowance extends JSONSerializable<
   AllowedMsgAllowance.Proto
 > {
   /**
-   * @param allowance any of basic and periodic fee allowance.
-   * @param allowed_messages the messages for which the grantee has the access.
+   * @param allowance any of basic and periodic fee allowance
+   * @param allowed_messages the messages for which the grantee has the access
    */
   constructor(
     public allowance: BasicAllowance | PeriodicAllowance,

src/core/gov/GovParams.ts

@@ -19,21 +19,21 @@ export class GovParams extends JSONSerializable<
 
   /**
    * @param min_deposit min deposit for a proposal to enter voting period
-   * @param max_deposit_period max period for holders to deposit on a proposal. Initial value: 2 months
+   * @param max_deposit_period max period for holders to deposit on a proposal (initial value: 2 months)
    * @param voting_period duration of the voting period
    * @param quorum min percentage of total stake needed to vote for a result to be considered valid
-   * @param threshold min proportion of Yes votes for proposal to pass. Default value: 0.5
-   * @param veto_threshold min value of Veto votes to Total votes ratio for proposal to be vetoed. Default value: 1/3
+   * @param threshold min proportion of Yes votes for proposal to pass (default: 0.5)
+   * @param veto_threshold min value of Veto votes to Total votes ratio for proposal to be vetoed (default: 1/3)
    * @param min_initial_deposit_ratio the ratio representing the proportion of the deposit value that must be paid at proposal submission
    * @param proposal_cancel_ratio the cancel ratio which will not be returned back to the depositors when a proposal is cancelled
    * @param proposal_cancel_dest the address which will receive (proposal_cancel_ratio * deposit) proposal deposits; If empty, the proposal deposits will be burned
    * @param expedited_voting_period duration of the voting period of an expedited proposal
-   * @param expedited_threshold min proportion of Yes votes for proposal to pass. Default value: 0.67
+   * @param expedited_threshold min proportion of Yes votes for proposal to pass (default: 0.67)
    * @param expedited_min_deposit min expedited deposit for a proposal to enter voting period
    * @param burn_vote_quorum burn deposits if a proposal does not meet quorum
    * @param burn_proposal_deposit_prevote burn deposits if the proposal does not enter voting period
    * @param burn_vote_veto burn deposits if quorum with vote type no_veto is met
-   * @param min_deposit_ratio the proportion of the deposit value minimum that must be met when making a deposit. Default value: 0.01
+   * @param min_deposit_ratio the proportion of the deposit value minimum that must be met when making a deposit (default: 0.01)
    * @param emergency_min_deposit min deposit for a emergency proposal to enter voting period
    * @param emergency_tally_interval tally interval for emergency proposal
    * @param low_threshold_functions low threshold functions for emergency and expedited proposal

src/core/gov/Vote.ts

@@ -106,6 +106,9 @@ export namespace Vote {
   export type Proto = Vote_pb
 }
 
+/**
+ * WeightedVoteOption defines a unit of vote for vote split.
+ */
 export class WeightedVoteOption extends JSONSerializable<
   WeightedVoteOption.Amino,
   WeightedVoteOption.Data,

src/core/ibc/applications/fee/IbcFee.ts

@@ -3,19 +3,17 @@ import { Coins } from '../../../Coins'
 import { JSONSerializable } from '../../../../util/json'
 
 /**
- * Fee defines the ICS29 receive, acknowledgement and timeout fees
+ * Fee defines the ICS29 receive, acknowledgement and timeout fees.
  */
 export class IbcFee extends JSONSerializable<
   IbcFee.Amino,
   IbcFee.Data,
   IbcFee.Proto
 > {
-  /** the packet receive fee */
   public recv_fee: Coins
-  /** the packet acknowledgement fee */
   public ack_fee: Coins
-  /** the packet timeout fee */
   public timeout_fee: Coins
+
   /**
    * @param recv_fee the packet receive fee
    * @param ack_fee the packet acknowledgement fee

src/core/ibc/applications/fee/IdentifiedPacketFee.ts

@@ -4,7 +4,7 @@ import { PacketFee } from './PacketFee'
 import { PacketId } from '../../core/channel/PacketId'
 
 /**
- * IdentifiedPacketFees contains a list of type PacketFee and associated PacketId
+ * IdentifiedPacketFees contains a list of type PacketFee and associated PacketId.
  */
 export class IdentifiedPacketFees extends JSONSerializable<
   IdentifiedPacketFees.Amino,

src/core/ibc/applications/fee/Metadata.ts

@@ -2,7 +2,7 @@ import { Metadata as Metadata_pb } from '@initia/initia.proto/ibc/applications/f
 import { JSONSerializable } from '../../../../util/json'
 
 /**
- * Metadata defines the ICS29 channel specific metadata encoded into the channel version bytestring
+ * Metadata defines the ICS29 channel specific metadata encoded into the channel version bytestring.
  * See ICS004: https://github.com/cosmos/ibc/tree/master/spec/core/ics-004-channel-and-packet-semantics#Versioning
  */
 export class Metadata extends JSONSerializable<

src/core/ibc/applications/fee/PacketFee.ts

@@ -4,7 +4,7 @@ import { IbcFee } from './IbcFee'
 import { AccAddress } from '../../../..'
 
 /**
- * PacketFee contains ICS29 relayer fees, refund address and optional list of permitted relayers
+ * PacketFee contains ICS29 relayer fees, refund address and optional list of permitted relayers.
  */
 export class PacketFee extends JSONSerializable<
   PacketFee.Amino,

src/core/ibc/applications/fee/msgs/MsgPayPacketFee.ts

@@ -4,8 +4,10 @@ import { MsgPayPacketFee as MsgPayPacketFee_pb } from '@initia/initia.proto/ibc/
 import { IbcFee } from '../IbcFee'
 
 /**
- * MsgPayPacketFee defines the request type for the PayPacketFee rpc
- * This Msg can be used to pay for a packet at the next sequence send & should be combined with the Msg that will be paid for
+ * MsgPayPacketFee is an open callback that may be called by any module/user that wishes to escrow funds in order to
+ * incentivize the relaying of the packet at the next sequence.
+ * NOTE: This method is intended to be used within a multi msg transaction, where the subsequent msg that follows
+ * initiates the lifecycle of the incentivized packet.
  */
 export class MsgPayPacketFee extends JSONSerializable<
   any,

src/core/ibc/applications/fee/msgs/MsgPayPacketFeeAsync.ts

@@ -5,8 +5,8 @@ import { PacketId } from '../../../core/channel/PacketId'
 import { PacketFee } from '../PacketFee'
 
 /**
- * MsgPayPacketFeeAsync defines the request type for the PayPacketFeeAsync rpc
- * This Msg can be used to pay for a packet at a specified sequence (instead of the next sequence send)
+ * MsgPayPacketFeeAsync is an open callback that may be called by any module/user that wishes to escrow funds in order to
+ * incentivize the relaying of a known packet (i.e. at a particular sequence).
  */
 export class MsgPayPacketFeeAsync extends JSONSerializable<
   any,

src/core/ibc/applications/fee/msgs/MsgRegisterCounterpartyPayee.ts

@@ -3,7 +3,10 @@ import { Any } from '@initia/initia.proto/google/protobuf/any'
 import { MsgRegisterCounterpartyPayee as MsgRegisterCounterpartyPayee_pb } from '@initia/initia.proto/ibc/applications/fee/v1/tx'
 
 /**
- * MsgRegisterCounterpartyPayee defines the request type for the RegisterCounterpartyPayee rpc
+ * MsgRegisterCounterpartyPayee is called by the relayer on each channelEnd and allows them to specify the counterparty
+ * payee address before relaying. This ensures they will be properly compensated for forward relaying since
+ * the destination chain must include the registered counterparty payee address in the acknowledgement. This function
+ * may be called more than once by a relayer, in which case, the latest counterparty payee address is always used.
  */
 export class MsgRegisterCounterpartyPayee extends JSONSerializable<
   any,

src/core/ibc/applications/fee/msgs/MsgRegisterPayee.ts

@@ -3,7 +3,10 @@ import { Any } from '@initia/initia.proto/google/protobuf/any'
 import { MsgRegisterPayee as MsgRegisterPayee_pb } from '@initia/initia.proto/ibc/applications/fee/v1/tx'
 
 /**
- * MsgRegisterPayee defines the request type for the RegisterPayee rpc
+ * MsgRegisterPayee is called by the relayer on each channelEnd and allows them to set an optional
+ * payee to which reverse and timeout relayer packet fees will be paid out. The payee should be registered on
+ * the source chain from which packets originate as this is where fee distribution takes place. This function may be
+ * called more than once by a relayer, in which case, the latest payee is always used.
  */
 export class MsgRegisterPayee extends JSONSerializable<
   any,

src/core/ibc/applications/interchain-account/Account.ts

@@ -3,7 +3,7 @@ import { BaseAccount } from '../../../..'
 import { JSONSerializable } from '../../../../util/json'
 
 /**
- * An InterchainAccount is defined as a BaseAccount & the address of the account owner on the controller chain
+ * An InterchainAccount is defined as a BaseAccount & the address of the account owner on the controller chain.
  */
 export class InterchainAccount extends JSONSerializable<
   InterchainAccount.Amino,

src/core/ibc/applications/interchain-account/Metadata.ts

@@ -2,7 +2,7 @@ import { Metadata as Metadata_pb } from '@initia/initia.proto/ibc/applications/i
 import { JSONSerializable } from '../../../../util/json'
 
 /**
- * Metadata defines a set of protocol specific data encoded into the ICS27 channel version bytestring
+ * Metadata defines a set of protocol specific data encoded into the ICS27 channel version bytestring.
  * See ICS004: https://github.com/cosmos/ibc/tree/master/spec/core/ics-004-channel-and-packet-semantics#Versioning
  */
 export class Metadata extends JSONSerializable<

src/core/ibc/applications/interchain-account/host/Params.ts

@@ -11,7 +11,7 @@ export class Params extends JSONSerializable<
   Params.Proto
 > {
   /**
-   * @param host_enabled host_enabled enables or disables the host submodule.
+   * @param host_enabled host_enabled enables or disables the host submodule
    */
   constructor(
     public host_enabled: boolean,

src/core/ibc/applications/nft-transfer/NftClassTrace.ts

@@ -1,6 +1,9 @@
 import { ClassTrace as NftClassTrace_pb } from '@initia/initia.proto/ibc/applications/nft_transfer/v1/types'
 import { JSONSerializable } from '../../../../util/json'
 
+/**
+ * NftClassTrace contains the base class id for ICS721 non fungible tokens and the source tracing information path.
+ */
 export class NftClassTrace extends JSONSerializable<
   NftClassTrace.Amino,
   NftClassTrace.Data,

src/core/ibc/applications/nft-transfer/NonFungibleTokenPacketData.ts

@@ -2,7 +2,7 @@ import { NonFungibleTokenPacketData as NonFungibleTokenPacketData_pb } from '@in
 import { JSONSerializable } from '../../../../util/json'
 
 /**
- * NonFungibleTokenPacketData defines a struct for the packet payload
+ * NonFungibleTokenPacketData defines a struct for the packet payload.
  * See NonFungibleTokenPacketData spec:
  * https://github.com/cosmos/ibc/tree/main/spec/app/ics-721-nft-transfer
  */