From 321100d671d0fac39d1567127b5c051eb768ddcf Mon Sep 17 00:00:00 2001 From: matthewkeil Date: Sat, 20 Apr 2024 23:08:34 +0700 Subject: [PATCH] feat: widen types and add comments for methods to highlight throwing behavior --- src/types.ts | 100 +++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 93 insertions(+), 7 deletions(-) diff --git a/src/types.ts b/src/types.ts index a665a97..d0a499b 100644 --- a/src/types.ts +++ b/src/types.ts @@ -35,17 +35,59 @@ export interface IBls { PublicKey: typeof PublicKey; Signature: typeof Signature; + secretKeyToPublicKey(secretKey: Uint8Array): Uint8Array; sign(secretKey: Uint8Array, message: Uint8Array): Uint8Array; aggregatePublicKeys(publicKeys: PublicKeyArg[]): Uint8Array; aggregateSignatures(signatures: SignatureArg[]): Uint8Array; + /** + * Will synchronously verify a signature. This function catches invalid input and return false for + * bad keys or signatures. Use the `Signature.verify` method if throwing is desired. + */ verify(publicKey: PublicKeyArg, message: Uint8Array, signature: SignatureArg): boolean; + /** + * Will synchronously verify a signature over a message by multiple aggregated keys. This function + * catches invalid input and return false for bad keys or signatures. Use the + * `Signature.verifyAggregate` if throwing is desired. + */ verifyAggregate(publicKeys: PublicKeyArg[], message: Uint8Array, signature: SignatureArg): boolean; + /** + * Will synchronously verify an aggregated signature over a number of messages each signed by a + * different key. This function catches invalid input and return false for bad keys or signatures. + * Use the `Signature.verifyAggregate` if throwing is desired. + * + * Note: the number of keys and messages must match. + */ verifyMultiple(publicKeys: PublicKeyArg[], messages: Uint8Array[], signature: SignatureArg): boolean; + /** + * Will synchronously verify a group of SignatureSets where each contains a signature signed for + * a message by a public key. This function catches invalid input and return false for bad keys or + * signatures. Use the `Signature.verifyMultipleSignatures` if throwing is desired. + */ verifyMultipleSignatures(sets: SignatureSet[]): boolean; - secretKeyToPublicKey(secretKey: Uint8Array): Uint8Array; + /** + * Will asynchronously verify a signature. This function catches invalid input and return false for + * bad keys or signatures. Use the `Signature.asyncVerify` method if throwing is desired. + */ asyncVerify(publicKey: PublicKeyArg, message: Uint8Array, signature: SignatureArg): Promise; + /** + * Will asynchronously verify a signature over a message by multiple aggregated keys. This function + * catches invalid input and return false for bad keys or signatures. Use the + * `Signature.asyncVerifyAggregate` if throwing is desired. + */ asyncVerifyAggregate(publicKeys: PublicKeyArg[], message: Uint8Array, signature: SignatureArg): Promise; + /** + * Will asynchronously verify an aggregated signature over a number of messages each signed by a + * different key. This function catches invalid input and return false for bad keys or signatures. + * Use the `Signature.asyncVerifyAggregate` if throwing is desired. + * + * Note: the number of keys and messages must match. + */ asyncVerifyMultiple(publicKeys: PublicKeyArg[], messages: Uint8Array[], signature: SignatureArg): Promise; + /** + * Will asynchronously verify a group of SignatureSets where each contains a signature signed for + * a message by a public key. This function catches invalid input and return false for bad keys or + * signatures. Use the Signature.asyncVerifyMultipleSignatures if throwing is desired. + */ asyncVerifyMultipleSignatures(sets: SignatureSet[]): Promise; } @@ -67,7 +109,7 @@ export declare class PublicKey { /** @param type Only for impl `blst-native`. Defaults to `CoordType.jacobian` */ static fromBytes(bytes: Uint8Array, type?: CoordType, validate?: boolean): PublicKey; static fromHex(hex: string): PublicKey; - static aggregate(publicKeys: PublicKey[]): PublicKey; + static aggregate(publicKeys: PublicKeyArg[]): PublicKey; /** @param format Defaults to `PointFormat.compressed` */ toBytes(format?: PointFormat): Uint8Array; toHex(format?: PointFormat): string; @@ -81,16 +123,60 @@ export declare class Signature { * @param validate When using `herumi` implementation, signature validation is always on regardless of this flag. */ static fromBytes(bytes: Uint8Array, type?: CoordType, validate?: boolean): Signature; static fromHex(hex: string): Signature; - static aggregate(signatures: Signature[]): Signature; + static aggregate(signatures: SignatureArg[]): Signature; + /** + * Will synchronously verify a group of SignatureSets where each contains a signature signed for + * a message by a public key. This version of the function will potentially throw errors for + * invalid input. Use the free function `verifyMultipleSignatures` if throwing is not desired. + */ static verifyMultipleSignatures(sets: SignatureSet[]): boolean; + /** + * Will asynchronously verify a group of SignatureSets where each contains a signature signed for + * a message by a public key. This version of the function will potentially throw errors for + * invalid input. Use the free function `verifyMultipleSignatures` if throwing is not desired. + */ static asyncVerifyMultipleSignatures(sets: SignatureSet[]): Promise; - verify(publicKey: PublicKey, message: Uint8Array): boolean; - verifyAggregate(publicKeys: PublicKey[], message: Uint8Array): boolean; - verifyMultiple(publicKeys: PublicKey[], messages: Uint8Array[]): boolean; + /** + * Will synchronously verify a signature. This version of the function will potentially throw + * errors for invalid input. Use the free function `verify` if throwing is not desired. + */ + verify(publicKey: PublicKeyArg, message: Uint8Array): boolean; + /** + * Will synchronously verify a signature over a message by multiple aggregated keys. This + * version of the function will potentially throw errors for invalid input. Use the free function + * `verifyAggregate` if throwing is not desired. + */ + verifyAggregate(publicKeys: PublicKeyArg[], message: Uint8Array): boolean; + /** + * Will synchronously verify an aggregated signature over a number of messages each signed by a + * different key. This version of the function will potentially throw errors for invalid input. + * Use the free function `verifyMultiple` if throwing is not desired. + * + * Note: the number of keys and messages must match. + */ + verifyMultiple(publicKeys: PublicKeyArg[], messages: Uint8Array[]): boolean; + /** + * Will asynchronously verify a signature. This version of the function will potentially throw + * errors for invalid input. Use the free function `asyncVerify` if throwing is not desired. + */ asyncVerify(publicKey: PublicKeyArg, message: Uint8Array): Promise; + /** + * Will asynchronously verify a signature over a message by multiple aggregated keys. This + * version of the function will potentially throw errors for invalid input. Use the free function + * `asyncVerifyAggregate` if throwing is not desired. + */ asyncVerifyAggregate(publicKeys: PublicKeyArg[], message: Uint8Array): Promise; + /** + * Will asynchronously verify an aggregated signature over a number of messages each signed by a + * different key. This version of the function will potentially throw errors for invalid input. + * Use the free function `asyncVerifyMultiple` if throwing is not desired. + * + * Note: the number of keys and messages must match. + */ asyncVerifyMultiple(publicKeys: PublicKeyArg[], messages: Uint8Array[]): Promise; - /** @param format Defaults to `PointFormat.compressed` */ + /** + * @default format - `PointFormat.compressed` + */ toBytes(format?: PointFormat): Uint8Array; toHex(format?: PointFormat): string; multiplyBy(bytes: Uint8Array): Signature;