@aptos-labs/ts-sdk 6.3.1 → 7.0.0

package/dist/core/crypto/multiEd25519.js

@@ -0,0 +1,361 @@
+// Copyright © Aptos Foundation
+// SPDX-License-Identifier: Apache-2.0
+import { SigningScheme as AuthenticationKeyScheme } from "../../types/index.js";
+import { AuthenticationKey } from "../authenticationKey.js";
+import { Ed25519PublicKey, Ed25519Signature } from "./ed25519.js";
+import { AbstractMultiKey } from "./multiKey.js";
+import { Signature } from "./signature.js";
+/**
+ * Represents the public key of a K-of-N Ed25519 multi-sig transaction.
+ *
+ * A K-of-N multi-sig transaction requires at least K out of N authorized signers to sign the transaction
+ * for it to be executed. This class encapsulates the logic for managing the public keys and the threshold
+ * for valid signatures.
+ *
+ * @see {@link https://aptos.dev/integration/creating-a-signed-transaction/ | Creating a Signed Transaction}
+ * @group Implementation
+ * @category Serialization
+ */
+export class MultiEd25519PublicKey extends AbstractMultiKey {
+    /**
+     * Maximum number of public keys supported
+     * @group Implementation
+     * @category Serialization
+     */
+    static MAX_KEYS = 32;
+    /**
+     * Minimum number of public keys needed
+     * @group Implementation
+     * @category Serialization
+     */
+    static MIN_KEYS = 2;
+    /**
+     * Minimum threshold for the number of valid signatures required
+     * @group Implementation
+     * @category Serialization
+     */
+    static MIN_THRESHOLD = 1;
+    /**
+     * List of Ed25519 public keys for this LegacyMultiEd25519PublicKey
+     * @group Implementation
+     * @category Serialization
+     */
+    publicKeys;
+    /**
+     * The minimum number of valid signatures required, for the number of public keys specified
+     * @group Implementation
+     * @category Serialization
+     */
+    threshold;
+    /**
+     * Public key for a K-of-N multi-sig transaction. A K-of-N multi-sig transaction means that for such a
+     * transaction to be executed, at least K out of the N authorized signers have signed the transaction
+     * and passed the check conducted by the chain.
+     *
+     * @see {@link
+     * https://aptos.dev/integration/creating-a-signed-transaction/ | Creating a Signed Transaction}
+     * @param args - A wrapper to let you choose the param order.
+     * @param args.publicKeys A list of public keys
+     * @param args.threshold At least "threshold" signatures must be valid
+     * @group Implementation
+     * @category Serialization
+     */
+    constructor(args) {
+        const { publicKeys, threshold } = args;
+        super({ publicKeys });
+        // Validate number of public keys
+        if (publicKeys.length > MultiEd25519PublicKey.MAX_KEYS || publicKeys.length < MultiEd25519PublicKey.MIN_KEYS) {
+            throw new Error(`Must have between ${MultiEd25519PublicKey.MIN_KEYS} and ` +
+                `${MultiEd25519PublicKey.MAX_KEYS} public keys, inclusive`);
+        }
+        // Validate threshold: must be between 1 and the number of public keys, inclusive
+        if (threshold < MultiEd25519PublicKey.MIN_THRESHOLD || threshold > publicKeys.length) {
+            throw new Error(`Threshold must be between ${MultiEd25519PublicKey.MIN_THRESHOLD} and ${publicKeys.length}, inclusive`);
+        }
+        this.publicKeys = publicKeys;
+        this.threshold = threshold;
+    }
+    getSignaturesRequired() {
+        return this.threshold;
+    }
+    // region AccountPublicKey
+    /**
+     * Verifies a multi-signature against a given message.
+     * This function ensures that the provided signatures meet the required threshold and are valid for the given message.
+     *
+     * @param args - The arguments for verifying the signature.
+     * @param args.message - The message that was signed.
+     * @param args.signature - The multi-signature containing multiple signatures and a bitmap indicating which signatures are valid.
+     * @returns True if the signature is valid; otherwise, false.
+     * @throws Error if the bitmap and signatures length mismatch or if there are not enough valid signatures.
+     * @group Implementation
+     * @category Serialization
+     */
+    verifySignature(args) {
+        const { message, signature } = args;
+        if (!(signature instanceof MultiEd25519Signature)) {
+            return false;
+        }
+        const indices = [];
+        for (let i = 0; i < 4; i += 1) {
+            for (let j = 0; j < 8; j += 1) {
+                const bitIsSet = (signature.bitmap[i] & (1 << (7 - j))) !== 0;
+                if (bitIsSet) {
+                    const index = i * 8 + j;
+                    indices.push(index);
+                }
+            }
+        }
+        if (indices.length !== signature.signatures.length) {
+            throw new Error("Bitmap and signatures length mismatch");
+        }
+        if (indices.length < this.threshold) {
+            throw new Error("Not enough signatures");
+        }
+        for (let i = 0; i < indices.length; i += 1) {
+            const publicKey = this.publicKeys[indices[i]];
+            if (!publicKey.verifySignature({ message, signature: signature.signatures[i] })) {
+                return false;
+            }
+        }
+        return true;
+    }
+    async verifySignatureAsync(args) {
+        return this.verifySignature(args);
+    }
+    /**
+     * Generates an authentication key based on the current instance's byte representation.
+     * This function is essential for creating a secure authentication key that can be used for various cryptographic operations.
+     *
+     * @returns {AuthenticationKey} The generated authentication key.
+     * @group Implementation
+     * @category Serialization
+     */
+    authKey() {
+        return AuthenticationKey.fromSchemeAndBytes({
+            scheme: AuthenticationKeyScheme.MultiEd25519,
+            input: this.toUint8Array(),
+        });
+    }
+    /**
+     * Converts a PublicKeys into Uint8Array (bytes) with: bytes = p1_bytes | ... | pn_bytes | threshold
+     * @group Implementation
+     * @category Serialization
+     */
+    toUint8Array() {
+        const bytes = new Uint8Array(this.publicKeys.length * Ed25519PublicKey.LENGTH + 1);
+        this.publicKeys.forEach((k, i) => {
+            bytes.set(k.toUint8Array(), i * Ed25519PublicKey.LENGTH);
+        });
+        bytes[this.publicKeys.length * Ed25519PublicKey.LENGTH] = this.threshold;
+        return bytes;
+    }
+    // endregion
+    // region Serializable
+    /**
+     * Serializes the current instance into bytes using the provided serializer.
+     * This allows for the conversion of the instance's data into a format suitable for transmission or storage.
+     *
+     * @param serializer - The serializer used to convert the instance into bytes.
+     * @group Implementation
+     * @category Serialization
+     */
+    serialize(serializer) {
+        serializer.serializeBytes(this.toUint8Array());
+    }
+    /**
+     * Deserializes a MultiEd25519Signature from the provided deserializer.
+     * This function helps in reconstructing a MultiEd25519Signature object from its serialized byte representation.
+     *
+     * @param deserializer - The deserializer instance used to read the serialized data.
+     * @group Implementation
+     * @category Serialization
+     */
+    static deserialize(deserializer) {
+        const bytes = deserializer.deserializeBytes();
+        const threshold = bytes[bytes.length - 1];
+        const keys = [];
+        for (let i = 0; i < bytes.length - 1; i += Ed25519PublicKey.LENGTH) {
+            const begin = i;
+            keys.push(new Ed25519PublicKey(bytes.subarray(begin, begin + Ed25519PublicKey.LENGTH)));
+        }
+        return new MultiEd25519PublicKey({ publicKeys: keys, threshold });
+    }
+    /**
+     * Deserializes a MultiEd25519Signature from the provided deserializer.
+     * This function helps in reconstructing a MultiEd25519Signature object from its serialized byte representation.
+     *
+     * @param deserializer - The deserializer instance used to read the serialized data.
+     * @group Implementation
+     * @category Serialization
+     */
+    static deserializeWithoutLength(deserializer) {
+        const length = deserializer.remaining();
+        const bytes = deserializer.deserializeFixedBytes(length);
+        const threshold = bytes[bytes.length - 1];
+        const keys = [];
+        for (let i = 0; i < bytes.length - 1; i += Ed25519PublicKey.LENGTH) {
+            const begin = i;
+            keys.push(new Ed25519PublicKey(bytes.subarray(begin, begin + Ed25519PublicKey.LENGTH)));
+        }
+        return new MultiEd25519PublicKey({ publicKeys: keys, threshold });
+    }
+    // endregion
+    /**
+     * Get the index of the provided public key.
+     *
+     * This function retrieves the index of a specified public key within the MultiKey.
+     * If the public key does not exist, it throws an error.
+     *
+     * @param publicKey - The public key to find the index for.
+     * @returns The corresponding index of the public key, if it exists.
+     * @throws Error - If the public key is not found in the MultiKey.
+     * @group Implementation
+     */
+    getIndex(publicKey) {
+        return super.getIndex(publicKey);
+    }
+}
+/**
+ * Represents the signature of a K-of-N Ed25519 multi-sig transaction.
+ *
+ * @see {@link https://aptos.dev/integration/creating-a-signed-transaction/#multisignature-transactions | Creating a Signed Transaction}
+ * @group Implementation
+ * @category Serialization
+ */
+export class MultiEd25519Signature extends Signature {
+    /**
+     * Maximum number of Ed25519 signatures supported
+     * @group Implementation
+     * @category Serialization
+     */
+    static MAX_SIGNATURES_SUPPORTED = 32;
+    /**
+     * Number of bytes in the bitmap representing who signed the transaction (32-bits)
+     * @group Implementation
+     * @category Serialization
+     */
+    static BITMAP_LEN = 4;
+    /**
+     * The list of underlying Ed25519 signatures
+     * @group Implementation
+     * @category Serialization
+     */
+    signatures;
+    /**
+     * 32-bit Bitmap representing who signed the transaction
+     *
+     * This is represented where each public key can be masked to determine whether the message was signed by that key.
+     * @group Implementation
+     * @category Serialization
+     */
+    bitmap;
+    /**
+     * Signature for a K-of-N multi-sig transaction.
+     *
+     * @see {@link
+     * https://aptos.dev/integration/creating-a-signed-transaction/#multisignature-transactions | Creating a Signed Transaction}
+     *
+     * @param args.signatures A list of signatures
+     * @param args.bitmap 4 bytes, at most 32 signatures are supported. If Nth bit value is `1`, the Nth
+     * signature should be provided in `signatures`. Bits are read from left to right.
+     * Alternatively, you can specify an array of bitmap positions.
+     * Valid position should range between 0 and 31.
+     * @see MultiEd25519Signature.createBitmap
+     * @group Implementation
+     * @category Serialization
+     */
+    constructor(args) {
+        super();
+        const { signatures, bitmap } = args;
+        if (signatures.length > MultiEd25519Signature.MAX_SIGNATURES_SUPPORTED) {
+            throw new Error(`The number of signatures cannot be greater than ${MultiEd25519Signature.MAX_SIGNATURES_SUPPORTED}`);
+        }
+        this.signatures = signatures;
+        if (!(bitmap instanceof Uint8Array)) {
+            this.bitmap = MultiEd25519Signature.createBitmap({ bits: bitmap });
+        }
+        else if (bitmap.length !== MultiEd25519Signature.BITMAP_LEN) {
+            throw new Error(`"bitmap" length should be ${MultiEd25519Signature.BITMAP_LEN}`);
+        }
+        else {
+            this.bitmap = bitmap;
+        }
+    }
+    // region AccountSignature
+    /**
+     * Converts a MultiSignature into Uint8Array (bytes) with `bytes = s1_bytes | ... | sn_bytes | bitmap`
+     * @group Implementation
+     * @category Serialization
+     */
+    toUint8Array() {
+        const bytes = new Uint8Array(this.signatures.length * Ed25519Signature.LENGTH + MultiEd25519Signature.BITMAP_LEN);
+        this.signatures.forEach((k, i) => {
+            bytes.set(k.toUint8Array(), i * Ed25519Signature.LENGTH);
+        });
+        bytes.set(this.bitmap, this.signatures.length * Ed25519Signature.LENGTH);
+        return bytes;
+    }
+    // endregion
+    // region Serializable
+    serialize(serializer) {
+        serializer.serializeBytes(this.toUint8Array());
+    }
+    static deserialize(deserializer) {
+        const bytes = deserializer.deserializeBytes();
+        const bitmap = bytes.subarray(bytes.length - 4);
+        const signatures = [];
+        for (let i = 0; i < bytes.length - bitmap.length; i += Ed25519Signature.LENGTH) {
+            const begin = i;
+            signatures.push(new Ed25519Signature(bytes.subarray(begin, begin + Ed25519Signature.LENGTH)));
+        }
+        return new MultiEd25519Signature({ signatures, bitmap });
+    }
+    // endregion
+    /**
+     * Helper method to create a bitmap out of the specified bit positions.
+     * This function allows you to set specific bits in a 32-bit long bitmap based on the provided positions.
+     *
+     * @param args The arguments for creating the bitmap.
+     * @param args.bits The bitmap positions that should be set. A position starts at index 0. Valid positions should range between 0 and 31.
+     *
+     * @example
+     * Here's an example of valid `bits`
+     * ```
+     * [0, 2, 31]
+     * ```
+     * `[0, 2, 31]` means the 1st, 3rd and 32nd bits should be set in the bitmap.
+     * The result bitmap should be 0b1010000000000000000000000000001
+     *
+     * @returns bitmap that is 32 bits long.
+     * @group Implementation
+     * @category Serialization
+     */
+    static createBitmap(args) {
+        const { bits } = args;
+        // Bits are read from left to right. e.g. 0b10000000 represents the first bit is set in one byte.
+        // The decimal value of 0b10000000 is 128.
+        const firstBitInByte = 128;
+        const bitmap = new Uint8Array([0, 0, 0, 0]);
+        // Check if duplicates exist in bits
+        const dupCheckSet = new Set();
+        bits.forEach((bit, index) => {
+            if (bit >= MultiEd25519Signature.MAX_SIGNATURES_SUPPORTED) {
+                throw new Error(`Cannot have a signature larger than ${MultiEd25519Signature.MAX_SIGNATURES_SUPPORTED - 1}.`);
+            }
+            if (dupCheckSet.has(bit)) {
+                throw new Error("Duplicate bits detected.");
+            }
+            if (index > 0 && bit <= bits[index - 1]) {
+                throw new Error("The bits need to be sorted in ascending order.");
+            }
+            dupCheckSet.add(bit);
+            const byteOffset = Math.floor(bit / 8);
+            let byte = bitmap[byteOffset];
+            byte |= firstBitInByte >> (bit % 8);
+            bitmap[byteOffset] = byte;
+        });
+        return bitmap;
+    }
+}
+//# sourceMappingURL=multiEd25519.js.map

