@aptos-labs/ts-sdk 1.33.1 → 1.33.2

package/src/core/crypto/ed25519.ts

@@ -15,6 +15,8 @@ import { convertSigningMessage } from "./utils";
 
 /**
  * L is the value that greater than or equal to will produce a non-canonical signature, and must be rejected
+ * @group Implementation
+ * @category Serialization
  */
 const L: number[] = [
   0xed, 0xd3, 0xf5, 0x5c, 0x1a, 0x63, 0x12, 0x58, 0xd6, 0x9c, 0xf7, 0xa2, 0xde, 0xf9, 0xde, 0x14, 0x00, 0x00, 0x00,
@@ -30,6 +32,8 @@ const L: number[] = [
  *
  * Comes from Aptos Core
  * https://github.com/aptos-labs/aptos-core/blob/main/crates/aptos-crypto/src/ed25519/ed25519_sigs.rs#L47-L85
+ * @group Implementation
+ * @category Serialization
  */
 export function isCanonicalEd25519Signature(signature: Signature): boolean {
   const s = signature.toUint8Array().slice(32);
@@ -53,16 +57,22 @@ export function isCanonicalEd25519Signature(signature: Signature): boolean {
  *
  * Ed25519 scheme is represented in the SDK as `Legacy authentication key` and also
  * as `AnyPublicKey` that represents any `Unified authentication key`.
+ * @group Implementation
+ * @category Serialization
  */
 export class Ed25519PublicKey extends AccountPublicKey {
   /**
    * Length of an Ed25519 public key
+   * @group Implementation
+   * @category Serialization
    */
   static readonly LENGTH: number = 32;
 
   /**
    * Bytes of the public key
    * @private
+   * @group Implementation
+   * @category Serialization
    */
   private readonly key: Hex;
 
@@ -72,6 +82,8 @@ export class Ed25519PublicKey extends AccountPublicKey {
    *
    * @param hexInput - The hex input representing the Ed25519 signature.
    * @throws Error if the signature length is not equal to Ed25519Signature.LENGTH.
+   * @group Implementation
+   * @category Serialization
    */
   constructor(hexInput: HexInput) {
     super();
@@ -91,6 +103,8 @@ export class Ed25519PublicKey extends AccountPublicKey {
    * @param args - The arguments for verification.
    * @param args.message - A signed message as a Hex string or Uint8Array.
    * @param args.signature - The signature of the message.
+   * @group Implementation
+   * @category Serialization
    */
   verifySignature(args: VerifySignatureArgs): boolean {
     const { message, signature } = args;
@@ -111,6 +125,8 @@ export class Ed25519PublicKey extends AccountPublicKey {
    * This function is essential for creating a secure authentication key that can be used for further cryptographic operations.
    *
    * @returns {AuthenticationKey} The generated authentication key.
+   * @group Implementation
+   * @category Serialization
    */
   authKey(): AuthenticationKey {
     return AuthenticationKey.fromSchemeAndBytes({
@@ -123,6 +139,8 @@ export class Ed25519PublicKey extends AccountPublicKey {
    * Convert the internal data representation to a Uint8Array.
    *
    * @returns Uint8Array representation of the data.
+   * @group Implementation
+   * @category Serialization
    */
   toUint8Array(): Uint8Array {
     return this.key.toUint8Array();
@@ -137,6 +155,8 @@ export class Ed25519PublicKey extends AccountPublicKey {
    * This allows for the conversion of 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.serializeBytes(this.key.toUint8Array());
@@ -147,6 +167,8 @@ export class Ed25519PublicKey extends AccountPublicKey {
    * This function is used to convert serialized byte data into a usable Ed25519Signature instance.
    *
    * @param deserializer - The deserializer instance used to read the byte data.
+   * @group Implementation
+   * @category Serialization
    */
   static deserialize(deserializer: Deserializer): Ed25519PublicKey {
     const bytes = deserializer.deserializeBytes();
@@ -161,6 +183,8 @@ export class Ed25519PublicKey extends AccountPublicKey {
    * @param publicKey - The public key to check.
    * @returns True if the public key is an instance of Ed25519PublicKey, otherwise false.
    * @deprecated use `instanceof Ed25519PublicKey` instead.
+   * @group Implementation
+   * @category Serialization
    */
   static isPublicKey(publicKey: AccountPublicKey): publicKey is Ed25519PublicKey {
     return publicKey instanceof Ed25519PublicKey;
@@ -173,6 +197,8 @@ export class Ed25519PublicKey extends AccountPublicKey {
    *
    * @param publicKey - The public key to validate.
    * @returns A boolean indicating whether the public key is a valid Ed25519 public key.
+   * @group Implementation
+   * @category Serialization
    */
   static isInstance(publicKey: PublicKey): publicKey is Ed25519PublicKey {
     return "key" in publicKey && (publicKey.key as any)?.data?.length === Ed25519PublicKey.LENGTH;
@@ -181,24 +207,30 @@ export class Ed25519PublicKey extends AccountPublicKey {
 
 /**
  * Represents the private key of an Ed25519 key pair.
+ * @group Implementation
+ * @category Serialization
  */
 export class Ed25519PrivateKey extends Serializable implements PrivateKey {
   /**
    * Length of an Ed25519 private key
-   * @readonly
+   * @group Implementation
+   * @category Serialization
    */
   static readonly LENGTH: number = 32;
 
   /**
    * The Ed25519 key seed to use for BIP-32 compatibility
    * See more {@link https://github.com/satoshilabs/slips/blob/master/slip-0010.md}
-   * @readonly
+   * @group Implementation
+   * @category Serialization
    */
   static readonly SLIP_0010_SEED = "ed25519 seed";
 
   /**
    * The Ed25519 signing key
    * @private
+   * @group Implementation
+   * @category Serialization
    */
   private readonly signingKey: Hex;
 
@@ -211,6 +243,8 @@ export class Ed25519PrivateKey extends Serializable implements PrivateKey {
    *
    * @param hexInput HexInput (string or Uint8Array)
    * @param strict If true, private key must AIP-80 compliant.
+   * @group Implementation
+   * @category Serialization
    */
   constructor(hexInput: HexInput, strict?: boolean) {
     super();
@@ -228,6 +262,8 @@ export class Ed25519PrivateKey extends Serializable implements PrivateKey {
    * Generate a new random private key.
    *
    * @returns Ed25519PrivateKey A newly generated Ed25519 private key.
+   * @group Implementation
+   * @category Serialization
    */
   static generate(): Ed25519PrivateKey {
     const keyPair = ed25519.utils.randomPrivateKey();
@@ -243,6 +279,8 @@ export class Ed25519PrivateKey extends Serializable implements PrivateKey {
    * @param path - The BIP44 path used for key derivation.
    * @param mnemonics - The mnemonic seed phrase from which the key will be derived.
    * @throws Error if the provided path is not a valid hardened path.
+   * @group Implementation
+   * @category Serialization
    */
   static fromDerivationPath(path: string, mnemonics: string): Ed25519PrivateKey {
     if (!isValidHardenedPath(path)) {
@@ -260,6 +298,8 @@ export class Ed25519PrivateKey extends Serializable implements PrivateKey {
    * @param seed - The seed phrase created by the mnemonics, represented as a Uint8Array.
    * @param offset - The offset used for key derivation, defaults to HARDENED_OFFSET.
    * @returns An instance of Ed25519PrivateKey derived from the specified path and seed.
+   * @group Implementation
+   * @category Serialization
    */
   private static fromDerivationPathInner(path: string, seed: Uint8Array, offset = HARDENED_OFFSET): Ed25519PrivateKey {
     const { key, chainCode } = deriveKey(Ed25519PrivateKey.SLIP_0010_SEED, seed);
@@ -282,6 +322,8 @@ export class Ed25519PrivateKey extends Serializable implements PrivateKey {
    * Derive the Ed25519PublicKey for this private key.
    *
    * @returns Ed25519PublicKey - The derived public key corresponding to the private key.
+   * @group Implementation
+   * @category Serialization
    */
   publicKey(): Ed25519PublicKey {
     const bytes = ed25519.getPublicKey(this.signingKey.toUint8Array());
@@ -294,6 +336,8 @@ export class Ed25519PrivateKey extends Serializable implements PrivateKey {
    *
    * @param message - A message as a string or Uint8Array in HexInput format.
    * @returns A digital signature for the provided message.
+   * @group Implementation
+   * @category Serialization
    */
   sign(message: HexInput): Ed25519Signature {
     const messageToSign = convertSigningMessage(message);
@@ -306,6 +350,8 @@ export class Ed25519PrivateKey extends Serializable implements PrivateKey {
    * Get the private key in bytes (Uint8Array).
    *
    * @returns Uint8Array representation of the private key
+   * @group Implementation
+   * @category Serialization
    */
   toUint8Array(): Uint8Array {
     return this.signingKey.toUint8Array();
@@ -315,6 +361,8 @@ export class Ed25519PrivateKey extends Serializable implements PrivateKey {
    * Get the private key as a hex string with the 0x prefix.
    *
    * @returns string representation of the private key.
+   * @group Implementation
+   * @category Serialization
    */
   toString(): string {
     return this.toHexString();
@@ -362,6 +410,8 @@ export class Ed25519PrivateKey extends Serializable implements PrivateKey {
    * @returns A boolean indicating whether the private key is an Ed25519PrivateKey.
    *
    * @deprecated Use `instanceof Ed25519PrivateKey` instead.
+   * @group Implementation
+   * @category Serialization
    */
   static isPrivateKey(privateKey: PrivateKey): privateKey is Ed25519PrivateKey {
     return privateKey instanceof Ed25519PrivateKey;
@@ -370,18 +420,22 @@ export class Ed25519PrivateKey extends Serializable implements PrivateKey {
 
 /**
  * Represents a signature of a message signed using an Ed25519 private key.
+ * @group Implementation
+ * @category Serialization
  */
 export class Ed25519Signature extends Signature {
   /**
    * Length of an Ed25519 signature, which is 64 bytes.
-   *
-   * @readonly
+   * @group Implementation
+   * @category Serialization
    */
   static readonly LENGTH = 64;
 
   /**
    * The signature bytes
    * @private
+   * @group Implementation
+   * @category Serialization
    */
   private readonly data: Hex;
 

package/src/core/crypto/ephemeral.ts

@@ -9,15 +9,21 @@ import { Hex } from "../hex";
  * Represents ephemeral public keys for Aptos Keyless accounts.
  *
  * These keys are used only temporarily within Keyless accounts and are not utilized as public keys for account identification.
+ * @group Implementation
+ * @category Serialization
  */
 export class EphemeralPublicKey extends PublicKey {
   /**
    * The public key itself
+   * @group Implementation
+   * @category Serialization
    */
   public readonly publicKey: PublicKey;
 
   /**
    * An enum indicating the scheme of the ephemeral public key
+   * @group Implementation
+   * @category Serialization
    */
   public readonly variant: EphemeralPublicKeyVariant;
 
@@ -27,6 +33,8 @@ export class EphemeralPublicKey extends PublicKey {
    *
    * @param publicKey - The public key to be used for the ephemeral public key.
    * @throws Error if the signature type is unsupported.
+   * @group Implementation
+   * @category Serialization
    */
   constructor(publicKey: PublicKey) {
     super();
@@ -48,6 +56,8 @@ export class EphemeralPublicKey extends PublicKey {
    * @param args.message - The message that was signed.
    * @param args.signature - The signature that was signed by the private key of the ephemeral public key.
    * @returns true if the signature is valid, otherwise false.
+   * @group Implementation
+   * @category Serialization
    */
   verifySignature(args: { message: HexInput; signature: EphemeralSignature }): boolean {
     const { message, signature } = args;
@@ -60,6 +70,8 @@ export class EphemeralPublicKey extends PublicKey {
    *
    * @param serializer - The serializer instance used to serialize the signature.
    * @throws Error if the signature type is unknown.
+   * @group Implementation
+   * @category Serialization
    */
   serialize(serializer: Serializer): void {
     if (this.publicKey instanceof Ed25519PublicKey) {
@@ -75,6 +87,8 @@ export class EphemeralPublicKey extends PublicKey {
    * This function allows you to retrieve an EphemeralSignature based on the deserialized data.
    *
    * @param deserializer - The deserializer instance used to read the serialized data.
+   * @group Implementation
+   * @category Serialization
    */
   static deserialize(deserializer: Deserializer): EphemeralPublicKey {
     const index = deserializer.deserializeUleb128AsU32();
@@ -91,6 +105,8 @@ export class EphemeralPublicKey extends PublicKey {
    *
    * @param publicKey - The public key to check.
    * @returns A boolean indicating whether the public key is an ephemeral type.
+   * @group Implementation
+   * @category Serialization
    */
   static isPublicKey(publicKey: PublicKey): publicKey is EphemeralPublicKey {
     return publicKey instanceof EphemeralPublicKey;
@@ -101,10 +117,14 @@ export class EphemeralPublicKey extends PublicKey {
  * Represents ephemeral signatures used in Aptos Keyless accounts.
  *
  * These signatures are utilized within the KeylessSignature framework.
+ * @group Implementation
+ * @category Serialization
  */
 export class EphemeralSignature extends Signature {
   /**
    * The signature signed by the private key of an EphemeralKeyPair
+   * @group Implementation
+   * @category Serialization
    */
   public readonly signature: Signature;
 
@@ -126,6 +146,8 @@ export class EphemeralSignature extends Signature {
    * further processing.
    *
    * @param hexInput - The hexadecimal input representing the ephemeral signature.
+   * @group Implementation
+   * @category Serialization
    */
   static fromHex(hexInput: HexInput): EphemeralSignature {
     const data = Hex.fromHexInput(hexInput);

package/src/core/crypto/federatedKeyless.ts

@@ -14,15 +14,21 @@ import { KeylessPublicKey, KeylessSignature } from "./keyless";
  * These keys use an on-chain address as a source of truth for the JWK used to verify signatures.
  *
  * FederatedKeylessPublicKey authentication key is represented in the SDK as `AnyPublicKey`.
+ * @group Implementation
+ * @category Serialization
  */
 export class FederatedKeylessPublicKey extends AccountPublicKey {
   /**
    * The address that contains the JWK set to be used for verification.
+   * @group Implementation
+   * @category Serialization
    */
   readonly jwkAddress: AccountAddress;
 
   /**
    * The inner public key which contains the standard Keyless public key.
+   * @group Implementation
+   * @category Serialization
    */
   readonly keylessPublicKey: KeylessPublicKey;
 
@@ -36,6 +42,8 @@ export class FederatedKeylessPublicKey extends AccountPublicKey {
    * Get the authentication key for the federated keyless public key
    *
    * @returns AuthenticationKey
+   * @group Implementation
+   * @category Serialization
    */
   authKey(): AuthenticationKey {
     const serializer = new Serializer();
@@ -53,6 +61,8 @@ export class FederatedKeylessPublicKey extends AccountPublicKey {
    * @param args.message message
    * @param args.signature The signature
    * @returns true if the signature is valid
+   * @group Implementation
+   * @category Serialization
    */
   // eslint-disable-next-line @typescript-eslint/no-unused-vars, class-methods-use-this
   verifySignature(args: { message: HexInput; signature: KeylessSignature }): boolean {
@@ -83,6 +93,8 @@ export class FederatedKeylessPublicKey extends AccountPublicKey {
    * @param args.aud the client ID of the application
    * @param args.pepper The pepper used to maintain privacy of the account
    * @returns FederatedKeylessPublicKey
+   * @group Implementation
+   * @category Serialization
    */
   static create(args: {
     iss: string;

package/src/core/crypto/hdKey.ts

@@ -7,6 +7,8 @@ import * as bip39 from "@scure/bip39";
 
 /**
  * Contains the derived cryptographic key as a Uint8Array.
+ * @group Implementation
+ * @category Serialization
  */
 export type DerivedKeys = {
   key: Uint8Array;
@@ -15,17 +17,30 @@ export type DerivedKeys = {
 
 /**
  * Aptos derive path is 637
+ * @group Implementation
+ * @category Serialization
  */
 export const APTOS_HARDENED_REGEX = /^m\/44'\/637'\/[0-9]+'\/[0-9]+'\/[0-9]+'?$/;
+
+/**
+ * @group Implementation
+ * @category Serialization
+ */
 export const APTOS_BIP44_REGEX = /^m\/44'\/637'\/[0-9]+'\/[0-9]+\/[0-9]+$/;
 
 /**
  * Supported key types and their associated seeds.
+ * @group Implementation
+ * @category Serialization
  */
 export enum KeyType {
   ED25519 = "ed25519 seed",
 }
 
+/**
+ * @group Implementation
+ * @category Serialization
+ */
 export const HARDENED_OFFSET = 0x80000000;
 
 /**
@@ -37,6 +52,8 @@ export const HARDENED_OFFSET = 0x80000000;
  * Note that for Secp256k1, the last two components must be non-hardened.
  *
  * @param path - The path string to validate (e.g. `m/44'/637'/0'/0/0`).
+ * @group Implementation
+ * @category Serialization
  */
 export function isValidBIP44Path(path: string): boolean {
   return APTOS_BIP44_REGEX.test(path);
@@ -57,11 +74,17 @@ export function isValidBIP44Path(path: string): boolean {
  * with the hash function breaking the homomorphism.
  *
  * @param path - The derivation path string to validate (e.g. `m/44'/637'/0'/0'/0'`).
+ * @group Implementation
+ * @category Serialization
  */
 export function isValidHardenedPath(path: string): boolean {
   return APTOS_HARDENED_REGEX.test(path);
 }
 
+/**
+ * @group Implementation
+ * @category Serialization
+ */
 export const deriveKey = (hashSeed: Uint8Array | string, data: Uint8Array | string): DerivedKeys => {
   const digest = hmac.create(sha512, hashSeed).update(data).digest();
   return {
@@ -75,6 +98,8 @@ export const deriveKey = (hashSeed: Uint8Array | string, data: Uint8Array | stri
  * @param key
  * @param chainCode
  * @param index
+ * @group Implementation
+ * @category Serialization
  */
 export const CKDPriv = ({ key, chainCode }: DerivedKeys, index: number): DerivedKeys => {
   const buffer = new ArrayBuffer(4);
@@ -90,12 +115,16 @@ const removeApostrophes = (val: string): string => val.replace(/'/g, "");
 /**
  * Splits derive path into segments
  * @param path
+ * @group Implementation
+ * @category Serialization
  */
 export const splitPath = (path: string): Array<string> => path.split("/").slice(1).map(removeApostrophes);
 
 /**
  * Normalizes the mnemonic by removing extra whitespace and making it lowercase
  * @param mnemonic the mnemonic seed phrase
+ * @group Implementation
+ * @category Serialization
  */
 export const mnemonicToSeed = (mnemonic: string): Uint8Array => {
   const normalizedMnemonic = mnemonic