@aptos-labs/ts-sdk 1.16.0 → 1.17.0-zeta.1

package/src/account/MultiKeyAccount.ts

@@ -7,6 +7,7 @@ import { AccountAddress } from "../core/accountAddress";
 import { HexInput, SigningScheme } from "../types";
 import { AccountAuthenticatorMultiKey } from "../transactions/authenticator/account";
 import { AnyRawTransaction } from "../transactions/types";
+import { KeylessAccount } from "./KeylessAccount";
 
 export interface VerifyMultiKeySignatureArgs {
   message: HexInput;
@@ -123,6 +124,16 @@ export class MultiKeyAccount implements Account {
     return new AccountAuthenticatorMultiKey(this.publicKey, this.signTransaction(transaction));
   }
 
+  /**
+   * Waits for any proofs on any KeylessAccount signers to be fetched. If the proof is fetched a syncronously, call this
+   * to ensure signing with the KeylessAccount does not fail as the proof must be ready.
+   * @return
+   */
+  async waitForProofFetch() {
+    const keylessSigners = this.signers.filter((signer) => signer instanceof KeylessAccount) as KeylessAccount[];
+    await Promise.all(keylessSigners.filter((signer) => signer.proof instanceof Promise).map((signer) => signer.proof));
+  }
+
   /**
    * Sign the given message using the MultiKeyAccount's signers
    * @param message in HexInput format

package/src/account/index.ts

@@ -1,4 +1,6 @@
 export * from "./Ed25519Account";
 export * from "./Account";
 export * from "./SingleKeyAccount";
+export * from "./EphemeralKeyPair";
+export * from "./KeylessAccount";
 export * from "./MultiKeyAccount";

package/src/api/aptos.ts

@@ -13,6 +13,7 @@ import { ANS } from "./ans";
 import { Staking } from "./staking";
 import { Transaction } from "./transaction";
 import { Table } from "./table";
+import { Keyless } from "./keyless";
 
 /**
  * This class is the main entry point into Aptos's
@@ -50,6 +51,8 @@ export class Aptos {
 
   readonly table: Table;
 
+  readonly keyless: Keyless;
+
   constructor(settings?: AptosConfig) {
     this.config = new AptosConfig(settings);
     this.account = new Account(this.config);
@@ -63,6 +66,7 @@ export class Aptos {
     this.staking = new Staking(this.config);
     this.transaction = new Transaction(this.config);
     this.table = new Table(this.config);
+    this.keyless = new Keyless(this.config);
   }
 }
 
@@ -77,6 +81,7 @@ export interface Aptos
     Faucet,
     FungibleAsset,
     General,
+    Keyless,
     Staking,
     Table,
     Omit<Transaction, "build" | "simulate" | "submit" | "batch"> {}
@@ -113,3 +118,4 @@ applyMixin(Aptos, General, "general");
 applyMixin(Aptos, Staking, "staking");
 applyMixin(Aptos, Transaction, "transaction");
 applyMixin(Aptos, Table, "table");
+applyMixin(Aptos, Keyless, "keyless");

package/src/api/aptosConfig.ts

@@ -3,7 +3,14 @@
 
 import aptosClient from "@aptos-labs/aptos-client";
 import { AptosSettings, ClientConfig, Client, FullNodeConfig, IndexerConfig, FaucetConfig } from "../types";
-import { NetworkToNodeAPI, NetworkToFaucetAPI, NetworkToIndexerAPI, Network } from "../utils/apiEndpoints";
+import {
+  NetworkToNodeAPI,
+  NetworkToFaucetAPI,
+  NetworkToIndexerAPI,
+  Network,
+  NetworkToPepperAPI,
+  NetworkToProverAPI,
+} from "../utils/apiEndpoints";
 import { AptosApiType } from "../utils/const";
 
 /**
@@ -34,6 +41,16 @@ export class AptosConfig {
    */
   readonly faucet?: string;
 
+  /**
+   * The optional hardcoded pepper service URL to send requests to instead of using the network
+   */
+  readonly pepper?: string;
+
+  /**
+   * The optional hardcoded prover service URL to send requests to instead of using the network
+   */
+  readonly prover?: string;
+
   /**
    * The optional hardcoded indexer URL to send requests to instead of using the network
    */
@@ -63,6 +80,8 @@ export class AptosConfig {
     this.network = settings?.network ?? Network.DEVNET;
     this.fullnode = settings?.fullnode;
     this.faucet = settings?.faucet;
+    this.pepper = settings?.pepper;
+    this.prover = settings?.prover;
     this.indexer = settings?.indexer;
     this.client = settings?.client ?? { provider: aptosClient };
     this.clientConfig = settings?.clientConfig ?? {};
@@ -95,8 +114,34 @@ export class AptosConfig {
         if (this.indexer !== undefined) return this.indexer;
         if (this.network === Network.CUSTOM) throw new Error("Please provide a custom indexer url");
         return NetworkToIndexerAPI[this.network];
+      case AptosApiType.PEPPER:
+        if (this.pepper !== undefined) return this.pepper;
+        if (this.network === Network.CUSTOM) throw new Error("Please provide a custom pepper service url");
+        return NetworkToPepperAPI[this.network];
+      case AptosApiType.PROVER:
+        if (this.prover !== undefined) return this.prover;
+        if (this.network === Network.CUSTOM) throw new Error("Please provide a custom prover service url");
+        return NetworkToProverAPI[this.network];
       default:
         throw Error(`apiType ${apiType} is not supported`);
     }
   }
+
+  /**
+   * Checks if the URL is a known pepper service endpoint
+   *
+   * @internal
+   * */
+  isPepperServiceRequest(url: string): boolean {
+    return NetworkToPepperAPI[this.network] === url;
+  }
+
+  /**
+   * Checks if the URL is a known prover service endpoint
+   *
+   * @internal
+   * */
+  isProverServiceRequest(url: string): boolean {
+    return NetworkToProverAPI[this.network] === url;
+  }
 }