package/dist/core/crypto/multiEd25519.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multiEd25519.js","sourceRoot":"","sources":["../../../src/core/crypto/multiEd25519.ts"],"names":[],"mappings":"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"}

package/dist/core/crypto/multiKey.d.ts

@@ -0,0 +1,248 @@
+import { HexInput } from "../../types/index.js";
+import { Deserializer } from "../../bcs/deserializer.js";
+import { Serializer } from "../../bcs/serializer.js";
+import { AuthenticationKey } from "../authenticationKey.js";
+import { AccountPublicKey, PublicKey } from "./publicKey.js";
+import { Signature } from "./signature.js";
+import { AnyPublicKey, AnySignature } from "./singleKey.js";
+import { AptosConfig } from "../../api/aptosConfig.js";
+export declare abstract class AbstractMultiKey extends AccountPublicKey {
+    publicKeys: PublicKey[];
+    constructor(args: {
+        publicKeys: PublicKey[];
+    });
+    /**
+     * Create a bitmap that holds the mapping from the original public keys
+     * to the signatures passed in
+     *
+     * @param args.bits array of the index mapping to the matching public keys
+     * @returns Uint8array bit map
+     * @group Implementation
+     * @category Serialization
+     */
+    createBitmap(args: {
+        bits: number[];
+    }): Uint8Array;
+    /**
+     * Get the index of the provided public key.
+     *
+     * This function retrieves the index of a specified public key within the MultiKey.
+     * If the public key does not exist, it throws an error.
+     *
+     * @param publicKey - The public key to find the index for.
+     * @returns The corresponding index of the public key, if it exists.
+     * @throws Error - If the public key is not found in the MultiKey.
+     * @group Implementation
+     * @category Serialization
+     */
+    getIndex(publicKey: PublicKey): number;
+    abstract getSignaturesRequired(): number;
+}
+/**
+ * Represents a multi-key authentication scheme for accounts, allowing multiple public keys
+ * to be associated with a single account. This class enforces a minimum number of valid signatures
+ * required to authorize actions, ensuring enhanced security for multi-agent accounts.
+ *
+ * The public keys of each individual agent can be any type of public key supported by Aptos.
+ * Since [AIP-55](https://github.com/aptos-foundation/AIPs/pull/263), Aptos supports
+ * `Legacy` and `Unified` authentication keys.
+ * @group Implementation
+ * @category Serialization
+ */
+export declare class MultiKey extends AbstractMultiKey {
+    /**
+     * List of any public keys
+     * @group Implementation
+     * @category Serialization
+     */
+    readonly publicKeys: AnyPublicKey[];
+    /**
+     * The minimum number of valid signatures required, for the number of public keys specified
+     * @group Implementation
+     * @category Serialization
+     */
+    readonly signaturesRequired: number;
+    /**
+     * Signature for a K-of-N multi-sig transaction.
+     * This constructor initializes a multi-signature transaction with the provided signatures and bitmap.
+     *
+     * @param args An object containing the parameters for the multi-signature transaction.
+     * @param args.signatures A list of signatures.
+     * @param args.bitmap A bitmap represented as a Uint8Array or an array of numbers, where each bit indicates whether a
+     * corresponding signature is present. A maximum of 32 signatures is supported, and the length of the bitmap must be 4 bytes.
+     *
+     * @throws Error if the number of signatures exceeds the maximum supported, if the bitmap length is incorrect, or if the number
+     * of signatures does not match the bitmap.
+     * @group Implementation
+     * @category Serialization
+     */
+    constructor(args: {
+        publicKeys: Array<PublicKey>;
+        signaturesRequired: number;
+    });
+    getSignaturesRequired(): number;
+    /**
+     * Verifies the provided signature against the given message.
+     * This function helps ensure the integrity and authenticity of the message by checking if the signature is valid.
+     *
+     * Note: This function will fail if a keyless signature is used.  Use `verifySignatureAsync` instead.
+     *
+     * @param args - The arguments for verifying the signature.
+     * @param args.message - The message that was signed.
+     * @param args.signature - The signature to verify.
+     * @group Implementation
+     * @category Serialization
+     */
+    verifySignature(args: {
+        message: HexInput;
+        signature: MultiKeySignature;
+    }): boolean;
+    /**
+     * Verifies the provided signature against the given message.
+     * This function helps ensure the integrity and authenticity of the message by checking if the signature is valid.
+     *
+     * @param args - The arguments for verifying the signature.
+     * @param args.aptosConfig - The Aptos configuration to use
+     * @param args.message - The message that was signed.
+     * @param args.signature - The signature to verify.
+     * @group Implementation
+     * @category Serialization
+     */
+    verifySignatureAsync(args: {
+        aptosConfig: AptosConfig;
+        message: HexInput;
+        signature: Signature;
+        options?: {
+            throwErrorWithReason?: boolean;
+        };
+    }): Promise<boolean>;
+    /**
+     * Generates an authentication key based on the current instance's byte representation.
+     * This key can be used for secure authentication processes within the system.
+     *
+     * @returns {AuthenticationKey} The generated authentication key.
+     * @group Implementation
+     * @category Serialization
+     */
+    authKey(): AuthenticationKey;
+    /**
+     * Serializes the object by writing its signatures and bitmap to the provided serializer.
+     * This allows the object to be converted into a format suitable for transmission or storage.
+     *
+     * @param serializer - The serializer instance used to perform the serialization.
+     * @group Implementation
+     * @category Serialization
+     */
+    serialize(serializer: Serializer): void;
+    /**
+     * Deserializes a MultiKeySignature from the provided deserializer.
+     * This function retrieves the signatures and bitmap necessary for creating a MultiKeySignature object.
+     *
+     * @param deserializer - The deserializer instance used to read the serialized data.
+     * @group Implementation
+     * @category Serialization
+     */
+    static deserialize(deserializer: Deserializer): MultiKey;
+    /**
+     * Get the index of the provided public key.
+     *
+     * This function retrieves the index of a specified public key within the MultiKey.
+     * If the public key does not exist, it throws an error.
+     *
+     * @param publicKey - The public key to find the index for.
+     * @returns The corresponding index of the public key, if it exists.
+     * @throws Error - If the public key is not found in the MultiKey.
+     * @group Implementation
+     */
+    getIndex(publicKey: PublicKey): number;
+    static isInstance(value: PublicKey): value is MultiKey;
+}
+/**
+ * Represents a multi-signature transaction using Ed25519 signatures.
+ * This class allows for the creation and management of a K-of-N multi-signature scheme,
+ * where a specified number of signatures are required to authorize a transaction.
+ *
+ * It includes functionality to validate the number of signatures against a bitmap,
+ * which indicates which public keys have signed the transaction.
+ * @group Implementation
+ * @category Serialization
+ */
+export declare class MultiKeySignature extends Signature {
+    /**
+     * Number of bytes in the bitmap representing who signed the transaction (32-bits)
+     * @group Implementation
+     * @category Serialization
+     */
+    static BITMAP_LEN: number;
+    /**
+     * Maximum number of Ed25519 signatures supported
+     * @group Implementation
+     * @category Serialization
+     */
+    static MAX_SIGNATURES_SUPPORTED: number;
+    /**
+     * The list of underlying Ed25519 signatures
+     * @group Implementation
+     * @category Serialization
+     */
+    readonly signatures: AnySignature[];
+    /**
+     * 32-bit Bitmap representing who signed the transaction
+     *
+     * This is represented where each public key can be masked to determine whether the message was signed by that key.
+     * @group Implementation
+     * @category Serialization
+     */
+    readonly bitmap: Uint8Array;
+    /**
+     * Signature for a K-of-N multi-sig transaction.
+     *
+     * @see {@link
+     * https://aptos.dev/integration/creating-a-signed-transaction/#multisignature-transactions | Creating a Signed Transaction}
+     *
+     * @param args.signatures A list of signatures
+     * @param args.bitmap 4 bytes, at most 32 signatures are supported. If Nth bit value is `1`, the Nth
+     * signature should be provided in `signatures`. Bits are read from left to right
+     * @group Implementation
+     * @category Serialization
+     */
+    constructor(args: {
+        signatures: Array<Signature | AnySignature>;
+        bitmap: Uint8Array | number[];
+    });
+    /**
+     * Helper method to create a bitmap out of the specified bit positions
+     * @param args.bits The bitmap positions that should be set. A position starts at index 0.
+     * Valid position should range between 0 and 31.
+     * @example
+     * Here's an example of valid `bits`
+     * ```
+     * [0, 2, 31]
+     * ```
+     * `[0, 2, 31]` means the 1st, 3rd and 32nd bits should be set in the bitmap.
+     * The result bitmap should be 0b1010000000000000000000000000001
+     *
+     * @returns bitmap that is 32bit long
+     * @group Implementation
+     * @category Serialization
+     */
+    static createBitmap(args: {
+        bits: number[];
+    }): Uint8Array;
+    /**
+     * Converts the bitmap to an array of signer indices.
+     *
+     * Example:
+     *
+     * bitmap: [0b10001000, 0b01000000, 0b00000000, 0b00000000]
+     * signerIndices: [0, 4, 9]
+     *
+     * @returns An array of signer indices.
+     * @group Implementation
+     * @category Serialization
+     */
+    bitMapToSignerIndices(): number[];
+    serialize(serializer: Serializer): void;
+    static deserialize(deserializer: Deserializer): MultiKeySignature;
+}
+//# sourceMappingURL=multiKey.d.ts.map

package/dist/core/crypto/multiKey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multiKey.d.ts","sourceRoot":"","sources":["../../../src/core/crypto/multiKey.ts"],"names":[],"mappings":"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"}