@aptos-labs/ts-sdk 1.28.0 → 1.29.0

package/src/account/KeylessAccount.ts

@@ -2,103 +2,25 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { JwtPayload, jwtDecode } from "jwt-decode";
-import EventEmitter from "eventemitter3";
-import { EphemeralCertificateVariant, HexInput, SigningScheme } from "../types";
+import { HexInput } from "../types";
 import { AccountAddress } from "../core/accountAddress";
-import {
-  AnyPublicKey,
-  AnySignature,
-  KeylessPublicKey,
-  KeylessSignature,
-  EphemeralCertificate,
-  ZeroKnowledgeSig,
-  ZkProof,
-} from "../core/crypto";
+import { ZeroKnowledgeSig } from "../core/crypto";
 
-import { Account } from "./Account";
 import { EphemeralKeyPair } from "./EphemeralKeyPair";
-import { Hex } from "../core/hex";
-import { AccountAuthenticatorSingleKey } from "../transactions/authenticator/account";
-import { Deserializer, Serializable, Serializer } from "../bcs";
-import { deriveTransactionType, generateSigningMessage } from "../transactions/transactionBuilder/signingMessage";
-import { AnyRawTransaction, AnyRawTransactionInstance } from "../transactions/types";
-import { base64UrlDecode } from "../utils/helpers";
+import { Deserializer, Serializer } from "../bcs";
+import { AbstractKeylessAccount, ProofFetchCallback } from "./AbstractKeylessAccount";
 
 /**
  * Account implementation for the Keyless authentication scheme.
  *
  * Used to represent a Keyless based account and sign transactions with it.
  *
- * Use KeylessAccount.fromJWTAndProof to instantiate a KeylessAccount with a JWT, proof and EphemeralKeyPair.
+ * Use KeylessAccount.create to instantiate a KeylessAccount with a JWT, proof and EphemeralKeyPair.
  *
  * When the proof expires or the JWT becomes invalid, the KeylessAccount must be instantiated again with a new JWT,
  * EphemeralKeyPair, and corresponding proof.
  */