package/src/api/general.ts

@@ -3,14 +3,13 @@
 
 import { AptosConfig } from "./aptosConfig";
 import {
-  getBlockByHeight,
-  getBlockByVersion,
   getChainTopUserTransactions,
   getIndexerLastSuccessVersion,
   getLedgerInfo,
   getProcessorStatus,
   queryIndexer,
 } from "../internal/general";
+import { getBlockByHeight, getBlockByVersion } from "../internal/transaction";
 import { view } from "../internal/view";
 import {
   AnyNumber,

package/src/api/keyless.ts

@@ -0,0 +1,51 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+
+import { EphemeralKeyPair, KeylessAccount, ProofFetchCallback } from "../account";
+import { deriveKeylessAccount, getPepper } from "../internal/keyless";
+import { HexInput } from "../types";
+import { AptosConfig } from "./aptosConfig";
+
+/**
+ * A class to query all `Keyless` related queries on Aptos.
+ *
+ * More documentation on how to integrate Keyless Accounts see the below
+ * https://aptos.dev/guides/keyless-accounts/#aptos-keyless-integration-guide
+ */
+export class Keyless {
+  constructor(readonly config: AptosConfig) {}
+
+  /**
+   * Fetches the pepper from the Aptos pepper service API.
+   *
+   * @param args.jwt JWT token
+   * @param args.ephemeralKeyPair the EphemeralKeyPair used to generate the nonce in the JWT token
+   * @returns The pepper which is a Uint8Array of length 31.
+   */
+  async getPepper(args: { jwt: string; ephemeralKeyPair: EphemeralKeyPair }): Promise<Uint8Array> {
+    return getPepper({ aptosConfig: this.config, ...args });
+  }
+
+  /**
+   * Fetches the pepper from the Aptos pepper service API.
+   *
+   * @param args.jwt JWT token
+   * @param args.ephemeralKeyPair the EphemeralKeyPair used to generate the nonce in the JWT token
+   * @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
+   * fetching finishes the callback function will be called.  This should be used to provide a more responsive user experience as now
+   * they are not blocked on fetching the proof. Thus the function will return much more quickly.
+   *
+   * @returns A KeylessAccount that can be used to sign transactions
+   */
+  async deriveKeylessAccount(args: {
+    jwt: string;
+    ephemeralKeyPair: EphemeralKeyPair;
+    uidKey?: string;
+    pepper?: HexInput;
+    proofFetchCallback?: ProofFetchCallback;
+  }): Promise<KeylessAccount> {
+    return deriveKeylessAccount({ aptosConfig: this.config, ...args });
+  }
+}

package/src/bcs/deserializer.ts

@@ -56,6 +56,52 @@ export class Deserializer {
     return textDecoder.decode(value);
   }
 
+  /**
+   * Deserializes a an optional string.
+   *
+   * BCS layout for Optional<String>: 0 if none, else 1 | string_length | string_content
+   * @example
+   * ```ts
+   * const deserializer = new Deserializer(new Uint8Array([0x00]));
+   * assert(deserializer.deserializeOptionStr() === undefined);
+   * const deserializer = new Deserializer(new Uint8Array([1, 8, 49, 50, 51, 52, 97, 98, 99, 100]));
+   * assert(deserializer.deserializeOptionStr() === "1234abcd");
+   * ```
+   */
+  deserializeOptionStr(): string | undefined {
+    const exists = this.deserializeUleb128AsU32();
+    if (exists === 1) {
+      return this.deserializeStr();
+    }
+    return undefined;
+  }
+
+  /**
+   * Deserializes a an optional deserializable class.
+   *
+   * BCS layout for Optional<T>: 0 if none, else 1 | bcs representation of class
+   *
+   * @example
+   * const deserializer = new Deserializer(new Uint8Array([1, 2, 3]));
+   * const value = deserializer.deserializeOption(MyClass); // where MyClass has a `deserialize` function
+   * // value is now an instance of MyClass
+   *
+   * const deserializer = new Deserializer(new Uint8Array([0]));
+   * const value = deserializer.deserializeOption(MyClass); // where MyClass has a `deserialize` function
+   * // value is undefined
+   *
+   * @param cls The BCS-deserializable class to deserialize the buffered bytes into.
+   *
+   * @returns the deserialized value of class type T
+   */
+  deserializeOption<T>(cls: Deserializable<T>): T | undefined {
+    const exists = this.deserializeUleb128AsU32();
+    if (exists === 1) {
+      return this.deserialize(cls);
+    }
+    return undefined;
+  }
+
   /**
    * Deserializes an array of bytes.
    *

package/src/bcs/serializer.ts

@@ -316,6 +316,64 @@ export class Serializer {
       item.serialize(this);
     });
   }
+
+  /**
+   * Serializes a BCS Serializable values into a serializer instance or undefined.
+   * Note that this does not return anything. The bytes are added to the serializer instance's byte buffer.
+   *
+   * @param values The array of BCS Serializable values
+   *
+   * @example
+   * ```ts
+   * const serializer = new Serializer();
+   * serializer.serializeOption(new AccountAddress(...));
+   * const serializedBytes = serializer.toUint8Array();
+   * // serializedBytes is now the BCS-serialized byte representation of AccountAddress
+   *
+   * const serializer = new Serializer();
+   * serializer.serializeOption(undefined);
+   * assert(serializer.toUint8Array() === new Uint8Array([0x00]));
+   * ```
+   */
+  serializeOption<T extends Serializable>(value?: T): void {
+    if (value === undefined) {
+      this.serializeU32AsUleb128(0);
+    } else {
+      this.serializeU32AsUleb128(1);
+      value.serialize(this);
+    }
+  }
+
+  /**
+   * Serializes an optional string. UTF8 string is supported.
+   *
+   * The existence of the string is encoded first, 0 if undefined and 1 if it exists.
+   * Them the number of bytes in the string content is serialized, as a uleb128-encoded u32 integer.
+   * Then the string content is serialized as UTF8 encoded bytes.
+   *
+   * BCS layout for optional "string": 1 | string_length | string_content
+   * where string_length is a u32 integer encoded as a uleb128 integer, equal to the number of bytes in string_content.
+   *
+   * BCS layout for undefined: 0
+   * @example
+   * ```ts
+   * const serializer = new Serializer();
+   * serializer.serializeOptionStr("1234abcd");
+   * assert(serializer.toUint8Array() === new Uint8Array([1, 8, 49, 50, 51, 52, 97, 98, 99, 100]));
+   *
+   * const serializer = new Serializer();
+   * serializer.serializeOptionStr(undefined);
+   * assert(serializer.toUint8Array() === new Uint8Array([0]));
+   * ```
+   */
+  serializeOptionStr(value?: string): void {
+    if (value === undefined) {
+      this.serializeU32AsUleb128(0);
+    } else {
+      this.serializeU32AsUleb128(1);
+      this.serializeStr(value);
+    }
+  }
 }
 
 export function ensureBoolean(value: unknown): asserts value is boolean {

package/src/client/core.ts

@@ -100,6 +100,10 @@ export async function aptosRequest<Req extends {}, Res extends {}>(
       );
     }
     result.data = indexerResponse.data as Res;
