@aptos-labs/ts-sdk 1.33.1 → 1.33.2

package/src/client/post.ts

@@ -8,48 +8,70 @@ import { AptosApiType } from "../utils/const";
 
 /**
  * Options for making a POST request, including the API client configuration.
+ * @group Implementation
+ * @category Client
  */
 export type PostRequestOptions = {
   /**
    * The config for the API client
+   * @group Implementation
+   * @category Client
    */
   aptosConfig: AptosConfig;
   /**
    * The type of API endpoint to call e.g. fullnode, indexer, etc
+   * @group Implementation
+   * @category Client
    */
   type: AptosApiType;
   /**
    * The name of the API method
+   * @group Implementation
+   * @category Client
    */
   originMethod: string;
   /**
    * The URL path to the API method
+   * @group Implementation
+   * @category Client
    */
   path: string;
   /**
    * The content type of the request body
+   * @group Implementation
+   * @category Client
    */
   contentType?: MimeType;
   /**
    * The accepted content type of the response of the API
+   * @group Implementation
+   * @category Client
    */
   acceptType?: MimeType;
   /**
    * The query parameters for the request
+   * @group Implementation
+   * @category Client
    */
   params?: Record<string, string | AnyNumber | boolean | undefined>;
   /**
    * The body of the request, should match the content type of the request
+   * @group Implementation
+   * @category Client
    */
   body?: any;
   /**
    * Specific client overrides for this request to override aptosConfig
+   * @group Implementation
+   * @category Client
    */
   overrides?: ClientConfig;
 };
 
 /**
  * Options for posting a request to Aptos, excluding the type field.
+ * @group Implementation
+ * @category Client
  */
 export type PostAptosRequestOptions = Omit<PostRequestOptions, "type">;
 
@@ -67,6 +89,8 @@ export type PostAptosRequestOptions = Omit<PostRequestOptions, "type">;
  * @param options.aptosConfig - Configuration settings for the Aptos request.
  * @param options.overrides - Any overrides for the default request behavior.
  * @returns The response from the POST request.
