@aptos-labs/ts-sdk 1.29.1 → 1.30.0

package/src/internal/ans.ts

@@ -29,9 +29,11 @@ export const VALIDATION_RULES_DESCRIPTION = [
 ].join(" ");
 
 /**
+ * Validate if a given fragment is a valid ANS segment.
+ * This function checks the length and character constraints of the fragment to ensure it meets the ANS standards.
  *
- * @param fragment A fragment of a name, either the domain or subdomain
- * @returns boolean indicating if the fragment is a valid fragment
+ * @param fragment - A fragment of a name, either the domain or subdomain.
+ * @returns A boolean indicating if the fragment is a valid fragment.
  */
 export function isValidANSSegment(fragment: string): boolean {
   if (!fragment) return false;
@@ -43,9 +45,9 @@ export function isValidANSSegment(fragment: string): boolean {
 }
 
 /**
- * Checks if an ANS name is valid or not
+ * Checks if an ANS name is valid or not.
  *
- * @param name A string of the domain name, can include or exclude the .apt suffix
+ * @param name - A string of the domain name, which can include or exclude the .apt suffix.
  */
 export function isValidANSName(name: string): { domainName: string; subdomainName?: string } {
   const [first, second, ...rest] = name.replace(/\.apt$/, "").split(".");
@@ -68,21 +70,22 @@ export function isValidANSName(name: string): { domainName: string; subdomainNam
   };
 }
 
+/**
+ * Policy for determining how subdomains expire in relation to their parent domain.
+ */
 export enum SubdomainExpirationPolicy {
   Independent = 0,
   FollowsDomain = 1,
 }
 
 /**
- * A helper function to determine if a given ANS name is considered active or
- * not. Domains are considered active if their expiration date is in the
- * future. Subdomains have two policies which modify their behavior. They can
- * follow their parent's expiration (1) in which they ignore their own
- * expiration timestamp or they can expire independently (0) in which they can
- * expire before their parent but not afterwards.
- *
- * @param name - An ANS name returned from one of the functions of the SDK
- * @returns A boolean representing if the contract considers the name active or not
+ * Determine if a given ANS name is considered active based on its expiration dates.
+ * Domains are active if their expiration date is in the future, while subdomains may
+ * follow their parent's expiration policy (1) or expire independently (0).
+ * If the subdomain is expiring independently, it can expire before their parent, but not after.
+ *
+ * @param name - An ANS name returned from one of the functions of the SDK.
+ * @returns A boolean indicating whether the contract considers the name active or not.
  */
 export function isActiveANSName(name: GetANSNameResponse[0]): boolean {
   if (!name) return false;
@@ -115,6 +118,14 @@ const NetworkToAnsContract: Record<Network, string | null> = {
   [Network.DEVNET]: null,
 };
 
+/**
+ * Retrieves the address of the ANS contract based on the specified Aptos network configuration.
+ *
+ * @param aptosConfig - The configuration object for the Aptos network.
+ * @param aptosConfig.network - The network for which to retrieve the ANS contract address.
+ *
+ * @throws Throws an error if the ANS contract is not deployed to the specified network.
+ */
 function getRouterAddress(aptosConfig: AptosConfig): string {
   const address = NetworkToAnsContract[aptosConfig.network];
   if (!address) throw new Error(`The ANS contract is not deployed to ${aptosConfig.network}`);
@@ -129,6 +140,14 @@ const unwrapOption = <T>(option: any): T | undefined => {
   return undefined;
 };
 
+/**
+ * Retrieve the owner address of a specified domain or subdomain.
+ *
+ * @param args - The arguments for retrieving the owner address.
+ * @param args.aptosConfig - The Aptos configuration object.
+ * @param args.name - The name of the domain or subdomain to query.
+ * @returns The account address of the owner, or undefined if not found.
+ */
 export async function getOwnerAddress(args: {
   aptosConfig: AptosConfig;
   name: string;
@@ -150,6 +169,14 @@ export async function getOwnerAddress(args: {
   return owner ? AccountAddress.from(owner) : undefined;
 }
 
+/**
+ * Parameters for registering a name in the Aptos network.
+ *
+ * @param aptosConfig - Configuration settings for the Aptos network.
+ * @param sender - The account initiating the name registration.
+ * @param name - The name to be registered.
+ * @param expiration - The expiration policy for the name registration.
+ */
 export interface RegisterNameParameters {
   aptosConfig: AptosConfig;
   sender: Account;
@@ -164,6 +191,26 @@ export interface RegisterNameParameters {
   options?: InputGenerateTransactionOptions;
 }
 
+/**
+ * Registers a domain or subdomain with the specified parameters. This function ensures that the provided names and expiration
+ * policies are valid before proceeding with the registration process.
+ *
+ * @param args - The parameters required for registering a name.
+ * @param args.aptosConfig - The configuration settings for Aptos.
+ * @param args.expiration - The expiration details for the registration.
+ * @param args.name - The name to be registered, which can be a domain or subdomain.
+ * @param args.sender - The account details of the sender initiating the registration.
+ * @param args.targetAddress - The target address for the registration.
+ * @param args.toAddress - The address to which the registration is associated.
+ * @param args.options - Additional options for the registration process.
+ * @param args.transferable - Indicates whether the registered name is transferable.
+ *
+ * @throws Error if the provided expiration policy is invalid for subdomains.
+ * @throws Error if the domain does not exist.
+ * @throws Error if the subdomain expiration time exceeds the domain expiration time.
+ *
+ * @returns A transaction object representing the registration process.
+ */
 export async function registerName(args: RegisterNameParameters): Promise<SimpleTransaction> {
   const { aptosConfig, expiration, name, sender, targetAddress, toAddress, options, transferable } = args;
   const routerAddress = getRouterAddress(aptosConfig);
@@ -242,6 +289,14 @@ export async function registerName(args: RegisterNameParameters): Promise<Simple
   return transaction;
 }
 
+/**
+ * Retrieves the expiration time of a specified domain or subdomain in epoch milliseconds.
+ *
+ * @param args - The arguments for the function.
+ * @param args.aptosConfig - The configuration object for Aptos.
+ * @param args.name - The name of the domain or subdomain to check.
+ * @returns The expiration time in epoch milliseconds, or undefined if an error occurs.
+ */
 export async function getExpiration(args: { aptosConfig: AptosConfig; name: string }): Promise<number | undefined> {
   const { aptosConfig, name } = args;
   const routerAddress = getRouterAddress(aptosConfig);
@@ -263,6 +318,15 @@ export async function getExpiration(args: { aptosConfig: AptosConfig; name: stri
   }
 }
 
+/**
+ * Retrieves the primary name associated with a given account address.
+ * This function helps in obtaining the complete domain name by combining the subdomain and domain names.
+ *
+ * @param args - The arguments for retrieving the primary name.
+ * @param args.aptosConfig - The Aptos configuration object.
+ * @param args.address - The account address for which to retrieve the primary name.
+ * @returns The primary name as a string, or undefined if no domain name exists.
+ */
 export async function getPrimaryName(args: {
   aptosConfig: AptosConfig;
   address: AccountAddressInput;
@@ -286,6 +350,17 @@ export async function getPrimaryName(args: {
   return [subdomainName, domainName].filter(Boolean).join(".");
 }
 
+/**
+ * Sets the primary name for the specified account, allowing for the association of a domain or subdomain with the account.
+ * If no name is provided, it clears the existing primary name.
+ *
+ * @param args - The arguments for setting the primary name.
+ * @param args.aptosConfig - The Aptos configuration object.
+ * @param args.sender - The account that is sending the transaction.
+ * @param args.name - The name to set as the primary name. If omitted, the function will clear the primary name.
+ * @param args.options - Optional transaction generation options.
+ * @returns A transaction object representing the operation.
+ */
 export async function setPrimaryName(args: {
   aptosConfig: AptosConfig;
   sender: Account;
@@ -324,6 +399,14 @@ export async function setPrimaryName(args: {
   return transaction;
 }
 
+/**
+ * Retrieves the target address associated with a given domain name and subdomain name.
+ *
+ * @param args - The arguments for retrieving the target address.
+ * @param args.aptosConfig - The Aptos configuration object.
+ * @param args.name - The name of the domain, which may include a subdomain.
+ * @returns The target address as an AccountAddress, or undefined if not found.
+ */
 export async function getTargetAddress(args: {
   aptosConfig: AptosConfig;
   name: string;
@@ -344,6 +427,19 @@ export async function getTargetAddress(args: {
   return target ? AccountAddress.from(target) : undefined;
 }
 
+/**
+ * Sets the target address for a specified domain and subdomain in the Aptos network.
+ * This function helps to associate a given address with a domain name, allowing for easier access and management of resources.
+ *
+ * @param args - The arguments for setting the target address.
+ * @param args.aptosConfig - The configuration settings for the Aptos network.
+ * @param args.sender - The account that is sending the transaction.
+ * @param args.name - The name of the domain or subdomain to be set.
+ * @param args.address - The address to be associated with the domain or subdomain.
+ * @param args.options - Optional parameters for generating the transaction.
+ *
+ * @returns A transaction object representing the set target address operation.
+ */
 export async function setTargetAddress(args: {
   aptosConfig: AptosConfig;
   sender: Account;
@@ -368,6 +464,14 @@ export async function setTargetAddress(args: {
   return transaction;
 }
 
+/**
+ * Retrieves the active Aptos name associated with the specified domain and subdomain.
+ *
+ * @param args - The parameters for the function.
+ * @param args.aptosConfig - The configuration object for Aptos.
+ * @param args.name - The name to look up, which includes the domain and optional subdomain.
+ * @returns The active Aptos name if it exists; otherwise, returns undefined.
+ */
 export async function getName(args: {
   aptosConfig: AptosConfig;
   name: string;
@@ -401,14 +505,38 @@ export async function getName(args: {
   return isActiveANSName(res) ? res : undefined;
 }
 
+/**
+ * Options for querying names, including pagination, ordering, and filtering criteria.
+ *
+ * @param options - Pagination and filtering options for the query.
+ */
 interface QueryNamesOptions {
   options?: PaginationArgs & OrderByArg<GetANSNameResponse[0]> & WhereArg<CurrentAptosNamesBoolExp>;
 }
 
+/**
+ * Arguments for retrieving account names based on the specified account address.
+ *
+ * @param accountAddress - The address of the account for which names are to be retrieved.
+ */
 export interface GetAccountNamesArgs extends QueryNamesOptions {
   accountAddress: AccountAddressInput;
 }
 
+/**
+ * Retrieves the current Aptos names associated with a specific account address.
+ *
+ * @param args - The arguments for retrieving account names.
+ * @param args.aptosConfig - The configuration object for Aptos.
+ * @param args.options - Optional parameters for querying account names.
+ * @param args.options.limit - The maximum number of names to retrieve.
+ * @param args.options.offset - The number of names to skip before starting to collect the result set.
+ * @param args.options.orderBy - The field by which to order the results.
+ * @param args.options.where - Additional conditions to filter the results.
+ * @param args.accountAddress - The address of the account for which to retrieve names.
+ *
+ * @returns An array of sanitized Aptos names associated with the specified account address.
+ */
 export async function getAccountNames(
   args: { aptosConfig: AptosConfig } & GetAccountNamesArgs,
 ): Promise<GetANSNameResponse> {
@@ -437,10 +565,31 @@ export async function getAccountNames(
   return data.current_aptos_names.map(sanitizeANSName);
 }
 
+/**
+ * Arguments for retrieving the domains associated with a specific account.
+ *
+ * @param accountAddress - The address of the account for which to fetch domains.
+ */
 export interface GetAccountDomainsArgs extends QueryNamesOptions {
   accountAddress: AccountAddressInput;
 }
 
+/**
+ * Retrieves the list of top-level domains owned by a specified account.
+ *
+ * @param args - The arguments for retrieving account domains.
+ * @param args.aptosConfig - The Aptos configuration object.
+ * @param args.options - Optional parameters for the query.
+ * @param args.options.limit - The maximum number of results to return.
+ * @param args.options.offset - The number of results to skip before starting to collect the result set.
+ * @param args.options.orderBy - The field by which to order the results.
+ * @param args.options.where - Additional conditions to filter the results.
+ * @param args.options.where.owner_address - The address of the account whose domains are being queried.
+ * @param args.options.where.expiration_timestamp - The minimum expiration timestamp for the domains.
+ * @param args.options.where.subdomain - The specific subdomain to filter by.
+ *
+ * @returns An array of sanitized domain names owned by the specified account.
+ */
 export async function getAccountDomains(
   args: { aptosConfig: AptosConfig } & GetAccountDomainsArgs,
 ): Promise<GetANSNameResponse> {
@@ -470,10 +619,31 @@ export async function getAccountDomains(
   return data.current_aptos_names.map(sanitizeANSName);
 }
 
+/**
+ * Arguments for retrieving subdomains associated with a specific account.
+ *
+ * @param accountAddress - The address of the account for which to fetch subdomains.
+ */
 export interface GetAccountSubdomainsArgs extends QueryNamesOptions {
   accountAddress: AccountAddressInput;
 }
 
+/**
+ * Retrieves a list of subdomains owned by a specified account address.
+ * This function helps you identify all subdomains associated with a given account.
+ *
+ * @param args - The arguments for retrieving account subdomains.
+ * @param args.aptosConfig - The configuration object for Aptos.
+ * @param args.options - Optional parameters for the query.
+ * @param args.options.limit - The maximum number of results to return.
+ * @param args.options.offset - The number of results to skip before starting to collect the result set.
+ * @param args.options.orderBy - The field by which to order the results.
+ * @param args.options.where - Additional conditions to filter the results.
+ * @param args.options.where.owner_address - The address of the account to filter by.
+ * @param args.options.where.expiration_timestamp - The expiration timestamp to filter by.
+ * @param args.options.where.subdomain - The subdomain condition to filter by.
+ * @param args.accountAddress - The address of the account whose subdomains are being queried.
+ */
 export async function getAccountSubdomains(
   args: { aptosConfig: AptosConfig } & GetAccountSubdomainsArgs,
 ): Promise<GetANSNameResponse> {
@@ -503,10 +673,29 @@ export async function getAccountSubdomains(
   return data.current_aptos_names.map(sanitizeANSName);
 }
 
+/**
+ * Arguments for retrieving subdomains associated with a specific domain.
+ *
+ * @param domain - The domain for which to fetch subdomains.
+ */
 export interface GetDomainSubdomainsArgs extends QueryNamesOptions {
   domain: string;
 }
 
+/**
+ * Retrieve the active subdomains associated with a specified domain.
+ *
+ * @param args - The arguments for retrieving subdomains.
+ * @param args.aptosConfig - The configuration settings for Aptos.
+ * @param args.options - Optional parameters for the query.
+ * @param args.options.limit - The maximum number of results to return.
+ * @param args.options.offset - The number of results to skip before starting to collect the results.
+ * @param args.options.orderBy - The field by which to order the results.
+ * @param args.options.where - Additional conditions to filter the results.
+ * @param args.domain - The domain for which to retrieve subdomains.
+ *
+ * @returns An array of active subdomain names.
+ */
 export async function getDomainSubdomains(
   args: { aptosConfig: AptosConfig } & GetDomainSubdomainsArgs,
 ): Promise<GetANSNameResponse> {
@@ -541,8 +730,9 @@ export async function getDomainSubdomains(
  * without others taking ownership of the name. At the time of writing, the
  * contract specified 30 days.
  *
- * @param args.aptosConfig an AptosConfig object
- * @returns
+ * @param args - The arguments for the function.
+ * @param args.aptosConfig - An AptosConfig object containing the configuration settings.
+ * @returns The expiration date in ISO 8601 format.
  */
 async function getANSExpirationDate(args: { aptosConfig: AptosConfig }): Promise<string> {
   const { aptosConfig } = args;
@@ -561,6 +751,17 @@ async function getANSExpirationDate(args: { aptosConfig: AptosConfig }): Promise
   return new Date(now().setDate(now().getDate() - gracePeriodInDays)).toISOString();
 }
 
+/**
+ * Renews a domain for a specified duration. This function allows you to extend the registration of a domain for one year.
+ *
+ * @param args - The parameters required to renew the domain.
+ * @param args.aptosConfig - The configuration settings for Aptos.
+ * @param args.sender - The account that is sending the renewal transaction.
+ * @param args.name - The name of the domain to renew.
+ * @param args.years - The number of years to renew the domain for. Currently, only 1 year renewals are supported. (optional, default is 1)
+ * @param args.options - Additional options for generating the transaction. (optional)
+ * @throws Error if the name contains a subdomain or if the years parameter is not equal to 1.
+ */
 export async function renewDomain(args: {
   aptosConfig: AptosConfig;
   sender: Account;
@@ -599,6 +800,9 @@ export async function renewDomain(args: {
  * epoch milliseconds. This function converts the ISO string to epoch
  * milliseconds. In the future, if other properties need sanitization, this can
  * be extended.
+ *
+ * @param name - The ANS name response to sanitize.
+ * @param name.expiration_timestamp - The expiration timestamp in ISO string format.
  */
 function sanitizeANSName(name: GetANSNameResponse[0]): GetANSNameResponse[0] {
   return {

package/src/internal/coin.ts

@@ -12,6 +12,18 @@ const coinTransferAbi: EntryFunctionABI = {
   parameters: [new TypeTagAddress(), new TypeTagU64()],
 };
 
+/**
+ * Generates a transaction to transfer coins from one account to another.
+ * This function allows you to specify the sender, recipient, amount, and coin type for the transaction.
+ *
+ * @param args - The parameters for the transaction.
+ * @param args.aptosConfig - The Aptos configuration object.
+ * @param args.sender - The address of the account sending the coins.
+ * @param args.recipient - The address of the account receiving the coins.
+ * @param args.amount - The amount of coins to transfer.
+ * @param args.coinType - (Optional) The type of coin to transfer, defaults to Aptos Coin if not specified.
+ * @param args.options - (Optional) Options for generating the transaction.
+ */
 export async function transferCoinTransaction(args: {
   aptosConfig: AptosConfig;
   sender: AccountAddressInput;