+  } else if (apiType === AptosApiType.PEPPER || apiType === AptosApiType.PROVER) {
+    if (result.status >= 400) {
+      throw new AptosApiError(options, result, `${response.data}`);
+    }
   }
 
   if (result.status >= 200 && result.status < 300) {

package/src/client/get.ts

@@ -89,6 +89,18 @@ export async function getAptosFullNode<Req extends {}, Res extends {}>(
   });
 }
 
+/**
+ * Makes a get request to the pepper service
+ *
+ * @param options GetAptosRequestOptions
+ * @returns AptosResponse
+ */
+export async function getAptosPepperService<Req extends {}, Res extends {}>(
+  options: GetAptosRequestOptions,
+): Promise<AptosResponse<Req, Res>> {
+  return get<Req, Res>({ ...options, type: AptosApiType.PEPPER });
+}
+
 /// This function is a helper for paginating using a function wrapping an API
 export async function paginateWithCursor<Req extends Record<string, any>, Res extends Array<{}>>(
   options: GetAptosRequestOptions,

package/src/client/post.ts

@@ -135,3 +135,21 @@ export async function postAptosFaucet<Req extends {}, Res extends {}>(
     },
   });
 }
+
+/**
+ * Makes a post request to the pepper service
+ *
+ * @param options GetAptosRequestOptions
+ * @returns AptosResponse
+ */
+export async function postAptosPepperService<Req extends {}, Res extends {}>(
+  options: PostAptosRequestOptions,
+): Promise<AptosResponse<Req, Res>> {
+  return post<Req, Res>({ ...options, type: AptosApiType.PEPPER });
+}
+
+export async function postAptosProvingService<Req extends {}, Res extends {}>(
+  options: PostAptosRequestOptions,
+): Promise<AptosResponse<Req, Res>> {
+  return post<Req, Res>({ ...options, type: AptosApiType.PROVER });
+}