-export class KeylessAccount extends Serializable implements Account {
-  static readonly PEPPER_LENGTH: number = 31;
-
-  /**
-   * The KeylessPublicKey associated with the account
-   */
-  readonly publicKey: KeylessPublicKey;
-
-  /**
-   * The EphemeralKeyPair used to generate sign.
-   */
-  readonly ephemeralKeyPair: EphemeralKeyPair;
-
-  /**
-   * The claim on the JWT to identify a user.  This is typically 'sub' or 'email'.
-   */
-  readonly uidKey: string;
-
-  /**
-   * The value of the uidKey claim on the JWT.  This intended to be a stable user identifier.
-   */
-  readonly uidVal: string;
-
-  /**
-   * The value of the 'aud' claim on the JWT, also known as client ID.  This is the identifier for the dApp's
-   * OIDC registration with the identity provider.
-   */
-  readonly aud: string;
-
-  /**
-   * A value contains 31 bytes of entropy that preserves privacy of the account. Typically fetched from a pepper provider.
-   */
-  readonly pepper: Uint8Array;
-
-  /**
-   * Account address associated with the account
-   */
-  readonly accountAddress: AccountAddress;
-
-  /**
-   * The zero knowledge signature (if ready) which contains the proof used to validate the EphemeralKeyPair.
-   */
-  proof: ZeroKnowledgeSig | undefined;
-
-  /**
-   * The proof of the EphemeralKeyPair or a promise that provides the proof.  This is used to allow for awaiting on
-   * fetching the proof.
-   */
-  readonly proofOrPromise: ZeroKnowledgeSig | Promise<ZeroKnowledgeSig>;
-
-  /**
-   * Signing scheme used to sign transactions
-   */
-  readonly signingScheme: SigningScheme;
-
-  /**
-   * The JWT token used to derive the account
-   */
-  readonly jwt: string;
-
-  /**
-   * An event emitter used to assist in handling asycronous proof fetching.
-   */
-  private readonly emitter: EventEmitter<ProofFetchEvents>;
-
+export class KeylessAccount extends AbstractKeylessAccount {
   // Use the static constructor 'create' instead.
   private constructor(args: {
     address?: AccountAddress;
@@ -112,52 +34,7 @@ export class KeylessAccount extends Serializable implements Account {
     proofFetchCallback?: ProofFetchCallback;
     jwt: string;
   }) {
-    super();
-    const { address, ephemeralKeyPair, uidKey, uidVal, aud, pepper, proof, proofFetchCallback, jwt } = args;
-    this.ephemeralKeyPair = ephemeralKeyPair;
-    this.publicKey = KeylessPublicKey.create(args);
-    this.accountAddress = address ? AccountAddress.from(address) : this.publicKey.authKey().derivedAddress();
-    this.uidKey = uidKey;
-    this.uidVal = uidVal;
-    this.aud = aud;
-    this.jwt = jwt;
-    this.emitter = new EventEmitter<ProofFetchEvents>();
-    this.proofOrPromise = proof;
-    if (proof instanceof ZeroKnowledgeSig) {
-      this.proof = proof;
-    } else {
-      if (proofFetchCallback === undefined) {
-        throw new Error("Must provide callback for async proof fetch");
-      }
-      this.emitter.on("proofFetchFinish", async (status) => {
-        await proofFetchCallback(status);
-        this.emitter.removeAllListeners();
-      });
-      this.init(proof);
-    }
-    this.signingScheme = SigningScheme.SingleKey;
-    const pepperBytes = Hex.fromHexInput(pepper).toUint8Array();
-    if (pepperBytes.length !== KeylessAccount.PEPPER_LENGTH) {
-      throw new Error(`Pepper length in bytes should be ${KeylessAccount.PEPPER_LENGTH}`);
-    }
-    this.pepper = pepperBytes;
-  }
-
-  /**
-   * This initializes the asyncronous proof fetch
-   * @return
-   */
-  async init(promise: Promise<ZeroKnowledgeSig>) {
-    try {
-      this.proof = await promise;
-      this.emitter.emit("proofFetchFinish", { status: "Success" });
-    } catch (error) {
-      if (error instanceof Error) {
-        this.emitter.emit("proofFetchFinish", { status: "Failed", error: error.toString() });
-      } else {
-        this.emitter.emit("proofFetchFinish", { status: "Failed", error: "Unknown" });
-      }
-    }
+    super(args);
   }
 
   serialize(serializer: Serializer): void {
@@ -166,7 +43,7 @@ export class KeylessAccount extends Serializable implements Account {
     serializer.serializeFixedBytes(this.pepper);
     this.ephemeralKeyPair.serialize(serializer);
     if (this.proof === undefined) {
-      throw new Error("Connot serialize - proof undefined");
+      throw new Error("Cannot serialize - proof undefined");
     }
     this.proof.serialize(serializer);
   }
@@ -186,110 +63,6 @@ export class KeylessAccount extends Serializable implements Account {
     });
   }
 
-  /**
-   * Checks if the proof is expired.  If so the account must be rederived with a new EphemeralKeyPair
-   * and JWT token.
-   * @return boolean
-   */
-  isExpired(): boolean {
-    return this.ephemeralKeyPair.isExpired();
-  }
-
-  /**
-   * Sign a message using Keyless.
-   * @param message the message to sign, as binary input
-   * @return the AccountAuthenticator containing the signature, together with the account's public key
-   */
-  signWithAuthenticator(message: HexInput): AccountAuthenticatorSingleKey {
-    const signature = new AnySignature(this.sign(message));
-    const publicKey = new AnyPublicKey(this.publicKey);
-    return new AccountAuthenticatorSingleKey(publicKey, signature);
-  }
-
-  /**
-   * Sign a transaction using Keyless.
-   * @param transaction the raw transaction
-   * @return the AccountAuthenticator containing the signature of the transaction, together with the account's public key
-   */
-  signTransactionWithAuthenticator(transaction: AnyRawTransaction): AccountAuthenticatorSingleKey {
-    const signature = new AnySignature(this.signTransaction(transaction));
-    const publicKey = new AnyPublicKey(this.publicKey);
-    return new AccountAuthenticatorSingleKey(publicKey, signature);
-  }
-
-  /**
-   * Waits for asyncronous proof fetching to finish.
-   * @return
-   */
-  async waitForProofFetch() {
-    if (this.proofOrPromise instanceof Promise) {
-      await this.proofOrPromise;
-    }
-  }
-
-  /**
-   * Sign the given message using Keyless.
-   * @param message in HexInput format
-   * @returns Signature
-   */
-  sign(data: HexInput): KeylessSignature {
-    const { expiryDateSecs } = this.ephemeralKeyPair;
-    if (this.isExpired()) {
-      throw new Error("EphemeralKeyPair is expired");
-    }
-    if (this.proof === undefined) {
-      throw new Error("Proof not defined");
-    }
-    const ephemeralPublicKey = this.ephemeralKeyPair.getPublicKey();
-    const ephemeralSignature = this.ephemeralKeyPair.sign(data);
-
-    return new KeylessSignature({
-      jwtHeader: base64UrlDecode(this.jwt.split(".")[0]),
-      ephemeralCertificate: new EphemeralCertificate(this.proof, EphemeralCertificateVariant.ZkProof),
-      expiryDateSecs,
-      ephemeralPublicKey,
-      ephemeralSignature,
-    });
-  }
-
-  /**
-   * Sign the given transaction with Keyless.
-   * Signs the transaction and proof to guard against proof malleability.
-   * @param transaction the transaction to be signed
-   * @returns KeylessSignature
-   */
-  signTransaction(transaction: AnyRawTransaction): KeylessSignature {
-    if (this.proof === undefined) {
-      throw new Error("Proof not found");
-    }
-    const raw = deriveTransactionType(transaction);
-    const txnAndProof = new TransactionAndProof(raw, this.proof.proof);
-    const signMess = txnAndProof.hash();
-    return this.sign(signMess);
-  }
-
-  /**
-   * Note - This function is currently incomplete and should only be used to verify ownership of the KeylessAccount
-   *
-   * Verifies a signature given the message.
-   *
-   * TODO: Groth16 proof verification
-   *
-   * @param args.message the message that was signed.
-   * @param args.signature the KeylessSignature to verify
-   * @returns boolean
-   */
-  verifySignature(args: { message: HexInput; signature: KeylessSignature }): boolean {
-    const { message, signature } = args;
-    if (this.isExpired()) {
-      return false;
-    }
-    if (!this.ephemeralKeyPair.getPublicKey().verifySignature({ message, signature: signature.ephemeralSignature })) {
-      return false;
-    }
-    return true;
-  }
-
   static fromBytes(bytes: Uint8Array): KeylessAccount {
     return KeylessAccount.deserialize(new Deserializer(bytes));
   }
@@ -306,81 +79,24 @@ export class KeylessAccount extends Serializable implements Account {
     const { address, proof, jwt, ephemeralKeyPair, pepper, uidKey = "sub", proofFetchCallback } = args;
 
     const jwtPayload = jwtDecode<JwtPayload & { [key: string]: string }>(jwt);
-    const iss = jwtPayload.iss!;
+    if (typeof jwtPayload.iss !== "string") {
+      throw new Error("iss was not found");
+    }
     if (typeof jwtPayload.aud !== "string") {
       throw new Error("aud was not found or an array of values");
     }
-    const aud = jwtPayload.aud!;
     const uidVal = jwtPayload[uidKey];
     return new KeylessAccount({
       address,
       proof,
       ephemeralKeyPair,
-      iss,
+      iss: jwtPayload.iss,
       uidKey,
       uidVal,
-      aud,
+      aud: jwtPayload.aud,
       pepper,
       jwt,
       proofFetchCallback,
     });
   }
 }
-
-/**
- * A container class to hold a transaction and a proof.  It implements CryptoHashable which is used to create
- * the signing message for Keyless transactions.  We sign over the proof to ensure non-malleability.
- */
-class TransactionAndProof extends Serializable {
-  /**
-   * The transaction to sign.
-   */
-  transaction: AnyRawTransactionInstance;
-
-  /**
-   * The zero knowledge proof used in signing the transaction.
-   */
-  proof?: ZkProof;
-
-  /**
-   * The domain separator prefix used when hashing.
-   */
-  readonly domainSeparator = "APTOS::TransactionAndProof";
-
-  constructor(transaction: AnyRawTransactionInstance, proof?: ZkProof) {
-    super();
-    this.transaction = transaction;
-    this.proof = proof;
-  }
-
-  serialize(serializer: Serializer): void {
-    serializer.serializeFixedBytes(this.transaction.bcsToBytes());
-    serializer.serializeOption(this.proof);
-  }
-
-  /**
-   * Hashes the bcs serialized from of the class. This is the typescript corollary to the BCSCryptoHash macro in aptos-core.
-   *
-   * @returns Uint8Array
-   */
-  hash(): Uint8Array {
-    return generateSigningMessage(this.bcsToBytes(), this.domainSeparator);
-  }
-}
-
-export type ProofFetchSuccess = {
-  status: "Success";
-};
-
-export type ProofFetchFailure = {
-  status: "Failed";
-  error: string;
-};
-
-export type ProofFetchStatus = ProofFetchSuccess | ProofFetchFailure;
-
-export type ProofFetchCallback = (status: ProofFetchStatus) => Promise<void>;
-
-export interface ProofFetchEvents {
-  proofFetchFinish: (status: ProofFetchStatus) => void;
-}

package/src/account/MultiKeyAccount.ts

@@ -7,7 +7,7 @@ import { AccountAddress, AccountAddressInput } from "../core/accountAddress";
 import { HexInput, SigningScheme } from "../types";
 import { AccountAuthenticatorMultiKey } from "../transactions/authenticator/account";
 import { AnyRawTransaction } from "../transactions/types";
-import { KeylessAccount } from "./KeylessAccount";
+import { AbstractKeylessAccount } from "./AbstractKeylessAccount";
 
 export interface VerifyMultiKeySignatureArgs {
   message: HexInput;
@@ -130,7 +130,9 @@ export class MultiKeyAccount implements Account {
    * @return
    */
   async waitForProofFetch() {
-    const keylessSigners = this.signers.filter((signer) => signer instanceof KeylessAccount) as KeylessAccount[];
+    const keylessSigners = this.signers.filter(
+      (signer) => signer instanceof AbstractKeylessAccount,
+    ) as AbstractKeylessAccount[];
     const promises = keylessSigners.map(async (signer) => signer.waitForProofFetch());
     await Promise.all(promises);
   }

package/src/account/index.ts

@@ -3,4 +3,6 @@ export * from "./Account";
 export * from "./SingleKeyAccount";
 export * from "./EphemeralKeyPair";
 export * from "./KeylessAccount";
+export * from "./AbstractKeylessAccount";
+export * from "./FederatedKeylessAccount";
 export * from "./MultiKeyAccount";

package/src/api/account.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { Account as AccountModule } from "../account";
-import { AccountAddress, PrivateKey, AccountAddressInput } from "../core";
+import { AccountAddress, PrivateKey, AccountAddressInput, createObjectAddress } from "../core";
 import {
   AccountData,
   AnyNumber,
@@ -24,7 +24,6 @@ import {
 } from "../types";
 import {
   deriveAccountFromPrivateKey,
-  getAccountCoinAmount,
   getAccountCoinsCount,
   getAccountCoinsData,
   getAccountCollectionsWithOwnedTokens,
@@ -47,6 +46,7 @@ import { waitForIndexerOnVersion } from "./utils";
 import { CurrentFungibleAssetBalancesBoolExp } from "../types/generated/types";
 import { view } from "../internal/view";
 import { isEncodedStruct, parseEncodedStruct } from "../utils";
+import { memoizeAsync } from "../utils/memoize";
 
 /**
  * A class to query all `Account` related queries on Aptos.
@@ -454,35 +454,81 @@ export class Account {
     faMetadataAddress?: AccountAddressInput;
     minimumLedgerVersion?: AnyNumber;
   }): Promise<number> {
-    const { coinType, faMetadataAddress } = args;
-    await waitForIndexerOnVersion({
-      config: this.config,
-      minimumLedgerVersion: args.minimumLedgerVersion,
-      processorType: ProcessorType.FUNGIBLE_ASSET_PROCESSOR,
-    });
+    const { accountAddress, coinType, faMetadataAddress } = args;
 
     // Attempt to populate the CoinType field if the FA address is provided.
     // We cannot do this internally due to dependency cycles issue.
     let coinAssetType: MoveStructId | undefined = coinType;
     if (coinType === undefined && faMetadataAddress !== undefined) {
-      try {
-        const pairedCoinTypeStruct = (
-          await view({
-            aptosConfig: this.config,
-            payload: { function: "0x1::coin::paired_coin", functionArguments: [faMetadataAddress] },
-          })
-        ).at(0) as { vec: MoveValue[] };
+      coinAssetType = await memoizeAsync(
+        async () => {
+          try {
+            const pairedCoinTypeStruct = (
+              await view({
+                aptosConfig: this.config,
+                payload: { function: "0x1::coin::paired_coin", functionArguments: [faMetadataAddress] },
+              })
+            ).at(0) as { vec: MoveValue[] };
+
+            // Check if the Option has a value, and if so, parse the struct
+            if (pairedCoinTypeStruct.vec.length > 0 && isEncodedStruct(pairedCoinTypeStruct.vec[0])) {
+              return parseEncodedStruct(pairedCoinTypeStruct.vec[0]) as MoveStructId;
+            }
+          } catch (error) {
+            /* No paired coin type found */
+          }
+          return undefined;
+        },
+        `coin-mapping-${faMetadataAddress.toString()}`,
+        1000 * 60 * 5, // 5 minutes
+      )();
+    }
+
+    let faAddress: string;
 
-        // Check if the Option has a value, and if so, parse the struct
-        if (pairedCoinTypeStruct.vec.length > 0 && isEncodedStruct(pairedCoinTypeStruct.vec[0])) {
-          coinAssetType = parseEncodedStruct(pairedCoinTypeStruct.vec[0]);
-        }
-      } catch (error) {
-        /* No paired coin type found */
+    if (coinType !== undefined && faMetadataAddress !== undefined) {
+      faAddress = AccountAddress.from(faMetadataAddress).toStringLong();
+    } else if (coinType !== undefined && faMetadataAddress === undefined) {
+      // TODO Move to a separate function as defined in the AIP for coin migration
+      if (coinType === APTOS_COIN) {
+        faAddress = AccountAddress.A.toStringLong();
+      } else {
+        faAddress = createObjectAddress(AccountAddress.A, coinType).toStringLong();
+      }
+    } else if (coinType === undefined && faMetadataAddress !== undefined) {
+      const addr = AccountAddress.from(faMetadataAddress);
+      faAddress = addr.toStringLong();
+      if (addr === AccountAddress.A) {
+        coinAssetType = APTOS_COIN;
       }
+      // The paired CoinType should be populated outside of this function in another
+      // async call. We cannot do this internally due to dependency cycles issue.
+    } else {
+      throw new Error("Either coinType, faMetadataAddress, or both must be provided");
     }
 
-    return getAccountCoinAmount({ aptosConfig: this.config, ...args, coinType: coinAssetType });
+    // When there is a coin mapping, use that first, otherwise use the fungible asset address
+    // TODO: This function's signature at the top, returns number, but it could be greater than can be represented
+    if (coinAssetType !== undefined) {
+      const [balanceStr] = await view<[string]>({
+        aptosConfig: this.config,
+        payload: {
+          function: "0x1::coin::balance",
+          typeArguments: [coinAssetType],
+          functionArguments: [accountAddress],
+        },
+      });
+      return parseInt(balanceStr, 10);
+    }
+    const [balanceStr] = await view<[string]>({
+      aptosConfig: this.config,
+      payload: {
+        function: "0x1::primary_fungible_store::balance",
+        typeArguments: ["0x1::object::ObjectCore"],
+        functionArguments: [accountAddress, faAddress],
+      },
+    });
+    return parseInt(balanceStr, 10);
   }
 
   /**

package/src/api/keyless.ts

@@ -1,9 +1,16 @@
 // Copyright © Aptos Foundation
 // SPDX-License-Identifier: Apache-2.0
 
-import { EphemeralKeyPair, KeylessAccount, ProofFetchCallback } from "../account";
-import { ZeroKnowledgeSig } from "../core";
-import { deriveKeylessAccount, getPepper, getProof } from "../internal/keyless";
+import { Account, EphemeralKeyPair, KeylessAccount, ProofFetchCallback } from "../account";
+import { FederatedKeylessAccount } from "../account/FederatedKeylessAccount";
+import { AccountAddressInput, ZeroKnowledgeSig } from "../core";
+import {
+  deriveKeylessAccount,
+  getPepper,
+  getProof,
+  updateFederatedKeylessJwkSetTransaction,
+} from "../internal/keyless";
+import { SimpleTransaction } from "../transactions";
 import { HexInput } from "../types";
 import { AptosConfig } from "./aptosConfig";
 
@@ -52,12 +59,30 @@ export class Keyless {
     return getProof({ aptosConfig: this.config, ...args });
   }
 
+  async deriveKeylessAccount(args: {
+    jwt: string;
+    ephemeralKeyPair: EphemeralKeyPair;
+    uidKey?: string;
+    pepper?: HexInput;
+    proofFetchCallback?: ProofFetchCallback;
+  }): Promise<KeylessAccount>;
+
+  async deriveKeylessAccount(args: {
+    jwt: string;
+    ephemeralKeyPair: EphemeralKeyPair;
+    jwkAddress: AccountAddressInput;
+    uidKey?: string;
+    pepper?: HexInput;
+    proofFetchCallback?: ProofFetchCallback;
+  }): Promise<FederatedKeylessAccount>;
+
   /**
    * Derives the Keyless Account from the JWT token and corresponding EphemeralKeyPair.  It will lookup the pepper from
    * the pepper service if not explicitly provided.  It will compute the proof via the proving service.  It will ch
    *
    * @param args.jwt JWT token
    * @param args.ephemeralKeyPair the EphemeralKeyPair used to generate the nonce in the JWT token
+   * @param args.jwkAddress the where the JWKs used to verify signatures are found.  Setting the value derives a FederatedKeylessAccount
    * @param args.uidKey a key in the JWT token to use to set the uidVal in the IdCommitment
    * @param args.pepper the pepper
    * @param args.proofFetchCallback a callback function that if set, the fetch of the proof will be done in the background. Once
@@ -69,10 +94,31 @@ export class Keyless {
   async deriveKeylessAccount(args: {
     jwt: string;
     ephemeralKeyPair: EphemeralKeyPair;
+    jwkAddress?: AccountAddressInput;
     uidKey?: string;
     pepper?: HexInput;
     proofFetchCallback?: ProofFetchCallback;
-  }): Promise<KeylessAccount> {
+  }): Promise<KeylessAccount | FederatedKeylessAccount> {
     return deriveKeylessAccount({ aptosConfig: this.config, ...args });
   }
+
+  /**
+   * This installs a set of FederatedJWKs at an address for a given iss.
+   *
+   * It will fetch the JWK set from the well-known endpoint and update the FederatedJWKs at the sender's address
+   * to reflect it.
+   *
+   * @param args.sender The account that will install the JWKs
+   * @param args.iss the iss claim of the federated OIDC provider.
+   * @param args.jwksUrl the URL to find the corresponding JWKs. For supported IDP providers this parameter in not necessary.
+   *
+   * @returns The pending transaction that results from submission.
+   */
+  async updateFederatedKeylessJwkSetTransaction(args: {
+    sender: Account;
+    iss: string;
+    jwksUrl?: string;
+  }): Promise<SimpleTransaction> {
+    return updateFederatedKeylessJwkSetTransaction({ aptosConfig: this.config, ...args });
+  }
 }