+ * @group Implementation
+ * @category Client
  */
 export async function post<Req extends {}, Res extends {}>(
   options: PostRequestOptions,
@@ -100,6 +124,8 @@ export async function post<Req extends {}, Res extends {}>(
  * @param options.aptosConfig.clientConfig - Client-specific configuration settings.
  * @param options.aptosConfig.fullnodeConfig - Full node-specific configuration settings.
  * @param options.overrides - Additional overrides for the request.
+ * @group Implementation
+ * @category Client
  */
 export async function postAptosFullNode<Req extends {}, Res extends {}>(
   options: PostAptosRequestOptions,
@@ -128,6 +154,8 @@ export async function postAptosFullNode<Req extends {}, Res extends {}>(
  * @param options.aptosConfig.indexerConfig - The indexer configuration settings.
  * @param options.overrides - Additional overrides for the request.
  * @param options.overrides.HEADERS - Custom headers to include in the request.
+ * @group Implementation
+ * @category Client
  */
 export async function postAptosIndexer<Req extends {}, Res extends {}>(
   options: PostAptosRequestOptions,
@@ -150,12 +178,17 @@ export async function postAptosIndexer<Req extends {}, Res extends {}>(
  * Sends a request to the Aptos faucet to obtain test tokens.
  * This function modifies the provided configuration to ensure that the API_KEY is not included in the request.
  *
+ * Note that only devnet has a publicly accessible faucet. For testnet, you must use
+ * the minting page at https://aptos.dev/network/faucet.
+ *
  * @param options - The options for the request.
  * @param options.aptosConfig - The configuration settings for the Aptos client.
  * @param options.aptosConfig.clientConfig - The client-specific configuration settings.
  * @param options.aptosConfig.clientConfig.HEADERS - Optional headers to include in the request.
  * @param options.aptosConfig.faucetConfig - The configuration settings specific to the faucet.
  * @param options.overrides - Additional overrides for the request configuration.
+ * @group Implementation
+ * @category Client
  */
 export async function postAptosFaucet<Req extends {}, Res extends {}>(
   options: PostAptosRequestOptions,
@@ -190,6 +223,8 @@ export async function postAptosFaucet<Req extends {}, Res extends {}>(
  * @param options.headers - The headers to include in the request.
  * @param options.body - The body of the request.
  * @returns A promise that resolves to the response from the pepper service.
+ * @group Implementation
+ * @category Client
  */
 export async function postAptosPepperService<Req extends {}, Res extends {}>(
   options: PostAptosRequestOptions,
@@ -203,6 +238,8 @@ export async function postAptosPepperService<Req extends {}, Res extends {}>(
  * @param options - The options for the request to the Aptos proving service.
  * @param options.type - The type of the request, which should be set to AptosApiType.PROVER.
  * @param options.data - The data to be included in the request.
+ * @group Implementation
+ * @category Client
  */
 export async function postAptosProvingService<Req extends {}, Res extends {}>(
   options: PostAptosRequestOptions,

package/src/core/account/utils/address.ts

@@ -9,6 +9,8 @@ import { DeriveScheme } from "../../../types";
  * @param seed The seed in either Uint8Array | string type
  *
  * @returns The object account address
+ * @group Implementation
+ * @category Account (On-Chain Model)
  */
 export const createObjectAddress = (creatorAddress: AccountAddress, seed: Uint8Array | string): AccountAddress => {
   const creatorBytes = creatorAddress.bcsToBytes();
@@ -27,6 +29,8 @@ export const createObjectAddress = (creatorAddress: AccountAddress, seed: Uint8A
  * @param seed The seed in either Uint8Array | string type
  *
  * @returns The resource account address
+ * @group Implementation
+ * @category Account (On-Chain Model)
  */
 export const createResourceAddress = (creatorAddress: AccountAddress, seed: Uint8Array | string): AccountAddress => {
   const creatorBytes = creatorAddress.bcsToBytes();
@@ -46,6 +50,8 @@ export const createResourceAddress = (creatorAddress: AccountAddress, seed: Uint
  * @param tokenName The token name
  *
  * @returns The token account address
+ * @group Implementation
+ * @category Account (On-Chain Model)
  */
 export const createTokenAddress = (
   creatorAddress: AccountAddress,

package/src/core/accountAddress.ts

@@ -10,6 +10,8 @@ import { HexInput, ScriptTransactionArgumentVariants } from "../types";
 
 /**
  * Provides reasons for an address was invalid.
+ * @group Implementation
+ * @category Serialization
  */
 export enum AddressInvalidReason {
   INCORRECT_NUMBER_OF_BYTES = "incorrect_number_of_bytes",
@@ -24,6 +26,8 @@ export enum AddressInvalidReason {
 
 /**
  * The input for an account address, which can be either a hexadecimal string or a standard account address.
+ * @group Implementation
+ * @category Serialization
  */
 export type AccountAddressInput = HexInput | AccountAddress;
 
@@ -42,20 +46,28 @@ export type AccountAddressInput = HexInput | AccountAddress;
  *
  * The comments in this class make frequent reference to the LONG and SHORT formats,
  * as well as "special" addresses. To learn what these refer to see AIP-40.
+ * @group Implementation
+ * @category Serialization
  */
 export class AccountAddress extends Serializable implements TransactionArgument {
   /**
    * This is the internal representation of an account address.
+   * @group Implementation
+   * @category Serialization
    */
   readonly data: Uint8Array;
 
   /**
    * The number of bytes that make up an account address.
+   * @group Implementation
+   * @category Serialization
    */
   static readonly LENGTH: number = 32;
 
   /**
    * The length of an address string in LONG form without a leading 0x.
+   * @group Implementation
+   * @category Serialization
    */
   static readonly LONG_STRING_LENGTH: number = 64;
 
@@ -78,6 +90,8 @@ export class AccountAddress extends Serializable implements TransactionArgument
    *
    * @param input A Uint8Array representing an account address.
    * @throws ParsingError if the input length is not equal to 32 bytes.
+   * @group Implementation
+   * @category Serialization
    */
   constructor(input: Uint8Array) {
     super();
@@ -99,6 +113,8 @@ export class AccountAddress extends Serializable implements TransactionArgument
    * https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-40.md.
    *
    * @returns true if the address is special, false otherwise.
+   * @group Implementation
+   * @category Serialization
    */
   isSpecial(): boolean {
     return (
@@ -116,6 +132,8 @@ export class AccountAddress extends Serializable implements TransactionArgument
    * and other addresses in LONG form (0x + 64 characters).
    *
    * @returns AccountAddress as a string conforming to AIP-40.
+   * @group Implementation
+   * @category Serialization
    */
   toString(): `0x${string}` {
     return `0x${this.toStringWithoutPrefix()}`;
@@ -127,6 +145,8 @@ export class AccountAddress extends Serializable implements TransactionArgument
    * NOTE: Prefer to use `toString` where possible.
    *
    * @returns AccountAddress as a string without the leading 0x.
+   * @group Implementation
+   * @category Serialization
    */
   toStringWithoutPrefix(): string {
     let hex = bytesToHex(this.data);
@@ -142,6 +162,8 @@ export class AccountAddress extends Serializable implements TransactionArgument
    * NOTE: Prefer to use `toString` where possible, as it formats special addresses using the SHORT form (no leading 0s).
    *
    * @returns AccountAddress as a string in LONG form.
+   * @group Implementation
+   * @category Serialization
    */
   toStringLong(): `0x${string}` {
     return `0x${this.toStringLongWithoutPrefix()}`;
@@ -154,6 +176,8 @@ export class AccountAddress extends Serializable implements TransactionArgument
    * NOTE: Prefer to use `toString` where possible, as it formats special addresses using the SHORT form (no leading 0s).
    *
    * @returns {string} The account address in LONG form.
+   * @group Implementation
+   * @category Serialization
    */
   toStringLongWithoutPrefix(): string {
     return bytesToHex(this.data);
@@ -164,6 +188,8 @@ export class AccountAddress extends Serializable implements TransactionArgument
    * The inner data is already a Uint8Array, so no conversion takes place.
    *
    * @returns Hex data as Uint8Array
+   * @group Implementation
+   * @category Serialization
    */
   toUint8Array(): Uint8Array {
     return this.data;
@@ -179,6 +205,8 @@ export class AccountAddress extends Serializable implements TransactionArgument
    * address.serialize(serializer);
    * const bytes = serializer.toUint8Array();
    * // `bytes` is now the BCS-serialized address.
+   * @group Implementation
+   * @category Serialization
    */
   serialize(serializer: Serializer): void {
     serializer.serializeFixedBytes(this.data);
@@ -189,6 +217,8 @@ export class AccountAddress extends Serializable implements TransactionArgument
    * This allows for the proper encoding of data when interacting with entry functions in the blockchain.
    *
    * @param serializer - The serializer instance used to convert the data into bytes.
+   * @group Implementation
+   * @category Serialization
    */
   serializeForEntryFunction(serializer: Serializer): void {
     const bcsBytes = this.bcsToBytes();
@@ -200,6 +230,8 @@ export class AccountAddress extends Serializable implements TransactionArgument
    * This process involves serializing the variant index and the instance data, making it suitable for transmission.
    *
    * @param serializer - The serializer instance used to perform the serialization.
+   * @group Implementation
+   * @category Serialization
    */
   serializeForScriptFunction(serializer: Serializer): void {
     serializer.serializeU32AsUleb128(ScriptTransactionArgumentVariants.Address);
@@ -216,6 +248,8 @@ export class AccountAddress extends Serializable implements TransactionArgument
    * const deserializer = new Deserializer(bytes);
    * const address = AccountAddress.deserialize(deserializer);
    * // `address` is now an instance of AccountAddress.
+   * @group Implementation
+   * @category Serialization
    */
   static deserialize(deserializer: Deserializer): AccountAddress {
     const bytes = deserializer.deserializeFixedBytes(AccountAddress.LENGTH);
@@ -258,6 +292,8 @@ export class AccountAddress extends Serializable implements TransactionArgument
    * https://github.com/aptos-foundation/AIPs/blob/main/aips/aip-40.md.
    *
    * @returns An instance of AccountAddress.
+   * @group Implementation
+   * @category Serialization
    */
   static fromStringStrict(input: string): AccountAddress {
     // Assert the string starts with 0x.
@@ -315,6 +351,8 @@ export class AccountAddress extends Serializable implements TransactionArgument
    * @returns An instance of AccountAddress.
    *
    * @throws ParsingError if the hex string is too short, too long, or contains invalid characters.
+   * @group Implementation
+   * @category Serialization
    */
   static fromString(input: string, { maxMissingChars = 4 }: { maxMissingChars?: number } = {}): AccountAddress {
     let parsedInput = input;
@@ -384,6 +422,8 @@ Received ${input}`,
    * @param input - The input to convert into an AccountAddress. This can be a string representation of an address, a Uint8Array,
    * or an existing AccountAddress.
    * @param args.maxMissingChars The number of characters that can be missing in a padded address before it is invalid.
+   * @group Implementation
+   * @category Serialization
    */
   static from(input: AccountAddressInput, { maxMissingChars = 4 }: { maxMissingChars?: number } = {}): AccountAddress {
     if (typeof input === "string") {
@@ -399,6 +439,8 @@ Received ${input}`,
    * Create an AccountAddress from various input types, including strings, Uint8Array, and AccountAddress instances.
    *
    * @param input - The input to convert into an AccountAddress, which can be a string, a Uint8Array, or an AccountAddress.
+   * @group Implementation
+   * @category Serialization
    */
   static fromStrict(input: AccountAddressInput): AccountAddress {
     if (typeof input === "string") {
@@ -422,6 +464,8 @@ Received ${input}`,
    *
    * @returns An object indicating whether the address is valid. If valid, valid = true; if not, valid = false with additional details.
    * If the address is invalid, invalidReason will explain why it is invalid, and invalidReasonMessage will provide the error message.
+   * @group Implementation
+   * @category Serialization
    */
   static isValid(args: { input: AccountAddressInput; strict?: boolean }): ParsingResult<AddressInvalidReason> {
     try {
@@ -445,6 +489,8 @@ Received ${input}`,
    *
    * @param other - The AccountAddress to compare to.
    * @returns true if the AccountAddresses are equal, false if not.
+   * @group Implementation
+   * @category Serialization
    */
   equals(other: AccountAddress): boolean {
     if (this.data.length !== other.data.length) return false;

package/src/core/authenticationKey.ts

@@ -17,17 +17,23 @@ import { Deserializer } from "../bcs/deserializer";
  * @see {@link https://aptos.dev/concepts/accounts | Account Basics}
  *
  * Account addresses can be derived from the AuthenticationKey.
+ * @group Implementation
+ * @category Serialization
  */
 export class AuthenticationKey extends Serializable {
   /**
    * An authentication key is always a SHA3-256 hash of data, and is always 32 bytes.
    *
    * The data to hash depends on the underlying public key type and the derivation scheme.
+   * @group Implementation
+   * @category Serialization
    */
   static readonly LENGTH: number = 32;
 
   /**
    * The raw bytes of the authentication key.
+   * @group Implementation
+   * @category Serialization
    */
   public readonly data: Hex;
 
@@ -39,6 +45,8 @@ export class AuthenticationKey extends Serializable {
    * @param args.data - The hex input data to be used for the Authentication Key.
    * @throws {Error} Throws an error if the length of the provided hex input is not equal to the required Authentication Key
    * length.
+   * @group Implementation
+   * @category Serialization
    */
   constructor(args: { data: HexInput }) {
     super();
@@ -54,6 +62,8 @@ export class AuthenticationKey extends Serializable {
    * Serializes the fixed bytes data into a format suitable for transmission or storage.
    *
    * @param serializer - The serializer instance used to perform the serialization.
+   * @group Implementation
+   * @category Serialization
    */
   serialize(serializer: Serializer): void {
     serializer.serializeFixedBytes(this.data.toUint8Array());
@@ -63,6 +73,8 @@ export class AuthenticationKey extends Serializable {
    * Deserialize an AuthenticationKey from the byte buffer in a Deserializer instance.
    * @param deserializer - The deserializer to deserialize the AuthenticationKey from.
    * @returns An instance of AuthenticationKey.
+   * @group Implementation
+   * @category Serialization
    */
   static deserialize(deserializer: Deserializer): AuthenticationKey {
     const bytes = deserializer.deserializeFixedBytes(AuthenticationKey.LENGTH);
@@ -75,6 +87,8 @@ export class AuthenticationKey extends Serializable {
    * This function is useful for obtaining a byte representation of the data, which can be utilized for serialization or transmission.
    *
    * @returns Uint8Array representation of the internal data.
+   * @group Implementation
+   * @category Serialization
    */
   toUint8Array(): Uint8Array {
     return this.data.toUint8Array();
@@ -88,6 +102,8 @@ export class AuthenticationKey extends Serializable {
    * @param args.scheme - The authentication key scheme to use.
    * @param args.input - The input data in hexadecimal format to derive the key.
    * @returns An instance of AuthenticationKey containing the generated key data.
+   * @group Implementation
+   * @category Serialization
    */
   static fromSchemeAndBytes(args: { scheme: AuthenticationKeyScheme; input: HexInput }): AuthenticationKey {
     const { scheme, input } = args;
@@ -106,6 +122,8 @@ export class AuthenticationKey extends Serializable {
    * @param args - The arguments for deriving the authentication key.
    * @param args.publicKey - The public key used for the derivation.
    * @param args.scheme - The scheme to use for deriving the authentication key.
+   * @group Implementation
+   * @category Serialization
    */
   public static fromPublicKeyAndScheme(args: { publicKey: AccountPublicKey; scheme: AuthenticationKeyScheme }) {
     const { publicKey } = args;
@@ -118,6 +136,8 @@ export class AuthenticationKey extends Serializable {
    * @param args - The arguments for the function.
    * @param args.publicKey - The PublicKey to be converted.
    * @returns AuthenticationKey - The derived AuthenticationKey.
+   * @group Implementation
+   * @category Serialization
    */
   static fromPublicKey(args: { publicKey: AccountPublicKey }): AuthenticationKey {
     const { publicKey } = args;
@@ -128,6 +148,8 @@ export class AuthenticationKey extends Serializable {
    * Derives an account address from an AuthenticationKey by translating the AuthenticationKey bytes directly to an AccountAddress.
    *
    * @returns AccountAddress - The derived account address.
+   * @group Implementation
+   * @category Serialization
    */
   derivedAddress(): AccountAddress {
     return new AccountAddress(this.data.toUint8Array());

package/src/core/common.ts

@@ -3,12 +3,16 @@
 
 /**
  * This error is used to explain why parsing failed.
+ * @group Implementation
+ * @category Serialization
  */
 export class ParsingError<T> extends Error {
   /**
    * This provides a programmatic way to access why parsing failed. Downstream devs
    * might want to use this to build their own error messages if the default error
    * messages are not suitable for their use case. This should be an enum.
+   * @group Implementation
+   * @category Serialization
    */
   public invalidReason: T;
 
@@ -17,6 +21,8 @@ export class ParsingError<T> extends Error {
    *
    * @param message The error message that describes the issue.
    * @param invalidReason The reason why the input is considered invalid.
+   * @group Implementation
+   * @category Serialization
    */
   constructor(message: string, invalidReason: T) {
     super(message);
@@ -27,20 +33,28 @@ export class ParsingError<T> extends Error {
 /**
  * Whereas ParsingError is thrown when parsing fails, e.g. in a fromString function,
  * this type is returned from "defensive" functions like isValid.
+ * @group Implementation
+ * @category Serialization
  */
 export type ParsingResult<T> = {
   /**
    * True if valid, false otherwise.
+   * @group Implementation
+   * @category Serialization
    */
   valid: boolean;
 
   /**
    * If valid is false, this will be a code explaining why parsing failed.
+   * @group Implementation
+   * @category Serialization
    */
   invalidReason?: T;
 
   /**
    * If valid is false, this will be a string explaining why parsing failed.
+   * @group Implementation
+   * @category Serialization
    */
   invalidReasonMessage?: string;
 };