package/src/core/crypto/cryptoHashable.ts

@@ -0,0 +1,16 @@
+import { generateSigningMessage } from "../../transactions/transactionBuilder/signingMessage";
+import { Serializable } from "../../bcs/serializer";
+
+export type AptsoDomainSeparator = `APTOS::${string}`;
+export abstract class CryptoHashable extends Serializable {
+  abstract readonly domainSeparator: AptsoDomainSeparator;
+
+  /**
+   * 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);
+  }
+}

package/src/core/crypto/ephemeral.ts

@@ -0,0 +1,138 @@
+import { Serializer, Deserializer } from "../../bcs";
+import { EphemeralPublicKeyVariant, EphemeralSignatureVariant, HexInput } from "../../types";
+import { PublicKey } from "./publicKey";
+import { Signature } from "./signature";
+import { Ed25519PublicKey, Ed25519Signature } from "./ed25519";
+import { Hex } from "../hex";
+
+/**
+ * Represents ephemeral public keys for Aptos Keyless accounts.
+ *
+ * These are not public keys used as a public key on an account.  They are only used ephemerally on Keyless accounts.
+ */
+export class EphemeralPublicKey extends PublicKey {
+  /**
+   * The public key itself
+   */
+  public readonly publicKey: PublicKey;
+
+  /**
+   * An enum indicating the scheme of the ephemeral public key
+   */
+  public readonly variant: EphemeralPublicKeyVariant;
+
+  constructor(publicKey: PublicKey) {
+    super();
+    const publicKeyType = publicKey.constructor.name;
+    switch (publicKeyType) {
+      case Ed25519PublicKey.name:
+        this.publicKey = publicKey;
+        this.variant = EphemeralPublicKeyVariant.Ed25519;
+        break;
+      default:
+        throw new Error(`Unsupported key for EphemeralPublicKey - ${publicKeyType}`);
+    }
+  }
+
+  /**
+   * Get the public key in bytes (Uint8Array).
+   *
+   * @returns Uint8Array representation of the public key
+   */
+  toUint8Array(): Uint8Array {
+    return this.bcsToBytes();
+  }
+
+  /**
+   * Verifies a signed data with a the ephemeral public key
+   *
+   * @param args.message message
+   * @param args.signature The signature that was signed by the private key of the ephemeral public key
+   * @returns true if the signature is valid
+   */
+  verifySignature(args: { message: HexInput; signature: EphemeralSignature }): boolean {
+    const { message, signature } = args;
+    return this.publicKey.verifySignature({ message, signature });
+  }
+
+  serialize(serializer: Serializer): void {
+    if (this.publicKey instanceof Ed25519PublicKey) {
+      serializer.serializeU32AsUleb128(EphemeralPublicKeyVariant.Ed25519);
+      this.publicKey.serialize(serializer);
+    } else {
+      throw new Error("Unknown public key type");
+    }
+  }
+
+  static deserialize(deserializer: Deserializer): EphemeralPublicKey {
+    const index = deserializer.deserializeUleb128AsU32();
+    switch (index) {
+      case EphemeralPublicKeyVariant.Ed25519:
+        return new EphemeralPublicKey(Ed25519PublicKey.deserialize(deserializer));
+      default:
+        throw new Error(`Unknown variant index for EphemeralPublicKey: ${index}`);
+    }
+  }
+
+  static isPublicKey(publicKey: PublicKey): publicKey is EphemeralPublicKey {
+    return publicKey instanceof EphemeralPublicKey;
+  }
+}
+
+/**
+ * Represents ephemeral signatures used in Aptos Keyless accounts.
+ *
+ * These signatures are used inside of KeylessSignature
+ */
+export class EphemeralSignature extends Signature {
+  /**
+   * The signature signed by the private key of an EphemeralKeyPair
+   */
+  public readonly signature: Signature;
+
+  constructor(signature: Signature) {
+    super();
+    const signatureType = signature.constructor.name;
+    switch (signatureType) {
+      case Ed25519Signature.name:
+        this.signature = signature;
+        break;
+      default:
+        throw new Error(`Unsupported signature for EphemeralSignature - ${signatureType}`);
+    }
+  }
+
+  /**
+   * Get the public key in bytes (Uint8Array).
+   *
+   * @returns Uint8Array representation of the public key
+   */
+  toUint8Array(): Uint8Array {
+    return this.bcsToBytes();
+  }
+
+  static fromHex(hexInput: HexInput): EphemeralSignature {
+    const data = Hex.fromHexInput(hexInput);
+    const deserializer = new Deserializer(data.toUint8Array());
+    return EphemeralSignature.deserialize(deserializer);
+  }
+
+  serialize(serializer: Serializer): void {
+    if (this.signature instanceof Ed25519Signature) {
+      serializer.serializeU32AsUleb128(EphemeralSignatureVariant.Ed25519);
+      this.signature.serialize(serializer);
+    } else {
+      throw new Error("Unknown signature type");
+    }
+  }
+
+  static deserialize(deserializer: Deserializer): EphemeralSignature {
+    const index = deserializer.deserializeUleb128AsU32();
+    switch (index) {
+      case EphemeralSignatureVariant.Ed25519:
+        return new EphemeralSignature(Ed25519Signature.deserialize(deserializer));
+      default:
+        throw new Error(`Unknown variant index for EphemeralSignature: ${index}`);
+    }
+  }
+}

package/src/core/crypto/index.ts

@@ -5,6 +5,8 @@ export * from "./ed25519";
 export * from "./hdKey";
 export * from "./multiEd25519";
 export * from "./multiKey";
+export * from "./ephemeral";
+export * from "./keyless";
 export * from "./privateKey";
 export * from "./publicKey";
 export * from "./secp256k1";