@aptos-labs/ts-sdk 1.33.1 → 1.33.2

package/src/core/crypto/multiKey.ts

@@ -11,6 +11,8 @@ import { AnyPublicKey, AnySignature } from "./singleKey";
  * This function can help you determine the population count of a given byte value.
  *
  * @param byte - The byte value for which to count the number of set bits.
+ * @group Implementation
+ * @category Serialization
  */
 /* eslint-disable no-bitwise */
 function bitCount(byte: number) {
@@ -29,15 +31,21 @@ function bitCount(byte: number) {
  * The public keys of each individual agent can be any type of public key supported by Aptos.
  * Since [AIP-55](https://github.com/aptos-foundation/AIPs/pull/263), Aptos supports
  * `Legacy` and `Unified` authentication keys.
+ * @group Implementation
+ * @category Serialization
  */
 export class MultiKey extends AccountPublicKey {
   /**
    * List of any public keys
+   * @group Implementation
+   * @category Serialization
    */
   public readonly publicKeys: AnyPublicKey[];
 
   /**
    * The minimum number of valid signatures required, for the number of public keys specified
+   * @group Implementation
+   * @category Serialization
    */
   public readonly signaturesRequired: number;
 
@@ -52,6 +60,8 @@ export class MultiKey extends AccountPublicKey {
    *
    * @throws Error if the number of signatures exceeds the maximum supported, if the bitmap length is incorrect, or if the number
    * of signatures does not match the bitmap.
+   * @group Implementation
+   * @category Serialization
    */
   // region Constructors
   constructor(args: { publicKeys: Array<PublicKey>; signaturesRequired: number }) {
@@ -89,6 +99,8 @@ export class MultiKey extends AccountPublicKey {
    * @param args - The arguments for verifying the signature.
    * @param args.message - The message that was signed.
    * @param args.signature - The signature to verify.
+   * @group Implementation
+   * @category Serialization
    */
   // eslint-disable-next-line class-methods-use-this, @typescript-eslint/no-unused-vars
   verifySignature(args: VerifySignatureArgs): boolean {
@@ -100,6 +112,8 @@ export class MultiKey extends AccountPublicKey {
    * This key can be used for secure authentication processes within the system.
    *
    * @returns {AuthenticationKey} The generated authentication key.
+   * @group Implementation
+   * @category Serialization
    */
   authKey(): AuthenticationKey {
     return AuthenticationKey.fromSchemeAndBytes({
@@ -117,6 +131,8 @@ export class MultiKey extends AccountPublicKey {
    * This allows the object to be converted 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.serializeVector(this.publicKeys);
@@ -128,6 +144,8 @@ export class MultiKey extends AccountPublicKey {
    * This function retrieves the signatures and bitmap necessary for creating a MultiKeySignature object.
    *
    * @param deserializer - The deserializer instance used to read the serialized data.
+   * @group Implementation
+   * @category Serialization
    */
   static deserialize(deserializer: Deserializer): MultiKey {
     const keys = deserializer.deserializeVector(AnyPublicKey);
@@ -144,6 +162,8 @@ export class MultiKey extends AccountPublicKey {
    *
    * @param args.bits array of the index mapping to the matching public keys
    * @returns Uint8array bit map
+   * @group Implementation
+   * @category Serialization
    */
   createBitmap(args: { bits: number[] }): Uint8Array {
     const { bits } = args;
@@ -188,6 +208,8 @@ export class MultiKey extends AccountPublicKey {
    * @param publicKey - The public key to find the index for.
    * @returns The corresponding index of the public key, if it exists.
    * @throws Error - If the public key is not found in the MultiKey.
+   * @group Implementation
+   * @category Serialization
    */
   getIndex(publicKey: PublicKey): number {
     const anyPublicKey = publicKey instanceof AnyPublicKey ? publicKey : new AnyPublicKey(publicKey);
@@ -196,7 +218,7 @@ export class MultiKey extends AccountPublicKey {
     if (index !== -1) {
       return index;
     }
-    throw new Error("Public key not found in MultiKey");
+    throw new Error(`Public key ${publicKey} not found in MultiKey ${this.publicKeys}`);
   }
 
   public static isInstance(value: PublicKey): value is MultiKey {
@@ -211,20 +233,28 @@ export class MultiKey extends AccountPublicKey {
  *
  * It includes functionality to validate the number of signatures against a bitmap,
  * which indicates which public keys have signed the transaction.
+ * @group Implementation
+ * @category Serialization
  */
 export class MultiKeySignature extends Signature {
   /**
    * Number of bytes in the bitmap representing who signed the transaction (32-bits)
+   * @group Implementation
+   * @category Serialization
    */
   static BITMAP_LEN: number = 4;
 
   /**
    * Maximum number of Ed25519 signatures supported
+   * @group Implementation
+   * @category Serialization
    */
   static MAX_SIGNATURES_SUPPORTED = MultiKeySignature.BITMAP_LEN * 8;
 
   /**
    * The list of underlying Ed25519 signatures
+   * @group Implementation
+   * @category Serialization
    */
   public readonly signatures: AnySignature[];
 
@@ -232,6 +262,8 @@ export class MultiKeySignature extends Signature {
    * 32-bit Bitmap representing who signed the transaction
    *
    * This is represented where each public key can be masked to determine whether the message was signed by that key.
+   * @group Implementation
+   * @category Serialization
    */
   public readonly bitmap: Uint8Array;
 
@@ -244,6 +276,8 @@ export class MultiKeySignature extends Signature {
    * @param args.signatures A list of signatures
    * @param args.bitmap 4 bytes, at most 32 signatures are supported. If Nth bit value is `1`, the Nth
    * signature should be provided in `signatures`. Bits are read from left to right
+   * @group Implementation
+   * @category Serialization
    */
   constructor(args: { signatures: Array<Signature | AnySignature>; bitmap: Uint8Array | number[] }) {
     super();
@@ -285,6 +319,8 @@ export class MultiKeySignature extends Signature {
    * The result bitmap should be 0b1010000000000000000000000000001
    *
    * @returns bitmap that is 32bit long
+   * @group Implementation
+   * @category Serialization
    */
   static createBitmap(args: { bits: number[] }): Uint8Array {
     const { bits } = args;

package/src/core/crypto/poseidon.ts

@@ -48,6 +48,8 @@ const MAX_NUM_INPUT_BYTES = (MAX_NUM_INPUT_SCALARS - 1) * BYTES_PACKED_PER_SCALA
  * @param str - The string to be hashed.
  * @param maxSizeBytes - The maximum size in bytes for the resulting hash.
  * @returns bigint - The result of the hash.
+ * @group Implementation
+ * @category Serialization
  */
 export function hashStrToField(str: string, maxSizeBytes: number): bigint {
   const textEncoder = new TextEncoder();
@@ -62,6 +64,8 @@ export function hashStrToField(str: string, maxSizeBytes: number): bigint {
  * @param bytes - The byte array to be hashed.
  * @param maxSizeBytes - The maximum allowed size for the byte array.
  * @throws Error if the length of the inputted bytes exceeds the specified maximum size.
+ * @group Implementation
+ * @category Serialization
  */
 function hashBytesWithLen(bytes: Uint8Array, maxSizeBytes: number): bigint {
   if (bytes.length > maxSizeBytes) {
@@ -78,6 +82,8 @@ function hashBytesWithLen(bytes: Uint8Array, maxSizeBytes: number): bigint {
  * @param bytes - The byte array to be padded and packed.
  * @param maxSizeBytes - The maximum size in bytes that the input array can have.
  * @throws Error if the input byte array exceeds the specified maximum size.
+ * @group Implementation
+ * @category Serialization
  */
 function padAndPackBytesNoLen(bytes: Uint8Array, maxSizeBytes: number): bigint[] {
   if (bytes.length > maxSizeBytes) {
@@ -96,6 +102,8 @@ function padAndPackBytesNoLen(bytes: Uint8Array, maxSizeBytes: number): bigint[]
  * @param maxSizeBytes - The maximum allowed size for the byte array.
  * @throws Error if the length of the input bytes exceeds the maximum size.
  * @returns A new Uint8Array that contains the padded and packed bytes along with the length of the original byte array.
+ * @group Implementation
+ * @category Serialization
  */
 export function padAndPackBytesWithLen(bytes: Uint8Array, maxSizeBytes: number): bigint[] {
   if (bytes.length > maxSizeBytes) {
@@ -108,6 +116,8 @@ export function padAndPackBytesWithLen(bytes: Uint8Array, maxSizeBytes: number):
  * Packs a Uint8Array into an array of BigInts, ensuring the input does not exceed the maximum allowed bytes.
  * @param bytes - The Uint8Array to be packed.
  * @throws {Error} Throws an error if the input exceeds the maximum number of bytes allowed.
+ * @group Implementation
+ * @category Serialization
  */
 function packBytes(bytes: Uint8Array): bigint[] {
   if (bytes.length > MAX_NUM_INPUT_BYTES) {
@@ -123,6 +133,8 @@ function packBytes(bytes: Uint8Array): bigint[] {
  * @param array - The Uint8Array to be split into chunks.
  * @param chunkSize - The size of each chunk.
  * @returns An array of Uint8Array chunks.
+ * @group Implementation
+ * @category Serialization
  */
 function chunkUint8Array(array: Uint8Array, chunkSize: number): Uint8Array[] {
   const result: Uint8Array[] = [];
@@ -138,6 +150,8 @@ function chunkUint8Array(array: Uint8Array, chunkSize: number): Uint8Array[] {
  *
  * @param bytes - The byte array to convert.
  * @returns The resulting BigInt representation of the byte array.
+ * @group Implementation
+ * @category Serialization
  */
 export function bytesToBigIntLE(bytes: Uint8Array): bigint {
   let result = BigInt(0);
@@ -155,6 +169,8 @@ export function bytesToBigIntLE(bytes: Uint8Array): bigint {
  * @param value - The number to convert into bytes.
  * @param length - The desired length of the resulting byte array.
  * @returns A Uint8Array containing the little-endian representation of the bigint value.
+ * @group Implementation
+ * @category Serialization
  */
 export function bigIntToBytesLE(value: bigint | number, length: number): Uint8Array {
   let val = BigInt(value);
@@ -173,6 +189,8 @@ export function bigIntToBytesLE(value: bigint | number, length: number): Uint8Ar
  * @param inputArray - The Uint8Array to be padded.
  * @param paddedSize - The desired size of the padded array, which must be greater than or equal to the input array size.
  * @throws Error if paddedSize is less than the length of inputArray.
+ * @group Implementation
+ * @category Serialization
  */
 function padUint8ArrayWithZeros(inputArray: Uint8Array, paddedSize: number): Uint8Array {
   if (paddedSize < inputArray.length) {
@@ -200,6 +218,8 @@ function padUint8ArrayWithZeros(inputArray: Uint8Array, paddedSize: number): Uin
  * @param inputs - An array of elements to be hashed, which can be of type number, bigint, or string.
  * @returns bigint - The result of the hash.
  * @throws Error - Throws an error if the input length exceeds the maximum allowed.
+ * @group Implementation
+ * @category Serialization
  */
 export function poseidonHash(inputs: (number | bigint | string)[]): bigint {
   if (inputs.length > numInputsToPoseidonFunc.length) {

package/src/core/crypto/privateKey.ts

@@ -7,22 +7,30 @@ import { Signature } from "./signature";
 
 /**
  * Represents a private key used for signing messages and deriving the associated public key.
+ * @group Implementation
+ * @category Serialization
  */
 export interface PrivateKey {
   /**
    * Sign the given message with the private key to create a signature.
    * @param message - The message to be signed, provided in HexInput format.
    * @returns A Signature object representing the signed message.
+   * @group Implementation
+   * @category Serialization
    */
   sign(message: HexInput): Signature;
 
   /**
    * Derive the public key associated with the private key.
+   * @group Implementation
+   * @category Serialization
    */
   publicKey(): PublicKey;
 
   /**
    * Get the private key in bytes (Uint8Array).
+   * @group Implementation
+   * @category Serialization
    */
   toUint8Array(): Uint8Array;
 }

package/src/core/crypto/proof.ts

@@ -3,5 +3,7 @@ import { Serializable } from "../../bcs";
 /**
  * An abstract representation of a cryptographic proof associated with specific
  * zero-knowledge proof schemes, such as Groth16 and PLONK.
+ * @group Implementation
+ * @category Serialization
  */
 export abstract class Proof extends Serializable {}

package/src/core/crypto/publicKey.ts

@@ -9,6 +9,8 @@ import { Signature } from "./signature";
  *
  * @param message - The original message that was signed.
  * @param signature - The signature to be verified against the message.
+ * @group Implementation
+ * @category Serialization
  */
 export interface VerifySignatureArgs {
   message: HexInput;
@@ -20,17 +22,23 @@ export interface VerifySignatureArgs {
  *
  * This class provides a common interface for verifying signatures associated with the public key.
  * It allows for the retrieval of the raw public key bytes and the public key in a hexadecimal string format.
+ * @group Implementation
+ * @category Serialization
  */
 export abstract class PublicKey extends Serializable {
   /**
    * Verifies that the private key associated with this public key signed the message with the given signature.
    * @param args.message The message that was signed
    * @param args.signature The signature to verify
+   * @group Implementation
+   * @category Serialization
    */
   abstract verifySignature(args: VerifySignatureArgs): boolean;
 
   /**
    * Get the raw public key bytes
+   * @group Implementation
+   * @category Serialization
    */
   toUint8Array(): Uint8Array {
     return this.bcsToBytes();
@@ -40,6 +48,8 @@ export abstract class PublicKey extends Serializable {
    * Get the public key as a hex string with a 0x prefix.
    *
    * @returns The public key in hex format.
+   * @group Implementation
+   * @category Serialization
    */
   toString(): string {
     const bytes = this.toUint8Array();
@@ -53,10 +63,14 @@ export abstract class PublicKey extends Serializable {
  * Provides a common interface for deriving an authentication key.
  *
  * @abstract
+ * @group Implementation
+ * @category Serialization
  */
 export abstract class AccountPublicKey extends PublicKey {
   /**
    * Get the authentication key associated with this public key
+   * @group Implementation
+   * @category Serialization
    */
   abstract authKey(): AuthenticationKey;
 }

package/src/core/crypto/secp256k1.ts

@@ -18,6 +18,8 @@ import { convertSigningMessage } from "./utils";
  *
  * @extends PublicKey
  * @property LENGTH - The length of the Secp256k1 public key in bytes.
+ * @group Implementation
+ * @category Serialization
  */
 export class Secp256k1PublicKey extends PublicKey {
   // Secp256k1 ecdsa public keys contain a prefix indicating compression and two 32-byte coordinates.
@@ -35,6 +37,8 @@ export class Secp256k1PublicKey extends PublicKey {
    *
    * @param hexInput - A HexInput (string or Uint8Array) representing the signature data.
    * @throws Error if the length of the signature data is not equal to Secp256k1Signature.LENGTH.
+   * @group Implementation
+   * @category Serialization
    */
   constructor(hexInput: HexInput) {
     super();
@@ -62,6 +66,8 @@ export class Secp256k1PublicKey extends PublicKey {
    * @param args - The arguments for verifying the signature.
    * @param args.message - The message that was signed.
    * @param args.signature - The signature to verify against the public key.
+   * @group Implementation
+   * @category Serialization
    */
   verifySignature(args: VerifySignatureArgs): boolean {
     const { message, signature } = args;
@@ -76,6 +82,8 @@ export class Secp256k1PublicKey extends PublicKey {
    * Get the data as a Uint8Array representation.
    *
    * @returns Uint8Array representation of the data.
+   * @group Implementation
+   * @category Serialization
    */
   toUint8Array(): Uint8Array {
     return this.key.toUint8Array();
@@ -90,6 +98,8 @@ export class Secp256k1PublicKey extends PublicKey {
    * This function is essential for converting data into a format suitable for transmission or storage.
    *
    * @param serializer - The serializer instance used to convert the data.
+   * @group Implementation
+   * @category Serialization
    */
   serialize(serializer: Serializer): void {
     serializer.serializeBytes(this.key.toUint8Array());
@@ -100,6 +110,8 @@ export class Secp256k1PublicKey extends PublicKey {
    * This function allows you to reconstruct a Secp256k1Signature object from its serialized byte representation.
    *
    * @param deserializer - The deserializer instance used to read the serialized data.
+   * @group Implementation
+   * @category Serialization
    */
   // eslint-disable-next-line class-methods-use-this
   deserialize(deserializer: Deserializer) {
@@ -119,6 +131,8 @@ export class Secp256k1PublicKey extends PublicKey {
    *
    * @deprecated use `instanceof Secp256k1PublicKey` instead
    * @param publicKey - The public key to check.
+   * @group Implementation
+   * @category Serialization
    */
   static isPublicKey(publicKey: PublicKey): publicKey is Secp256k1PublicKey {
     return publicKey instanceof Secp256k1PublicKey;
@@ -130,6 +144,8 @@ export class Secp256k1PublicKey extends PublicKey {
    *
    * @param publicKey - The public key to validate.
    * @returns A boolean indicating whether the public key is a valid Secp256k1 public key.
+   * @group Implementation
+   * @category Serialization
    */
   static isInstance(publicKey: PublicKey): publicKey is Secp256k1PublicKey {
     return "key" in publicKey && (publicKey.key as any)?.data?.length === Secp256k1PublicKey.LENGTH;
@@ -139,16 +155,22 @@ export class Secp256k1PublicKey extends PublicKey {
 /**
  * Represents a Secp256k1 ECDSA private key, providing functionality to create, sign messages,
  * derive public keys, and serialize/deserialize the key.
+ * @group Implementation
+ * @category Serialization
  */
 export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
   /**
    * Length of Secp256k1 ecdsa private key
+   * @group Implementation
+   * @category Serialization
    */
   static readonly LENGTH: number = 32;
 
   /**
    * The private key bytes
    * @private
+   * @group Implementation
+   * @category Serialization
    */
   private readonly key: Hex;
 
@@ -161,6 +183,8 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
    *
    * @param hexInput A HexInput (string or Uint8Array)
    * @param strict If true, private key must AIP-80 compliant.
+   * @group Implementation
+   * @category Serialization
    */
   constructor(hexInput: HexInput, strict?: boolean) {
     super();
@@ -177,6 +201,8 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
    * Generate a new random private key.
    *
    * @returns Secp256k1PrivateKey - A newly generated Secp256k1 private key.
+   * @group Implementation
+   * @category Serialization
    */
   static generate(): Secp256k1PrivateKey {
     const hexInput = secp256k1.utils.randomPrivateKey();
@@ -192,6 +218,8 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
    * @returns The generated private key.
    *
    * @throws Error if the provided path is not a valid BIP44 path.
+   * @group Implementation
+   * @category Serialization
    */
   static fromDerivationPath(path: string, mnemonics: string): Secp256k1PrivateKey {
     if (!isValidBIP44Path(path)) {
@@ -208,6 +236,8 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
    * @param seed - The seed phrase created by the mnemonics, represented as a Uint8Array.
    * @returns The generated private key as an instance of Secp256k1PrivateKey.
    * @throws Error if the derived private key is invalid.
+   * @group Implementation
+   * @category Serialization
    */
   private static fromDerivationPathInner(path: string, seed: Uint8Array): Secp256k1PrivateKey {
     const { privateKey } = HDKey.fromMasterSeed(seed).derive(path);
@@ -229,6 +259,8 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
    *
    * @param message - A message in HexInput format to be signed.
    * @returns Signature - The generated signature for the provided message.
+   * @group Implementation
+   * @category Serialization
    */
   sign(message: HexInput): Secp256k1Signature {
     const messageToSign = convertSigningMessage(message);
@@ -242,6 +274,8 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
    * Derive the Secp256k1PublicKey from this private key.
    *
    * @returns Secp256k1PublicKey The derived public key.
+   * @group Implementation
+   * @category Serialization
    */
   publicKey(): Secp256k1PublicKey {
     const bytes = secp256k1.getPublicKey(this.key.toUint8Array(), false);
@@ -252,6 +286,8 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
    * Get the private key in bytes (Uint8Array).
    *
    * @returns
+   * @group Implementation
+   * @category Serialization
    */
   toUint8Array(): Uint8Array {
     return this.key.toUint8Array();
@@ -261,6 +297,8 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
    * Get the private key as a string representation.
    *
    * @returns string representation of the private key
+   * @group Implementation
+   * @category Serialization
    */
   toString(): string {
     return this.toHexString();
@@ -307,6 +345,8 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
    * @param privateKey - The private key to be checked.
    *
    * @deprecated use `instanceof Secp256k1PrivateKey` instead
+   * @group Implementation
+   * @category Serialization
    */
   static isPrivateKey(privateKey: PrivateKey): privateKey is Secp256k1PrivateKey {
     return privateKey instanceof Secp256k1PrivateKey;
@@ -316,17 +356,22 @@ export class Secp256k1PrivateKey extends Serializable implements PrivateKey {
 /**
  * Represents a signature of a message signed using a Secp256k1 ECDSA private key.
  *
+ * @group Implementation
+ * @category Serialization
  */
 export class Secp256k1Signature extends Signature {
   /**
-   * Secp256k1 ecdsa signatures are 256-bit or 64 bytes
-   * @readonly
+   * Secp256k1 ecdsa signatures are 256-bit.
+   * @group Implementation
+   * @category Serialization
    */
   static readonly LENGTH = 64;
 
   /**
    * The signature bytes
    * @private
+   * @group Implementation
+   * @category Serialization
    */
   private readonly data: Hex;
 
@@ -336,6 +381,8 @@ export class Secp256k1Signature extends Signature {
    * Create a new Signature instance from a Uint8Array or String.
    *
    * @param hexInput A HexInput (string or Uint8Array)
+   * @group Implementation
+   * @category Serialization
    */
   constructor(hexInput: HexInput) {
     super();

package/src/core/crypto/signature.ts

@@ -7,10 +7,14 @@ import { Hex } from "../hex";
  *
  * This class represents the product of signing a message directly from a
  * PrivateKey and can be verified against a CryptoPublicKey.
+ * @group Implementation
+ * @category Serialization
  */
 export abstract class Signature extends Serializable {
   /**
    * Get the raw signature bytes
+   * @group Implementation
+   * @category Serialization
    */
   toUint8Array(): Uint8Array {
     return this.bcsToBytes();
@@ -19,6 +23,8 @@ export abstract class Signature extends Serializable {
   /**
    * Get the signature as a hex string with a 0x prefix e.g. 0x123456...
    * @returns The hex string representation of the signature.
+   * @group Implementation
+   * @category Serialization
    */
   toString(): string {
     const bytes = this.toUint8Array();
@@ -32,6 +38,8 @@ export abstract class Signature extends Serializable {
  *
  * This is the product of signing a message through an account,
  * and can be verified against an AccountPublicKey.
+ * @group Implementation
+ * @category Serialization
  */
 // export abstract class AccountSignature extends Serializable {
 //   /**