@aptos-labs/ts-sdk 1.33.1 → 1.33.2

package/src/account/Account.ts

@@ -2,7 +2,7 @@ import type { AccountAuthenticator } from "../transactions/authenticator/account
 import { HexInput, SigningScheme, SigningSchemeInput } from "../types";
 import type { AccountAddress, AccountAddressInput } from "../core/accountAddress";
 import { AuthenticationKey } from "../core/authenticationKey";
-import { AccountPublicKey, Ed25519PrivateKey, PrivateKey, Signature, VerifySignatureArgs } from "../core/crypto";
+import { AccountPublicKey, Ed25519PrivateKey, PrivateKeyInput, Signature, VerifySignatureArgs } from "../core/crypto";
 import { Ed25519Account } from "./Ed25519Account";
 import { SingleKeyAccount } from "./SingleKeyAccount";
 import { AnyRawTransaction } from "../transactions/types";
@@ -14,6 +14,8 @@ import { AnyRawTransaction } from "../transactions/types";
  * @param privateKey - The private key used to create the account.
  * @param address - Optional address for the account.
  * @param legacy - Indicates whether to use legacy authentication (default is true).
+ * @group Implementation
+ * @category Account (On-Chain Model)
  */
 export interface CreateEd25519AccountFromPrivateKeyArgs {
   privateKey: Ed25519PrivateKey;
@@ -28,6 +30,8 @@ export interface CreateEd25519AccountFromPrivateKeyArgs {
  * @param privateKey - The Ed25519 private key used for account creation.
  * @param address - Optional account address input.
  * @param legacy - Must be false to enable the `SingleKey` authentication scheme.
+ * @group Implementation
+ * @category Account (On-Chain Model)
  */
 export interface CreateEd25519SingleKeyAccountFromPrivateKeyArgs {
   privateKey: Ed25519PrivateKey;
@@ -42,9 +46,11 @@ export interface CreateEd25519SingleKeyAccountFromPrivateKeyArgs {
  * @param privateKey - The private key used to create the account.
  * @param address - Optional address input for the account.
  * @param legacy - Always false; cannot be explicitly set to true.
+ * @group Implementation
+ * @category Account (On-Chain Model)
  */
 export interface CreateSingleKeyAccountFromPrivateKeyArgs {
-  privateKey: Exclude<PrivateKey, Ed25519PrivateKey>;
+  privateKey: PrivateKeyInput;
   address?: AccountAddressInput;
   legacy?: false;
 }
@@ -55,9 +61,11 @@ export interface CreateSingleKeyAccountFromPrivateKeyArgs {
  * @param privateKey - The private key used to create the account.
  * @param address - Optional address for the account.
  * @param legacy - Optional flag indicating if the account is a legacy account.
+ * @group Implementation
+ * @category Account (On-Chain Model)
  */
 export interface CreateAccountFromPrivateKeyArgs {
-  privateKey: PrivateKey;
+  privateKey: PrivateKeyInput;
   address?: AccountAddressInput;
   legacy?: boolean;
 }
@@ -67,6 +75,8 @@ export interface CreateAccountFromPrivateKeyArgs {
  *
  * @param scheme - The signing scheme to use for the account.
  * @param legacy - Indicates if the account should be created in legacy mode.
+ * @group Implementation
+ * @category Account (On-Chain Model)
  */
 export interface GenerateEd25519AccountArgs {
   scheme?: SigningSchemeInput.Ed25519;
@@ -79,6 +89,8 @@ export interface GenerateEd25519AccountArgs {
  *
  * @param scheme - Optional signing scheme input for the account.
  * @param legacy - Indicates whether to use legacy account generation.
+ * @group Implementation
+ * @category Account (On-Chain Model)
  */
 export interface GenerateEd25519SingleKeyAccountArgs {
   scheme?: SigningSchemeInput.Ed25519;
@@ -91,6 +103,8 @@ export interface GenerateEd25519SingleKeyAccountArgs {
  *
  * @param scheme - The signing scheme to use for the account.
  * @param legacy - Indicates whether to use legacy account generation (defaults to false).
+ * @group Implementation
+ * @category Account (On-Chain Model)
  */
 export interface GenerateSingleKeyAccountArgs {
   scheme: Exclude<SigningSchemeInput, SigningSchemeInput.Ed25519>;
@@ -102,6 +116,8 @@ export interface GenerateSingleKeyAccountArgs {
  *
  * @param scheme - The signing scheme to use for account generation.
  * @param legacy - Indicates whether to use legacy account generation methods.
+ * @group Implementation
+ * @category Account (On-Chain Model)
  */
 export interface GenerateAccountArgs {
   scheme?: SigningSchemeInput;
@@ -113,6 +129,8 @@ export interface GenerateAccountArgs {
  *
  * @param path - The BIP44 derivation path for the key.
  * @param mnemonic - The mnemonic phrase used for key generation.
+ * @group Implementation
+ * @category Account (On-Chain Model)
  */
 export interface PrivateKeyFromDerivationPathArgs {
   path: string;
@@ -127,20 +145,28 @@ export interface PrivateKeyFromDerivationPathArgs {
  * abstract class, it should be treated as an interface and enforced using the `implements` keyword.
  *
  * Note: Generating an account instance does not create the account on-chain.
+ * @group Implementation
+ * @category Account (On-Chain Model)
  */
 export abstract class Account {
   /**
    * Public key associated with the account
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   abstract readonly publicKey: AccountPublicKey;
 
   /**
    * Account address associated with the account
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   abstract readonly accountAddress: AccountAddress;
 
   /**
    * Signing scheme used to sign transactions
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   abstract signingScheme: SigningScheme;
 
@@ -151,6 +177,8 @@ export abstract class Account {
    * @param args - The arguments for generating the account.
    * @param args.scheme - The signing scheme to use for account generation. Defaults to Ed25519.
    * @param args.legacy - Indicates whether to use the legacy account generation method. Defaults to true.
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   static generate(args?: GenerateEd25519AccountArgs): Ed25519Account;
   static generate(args: GenerateEd25519SingleKeyAccountArgs): SingleKeyAccount;
@@ -174,12 +202,13 @@ export abstract class Account {
    * @param args.address - The address associated with the account.
    * @param args.legacy - A boolean indicating whether to create a legacy account (default is true).
    * @returns An instance of either Ed25519Account or SingleKeyAccount based on the provided private key.
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   static fromPrivateKey(args: CreateEd25519AccountFromPrivateKeyArgs): Ed25519Account;
-  static fromPrivateKey(args: CreateEd25519SingleKeyAccountFromPrivateKeyArgs): SingleKeyAccount;
   static fromPrivateKey(args: CreateSingleKeyAccountFromPrivateKeyArgs): SingleKeyAccount;
-  static fromPrivateKey(args: CreateAccountFromPrivateKeyArgs): Account;
-  static fromPrivateKey(args: CreateAccountFromPrivateKeyArgs) {
+  static fromPrivateKey(args: CreateAccountFromPrivateKeyArgs): SingleKeyAccount;
+  static fromPrivateKey(args: CreateAccountFromPrivateKeyArgs): Ed25519Account | SingleKeyAccount {
     const { privateKey, address, legacy = true } = args;
     if (privateKey instanceof Ed25519PrivateKey && legacy) {
       return new Ed25519Account({
@@ -202,6 +231,8 @@ export abstract class Account {
    * Ed25519 keypair.
    *
    * @returns Account
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   static fromPrivateKeyAndAddress(args: CreateAccountFromPrivateKeyArgs) {
     return this.fromPrivateKey(args);
@@ -216,6 +247,8 @@ export abstract class Account {
    * @param args.mnemonic - The mnemonic phrase used to derive the account.
    * @param args.path - The derivation path used to generate the account.
    * @param args.legacy - A boolean indicating whether to use the legacy account generation method. Defaults to true.
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   static fromDerivationPath(args: GenerateEd25519AccountArgs & PrivateKeyFromDerivationPathArgs): Ed25519Account;
   static fromDerivationPath(
@@ -240,6 +273,8 @@ export abstract class Account {
    * @param args - The arguments for retrieving the authentication key.
    * @param args.publicKey - The public key of the account.
    * @returns The authentication key for the associated account.
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   static authKey(args: { publicKey: AccountPublicKey }): AuthenticationKey {
     const { publicKey } = args;
@@ -250,6 +285,8 @@ export abstract class Account {
    * Sign a message using the available signing capabilities.
    * @param message the signing message, as binary input
    * @return the AccountAuthenticator containing the signature, together with the account's public key
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   abstract signWithAuthenticator(message: HexInput): AccountAuthenticator;
 
@@ -257,6 +294,8 @@ export abstract class Account {
    * Sign a transaction using the available signing capabilities.
    * @param transaction the raw transaction
    * @return the AccountAuthenticator containing the signature of the transaction, together with the account's public key
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   abstract signTransactionWithAuthenticator(transaction: AnyRawTransaction): AccountAuthenticator;
 
@@ -264,6 +303,8 @@ export abstract class Account {
    * Sign the given message using the available signing capabilities.
    * @param message in HexInput format
    * @returns Signature
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   abstract sign(message: HexInput): Signature;
 
@@ -271,6 +312,8 @@ export abstract class Account {
    * Sign the given transaction using the available signing capabilities.
    * @param transaction the transaction to be signed
    * @returns Signature
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   abstract signTransaction(transaction: AnyRawTransaction): Signature;
 
@@ -282,6 +325,8 @@ export abstract class Account {
    * @param args.message - The raw message data in HexInput format.
    * @param args.signature - The signed message signature.
    * @returns A boolean indicating whether the signature is valid.
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   verifySignature(args: VerifySignatureArgs): boolean {
     return this.publicKey.verifySignature(args);

package/src/account/AccountUtils.ts

@@ -0,0 +1,216 @@
+import { Deserializer, Serializer } from "../bcs";
+import { AnyPublicKeyVariant, HexInput, SigningScheme } from "../types";
+import { MultiKeyAccount } from "./MultiKeyAccount";
+import { Account } from "./Account";
+import { Ed25519Account } from "./Ed25519Account";
+import { isSingleKeySigner, SingleKeyAccount, SingleKeySignerOrLegacyEd25519Account } from "./SingleKeyAccount";
+import { KeylessAccount } from "./KeylessAccount";
+import { FederatedKeylessAccount } from "./FederatedKeylessAccount";
+import { AbstractKeylessAccount } from "./AbstractKeylessAccount";
+import {
+  AccountAddress,
+  Ed25519PrivateKey,
+  getIssAudAndUidVal,
+  Hex,
+  MultiKey,
+  Secp256k1PrivateKey,
+  ZeroKnowledgeSig,
+} from "../core";
+import { deserializeSchemeAndAddress } from "./utils";
+import { EphemeralKeyPair } from "./EphemeralKeyPair";
+
+function serializeKeylessAccountCommon(account: AbstractKeylessAccount, serializer: Serializer): void {
+  serializer.serializeStr(account.jwt);
+  serializer.serializeStr(account.uidKey);
+  serializer.serializeFixedBytes(account.pepper);
+  account.ephemeralKeyPair.serialize(serializer);
+  if (account.proof === undefined) {
+    throw new Error("Cannot serialize - proof undefined");
+  }
+  account.proof.serialize(serializer);
+  serializer.serializeOption(account.verificationKeyHash, 32);
+}
+
+function deserializeKeylessAccountCommon(deserializer: Deserializer): {
+  jwt: string;
+  uidKey: string;
+  pepper: Uint8Array;
+  ephemeralKeyPair: EphemeralKeyPair;
+  proof: ZeroKnowledgeSig;
+  verificationKeyHash?: Uint8Array;
+} {
+  const jwt = deserializer.deserializeStr();
+  const uidKey = deserializer.deserializeStr();
+  const pepper = deserializer.deserializeFixedBytes(31);
+  const ephemeralKeyPair = EphemeralKeyPair.deserialize(deserializer);
+  const proof = ZeroKnowledgeSig.deserialize(deserializer);
+  const verificationKeyHash = deserializer.deserializeOption("fixedBytes", 32);
+  return { jwt, uidKey, pepper, ephemeralKeyPair, proof, verificationKeyHash };
+}
+
+/**
+ * Utility functions for working with accounts.
+ */
+export namespace AccountUtils {
+  export function toBytes(account: Account): Uint8Array {
+    const serializer = new Serializer();
+    serializer.serializeU32AsUleb128(account.signingScheme);
+    account.accountAddress.serialize(serializer);
+    switch (account.signingScheme) {
+      case SigningScheme.Ed25519:
+        (account as Ed25519Account).privateKey.serialize(serializer);
+        return serializer.toUint8Array();
+      case SigningScheme.SingleKey: {
+        if (!isSingleKeySigner(account)) {
+          throw new Error("Account is not a SingleKeySigner");
+        }
+        const anyPublicKey = account.getAnyPublicKey();
+        serializer.serializeU32AsUleb128(anyPublicKey.variant);
+        switch (anyPublicKey.variant) {
+          case AnyPublicKeyVariant.Keyless: {
+            const keylessAccount = account as KeylessAccount;
+            serializeKeylessAccountCommon(keylessAccount, serializer);
+            return serializer.toUint8Array();
+          }
+          case AnyPublicKeyVariant.FederatedKeyless: {
+            const federatedKeylessAccount = account as FederatedKeylessAccount;
+            serializeKeylessAccountCommon(federatedKeylessAccount, serializer);
+            federatedKeylessAccount.publicKey.jwkAddress.serialize(serializer);
+            serializer.serializeBool(federatedKeylessAccount.audless);
+            return serializer.toUint8Array();
+          }
+          case AnyPublicKeyVariant.Secp256k1:
+          case AnyPublicKeyVariant.Ed25519: {
+            const singleKeyAccount = account as SingleKeyAccount;
+            singleKeyAccount.privateKey.serialize(serializer);
+            return serializer.toUint8Array();
+          }
+          default: {
+            throw new Error(`Invalid public key variant: ${anyPublicKey.variant}`);
+          }
+        }
+      }
+      case SigningScheme.MultiKey: {
+        const multiKeyAccount = account as MultiKeyAccount;
+        multiKeyAccount.publicKey.serialize(serializer);
+        serializer.serializeU32AsUleb128(multiKeyAccount.signers.length);
+        multiKeyAccount.signers.forEach((signer) => {
+          serializer.serializeFixedBytes(toBytes(signer));
+        });
+        return serializer.toUint8Array();
+      }
+      default:
+        throw new Error(`Deserialization of Account failed: invalid signingScheme value ${account.signingScheme}`);
+    }
+  }
+
+  export function toHexStringWithoutPrefix(account: Account): string {
+    return Hex.hexInputToStringWithoutPrefix(toBytes(account));
+  }
+
+  export function toHexString(account: Account): string {
+    return Hex.hexInputToString(toBytes(account));
+  }
+
+  export function deserialize(deserializer: Deserializer): Account {
+    const { address, signingScheme } = deserializeSchemeAndAddress(deserializer);
+    switch (signingScheme) {
+      case SigningScheme.Ed25519: {
+        const privateKey = Ed25519PrivateKey.deserialize(deserializer);
+        return new Ed25519Account({ privateKey, address });
+      }
+      case SigningScheme.SingleKey: {
+        const variantIndex = deserializer.deserializeUleb128AsU32();
+        switch (variantIndex) {
+          case AnyPublicKeyVariant.Ed25519: {
+            const privateKey = Ed25519PrivateKey.deserialize(deserializer);
+            return new SingleKeyAccount({ privateKey, address });
+          }
+          case AnyPublicKeyVariant.Secp256k1: {
+            const privateKey = Secp256k1PrivateKey.deserialize(deserializer);
+            return new SingleKeyAccount({ privateKey, address });
+          }
+          case AnyPublicKeyVariant.Keyless: {
+            const keylessComponents = deserializeKeylessAccountCommon(deserializer);
+            const jwtClaims = getIssAudAndUidVal(keylessComponents);
+            return new KeylessAccount({ ...keylessComponents, ...jwtClaims });
+          }
+          case AnyPublicKeyVariant.FederatedKeyless: {
+            const keylessComponents = deserializeKeylessAccountCommon(deserializer);
+            const jwkAddress = AccountAddress.deserialize(deserializer);
+            const audless = deserializer.deserializeBool();
+            const jwtClaims = getIssAudAndUidVal(keylessComponents);
+            return new FederatedKeylessAccount({ ...keylessComponents, ...jwtClaims, jwkAddress, audless });
+          }
+          default:
+            throw new Error(`Unsupported public key variant ${variantIndex}`);
+        }
+      }
+      case SigningScheme.MultiKey: {
+        const multiKey = MultiKey.deserialize(deserializer);
+        const length = deserializer.deserializeUleb128AsU32();
+        const signers = new Array<SingleKeySignerOrLegacyEd25519Account>();
+        for (let i = 0; i < length; i += 1) {
+          const signer = deserialize(deserializer);
+          if (!isSingleKeySigner(signer) && !(signer instanceof Ed25519Account)) {
+            throw new Error(
+              "Deserialization of MultiKeyAccount failed. Signer is not a SingleKeySigner or Ed25519Account",
+            );
+          }
+          signers.push(signer);
+        }
+        return new MultiKeyAccount({ multiKey, signers, address });
+      }
+      default:
+        throw new Error(`Deserialization of Account failed: invalid signingScheme value ${signingScheme}`);
+    }
+  }
+
+  export function keylessAccountFromHex(hex: HexInput): KeylessAccount {
+    const account = fromHex(hex);
+    if (!(account instanceof KeylessAccount)) {
+      throw new Error("Deserialization of KeylessAccount failed");
+    }
+    return account;
+  }
+
+  export function federatedKeylessAccountFromHex(hex: HexInput): FederatedKeylessAccount {
+    const account = fromHex(hex);
+    if (!(account instanceof FederatedKeylessAccount)) {
+      throw new Error("Deserialization of FederatedKeylessAccount failed");
+    }
+    return account;
+  }
+
+  export function multiKeyAccountFromHex(hex: HexInput): MultiKeyAccount {
+    const account = fromHex(hex);
+    if (!(account instanceof MultiKeyAccount)) {
+      throw new Error("Deserialization of MultiKeyAccount failed");
+    }
+    return account;
+  }
+
+  export function singleKeyAccountFromHex(hex: HexInput): SingleKeyAccount {
+    const account = fromHex(hex);
+    if (!(account instanceof SingleKeyAccount)) {
+      throw new Error("Deserialization of SingleKeyAccount failed");
+    }
+    return account;
+  }
+
+  export function ed25519AccountFromHex(hex: HexInput): Ed25519Account {
+    const account = fromHex(hex);
+    if (!(account instanceof Ed25519Account)) {
+      throw new Error("Deserialization of Ed25519Account failed");
+    }
+    return account;
+  }
+
+  export function fromHex(hex: HexInput): Account {
+    return deserialize(Deserializer.fromHex(hex));
+  }
+
+  export function fromBytes(bytes: Uint8Array): Account {
+    return fromHex(bytes);
+  }
+}

package/src/account/Ed25519Account.ts

@@ -11,6 +11,8 @@ import { generateSigningMessageForTransaction } from "../transactions/transactio
  *
  * @param privateKey - The private key used for signing.
  * @param address - Optional account address associated with the signer.
+ * @group Implementation
+ * @category Account (On-Chain Model)
  */
 export interface Ed25519SignerConstructorArgs {
   privateKey: Ed25519PrivateKey;
@@ -22,6 +24,8 @@ export interface Ed25519SignerConstructorArgs {
  *
  * @param path - The derivation path for the Ed25519 key.
  * @param mnemonic - The mnemonic phrase used to generate the key.
+ * @group Implementation
+ * @category Account (On-Chain Model)
  */
 export interface Ed25519SignerFromDerivationPathArgs {
   path: string;
@@ -33,6 +37,8 @@ export interface Ed25519SignerFromDerivationPathArgs {
  *
  * @param message - The message to be verified, represented in hexadecimal format.
  * @param signature - The Ed25519 signature to validate.
+ * @group Implementation
+ * @category Account (On-Chain Model)
  */
 export interface VerifyEd25519SignatureArgs {
   message: HexInput;
@@ -44,10 +50,14 @@ export interface VerifyEd25519SignatureArgs {
  * This class allows for the creation of accounts, signing messages and transactions, and verifying signatures.
  *
  * Note: Generating an instance of this class does not create the account on-chain.
+ * @group Implementation
+ * @category Account (On-Chain Model)
  */
 export class Ed25519Account implements Account {
   /**
    * Private key associated with the account
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   readonly privateKey: Ed25519PrivateKey;
 
@@ -66,6 +76,8 @@ export class Ed25519Account implements Account {
    * @param args - The constructor arguments for the Ed25519Signer.
    * @param args.privateKey - The private key used for signing.
    * @param args.address - The optional account address; if not provided, it will derive the address from the public key.
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   constructor(args: Ed25519SignerConstructorArgs) {
     const { privateKey, address } = args;
@@ -79,6 +91,8 @@ export class Ed25519Account implements Account {
    * This function is useful for creating a signer that can be used for cryptographic operations.
    *
    * @returns {Ed25519Account} The newly generated Ed25519 account.
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   static generate(): Ed25519Account {
     const privateKey = Ed25519PrivateKey.generate();
@@ -92,6 +106,8 @@ export class Ed25519Account implements Account {
    * @param args.path - The BIP44 derive hardened path, e.g., m/44'/637'/0'/0'/0'.
    * Detailed description: {@link https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki}
    * @param args.mnemonic - The mnemonic seed phrase of the account.
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   static fromDerivationPath(args: Ed25519SignerFromDerivationPathArgs) {
     const { path, mnemonic } = args;
@@ -108,6 +124,8 @@ export class Ed25519Account implements Account {
    * @param args.message - Raw message data in HexInput format.
    * @param args.signature - Signed message signature.
    * @returns A boolean indicating whether the signature is valid.
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   verifySignature(args: VerifyEd25519SignatureArgs): boolean {
     return this.publicKey.verifySignature(args);
@@ -119,6 +137,8 @@ export class Ed25519Account implements Account {
    *
    * @param message - The signing message, represented as hexadecimal input.
    * @returns An AccountAuthenticator containing the signature and the account's public key.
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   signWithAuthenticator(message: HexInput): AccountAuthenticatorEd25519 {
     return new AccountAuthenticatorEd25519(this.publicKey, this.privateKey.sign(message));
@@ -130,6 +150,8 @@ export class Ed25519Account implements Account {
    *
    * @param transaction - The raw transaction to be signed.
    * @returns An AccountAuthenticator containing the signature and the public key.
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   signTransactionWithAuthenticator(transaction: AnyRawTransaction): AccountAuthenticatorEd25519 {
     return new AccountAuthenticatorEd25519(this.publicKey, this.signTransaction(transaction));
@@ -139,6 +161,8 @@ export class Ed25519Account implements Account {
    * Sign the given message using the account's Ed25519 private key.
    * @param message - The message to be signed in HexInput format.
    * @returns Signature - The resulting signature of the signed message.
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   sign(message: HexInput): Ed25519Signature {
     return this.privateKey.sign(message);
@@ -150,6 +174,8 @@ export class Ed25519Account implements Account {
    *
    * @param transaction - The transaction to be signed.
    * @returns Signature - The resulting signature for the transaction.
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   signTransaction(transaction: AnyRawTransaction): Ed25519Signature {
     return this.sign(generateSigningMessageForTransaction(transaction));

package/src/account/EphemeralKeyPair.ts

@@ -24,6 +24,8 @@ const TWO_WEEKS_IN_SECONDS = 1_209_600;
  * This key pair is temporary and includes an expiration time.
  * For more details on how this class is used, refer to the documentation:
  * https://aptos.dev/guides/keyless-accounts/#1-present-the-user-with-a-sign-in-with-idp-button-on-the-ui
+ * @group Implementation
+ * @category Account (On-Chain Model)
  */
 export class EphemeralKeyPair extends Serializable {
   static readonly BLINDER_LENGTH: number = 31;
@@ -31,30 +33,40 @@ export class EphemeralKeyPair extends Serializable {
   /**
    * A byte array of length BLINDER_LENGTH used to obfuscate the public key from the IdP.
    * Used in calculating the nonce passed to the IdP and as a secret witness in proof generation.
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   readonly blinder: Uint8Array;
 
   /**
    * A timestamp in seconds indicating when the ephemeral key pair is expired.  After expiry, a new
    * EphemeralKeyPair must be generated and a new JWT needs to be created.
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   readonly expiryDateSecs: number;
 
   /**
    * The value passed to the IdP when the user authenticates.  It consists of a hash of the
    * ephemeral public key, expiry date, and blinder.
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   readonly nonce: string;
 
   /**
    * A private key used to sign transactions.  This private key is not tied to any account on the chain as it
    * is ephemeral (not permanent) in nature.
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   private privateKey: PrivateKey;
 
   /**
    * A public key used to verify transactions.  This public key is not tied to any account on the chain as it
    * is ephemeral (not permanent) in nature.
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   private publicKey: EphemeralPublicKey;
 
@@ -67,6 +79,8 @@ export class EphemeralKeyPair extends Serializable {
    * @param args.privateKey - The private key used for creating the instance.
    * @param args.expiryDateSecs - Optional expiry date in seconds from the current time. Defaults to two weeks from now.
    * @param args.blinder - Optional blinder value. If not provided, a new blinder will be generated.
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   constructor(args: { privateKey: PrivateKey; expiryDateSecs?: number; blinder?: HexInput }) {
     super();
@@ -88,6 +102,8 @@ export class EphemeralKeyPair extends Serializable {
   /**
    * Returns the public key of the key pair.
    * @return EphemeralPublicKey
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   getPublicKey(): EphemeralPublicKey {
     return this.publicKey;
@@ -96,6 +112,8 @@ export class EphemeralKeyPair extends Serializable {
   /**
    * Checks if the current time has surpassed the expiry date of the key pair.
    * @return boolean - Returns true if the key pair is expired, otherwise false.
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   isExpired(): boolean {
     const currentTimeSecs: number = Math.floor(Date.now() / 1000);
@@ -107,6 +125,8 @@ export class EphemeralKeyPair extends Serializable {
    * This function is essential for preparing the object data for serialization processes.
    *
    * @param serializer - The serializer instance used to serialize the object's properties.
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   serialize(serializer: Serializer): void {
     serializer.serializeU32AsUleb128(this.publicKey.variant);
@@ -120,6 +140,8 @@ export class EphemeralKeyPair extends Serializable {
    * This function helps in reconstructing an ephemeral key pair, which is essential for cryptographic operations.
    *
    * @param deserializer - The deserializer instance used to read the serialized data.
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   static deserialize(deserializer: Deserializer): EphemeralKeyPair {
     const variantIndex = deserializer.deserializeUleb128AsU32();
@@ -141,6 +163,8 @@ export class EphemeralKeyPair extends Serializable {
    * This function allows you to reconstruct an EphemeralKeyPair from its serialized byte representation.
    *
    * @param bytes - The byte array representing the serialized EphemeralKeyPair.
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   static fromBytes(bytes: Uint8Array): EphemeralKeyPair {
     return EphemeralKeyPair.deserialize(new Deserializer(bytes));
@@ -154,6 +178,8 @@ export class EphemeralKeyPair extends Serializable {
    * @param args.scheme - The type of key pair to use for the EphemeralKeyPair. Only Ed25519 is supported for now.
    * @param args.expiryDateSecs - The date of expiry for the key pair in seconds.
    * @returns An instance of EphemeralKeyPair containing the generated private key and expiry date.
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   static generate(args?: { scheme?: EphemeralPublicKeyVariant; expiryDateSecs?: number }): EphemeralKeyPair {
     let privateKey: PrivateKey;
@@ -174,6 +200,8 @@ export class EphemeralKeyPair extends Serializable {
    * @param data - The data to be signed, provided in HexInput format.
    * @returns EphemeralSignature - The resulting ephemeral signature.
    * @throws Error - Throws an error if the EphemeralKeyPair has expired.
+   * @group Implementation
+   * @category Account (On-Chain Model)
    */
   sign(data: HexInput): EphemeralSignature {
     if (this.isExpired()) {
@@ -186,6 +214,8 @@ export class EphemeralKeyPair extends Serializable {
 /**
  * Generates a random byte array of length EphemeralKeyPair.BLINDER_LENGTH.
  * @returns Uint8Array A random byte array used for blinding.
+ * @group Implementation
+ * @category Account (On-Chain Model)
  */
 function generateBlinder(): Uint8Array {
   return randomBytes(EphemeralKeyPair.BLINDER_LENGTH);