From 8f99e719df08c4c5b2ad976d0f743116dc28e7c9 Mon Sep 17 00:00:00 2001 From: SepehrGanji Date: Mon, 23 Oct 2023 11:14:00 -0600 Subject: [PATCH 1/3] add crypto docs --- packages/crypto/src/coders/hex.ts | 16 ++++++++++++++++ packages/crypto/src/coders/utf8.ts | 9 +++++++++ packages/crypto/src/hashes.ts | 12 ++++++++++++ 3 files changed, 37 insertions(+) diff --git a/packages/crypto/src/coders/hex.ts b/packages/crypto/src/coders/hex.ts index c7ac0953..aeb1a49e 100644 --- a/packages/crypto/src/coders/hex.ts +++ b/packages/crypto/src/coders/hex.ts @@ -12,6 +12,10 @@ const enum HexCharCode { F_LO = 102 // f } +/** + * Convert a Uint8Array to a hex string + * @param bytes + */ function bytesToHex(bytes: Uint8Array): string { assertInstanceOf(bytes, Uint8Array); @@ -23,6 +27,10 @@ function bytesToHex(bytes: Uint8Array): string { return hex; } +/** + * Convert a hex string to a Uint8Array + * @param hex + */ function hexToBytes(hex: string): Uint8Array { assertTypeOf(hex, "string"); assert(hex.length % 2 === 0, "Invalid hex padding."); @@ -37,6 +45,14 @@ function hexToBytes(hex: string): Uint8Array { return bytes; } +/** + * Convert a hex character code to a base 16 number + * @param char + * + * @example + * charCodeToBase16(48) // 0 + * charCodeToBase16(57) // 9 + */ function charCodeToBase16(char: number) { if (char >= HexCharCode.ZERO && char <= HexCharCode.NINE) { return char - HexCharCode.ZERO; diff --git a/packages/crypto/src/coders/utf8.ts b/packages/crypto/src/coders/utf8.ts index 02bbcb58..bb084a65 100644 --- a/packages/crypto/src/coders/utf8.ts +++ b/packages/crypto/src/coders/utf8.ts @@ -1,12 +1,21 @@ import { assertInstanceOf, assertTypeOf } from "@fleet-sdk/common"; import { BytesCoder } from "../types"; +/** + * Converts bytes to utf8 string + * @param bytes + */ function bytesToUtf8(bytes: Uint8Array): string { assertInstanceOf(bytes, Uint8Array); return new TextDecoder().decode(bytes); } +/** + * Converts utf8 string to bytes + * @param str + * @returns + */ function utf8ToBytes(str: string): Uint8Array { assertTypeOf(str, "string"); diff --git a/packages/crypto/src/hashes.ts b/packages/crypto/src/hashes.ts index 32725ec7..34a85c07 100644 --- a/packages/crypto/src/hashes.ts +++ b/packages/crypto/src/hashes.ts @@ -3,16 +3,28 @@ import { sha256 as _sha256 } from "@noble/hashes/sha256"; import { hex } from "./coders"; import { BytesInput } from "./types"; +/** + * Ensure that the input is a Uint8Array, if not convert it to one + * @param input + */ function ensureBytes(input: BytesInput): Uint8Array { if (input instanceof Uint8Array) return input; return hex.decode(input); } +/** + * Get the blake2b-256 hash of the input + * @param message + */ export function blake2b256(message: BytesInput): Uint8Array { return blake2b(ensureBytes(message), { dkLen: 32 }); } +/** + * Get the sha256 hash of the input + * @param message + */ export function sha256(message: BytesInput): Uint8Array { return _sha256(ensureBytes(message)); } From 3f59b0acf84afcc6eafeaa48eb89264b633c7eae Mon Sep 17 00:00:00 2001 From: SepehrGanji Date: Sat, 4 Nov 2023 19:08:52 -0600 Subject: [PATCH 2/3] add test docs --- packages/crypto/src/coders/index.spec.ts | 13 +++++++++++++ packages/crypto/src/coders/utf8.spec.ts | 12 ++++++++++++ packages/crypto/src/hashes.spec.ts | 12 ++++++++++++ 3 files changed, 37 insertions(+) diff --git a/packages/crypto/src/coders/index.spec.ts b/packages/crypto/src/coders/index.spec.ts index fce198be..dfc21d7a 100644 --- a/packages/crypto/src/coders/index.spec.ts +++ b/packages/crypto/src/coders/index.spec.ts @@ -2,6 +2,11 @@ import { describe, expect, test } from "vitest"; import { base58, base58check, base64, utf8 } from "."; describe("Coders smoke tests", () => { + + /** + * @description For testing base64 coder + * @expected it should encode and decode correctly + */ test("base64 coder roundtrip", () => { const decodedBase64 = utf8.decode("this is a base64 encoded string"); const encodedBase64 = "dGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIHN0cmluZw=="; @@ -10,6 +15,10 @@ describe("Coders smoke tests", () => { expect(base64.decode(encodedBase64)).to.be.deep.equal(decodedBase64); }); + /** + * @description For testing base58 coder + * @expected it should encode and decode correctly + */ test("base58 coder roundtrip", () => { const decodedBase58 = utf8.decode("this is a base58 encoded string"); const encodedBase58 = "2mxCXDZDHgWsZCCCUBhmanjEeEFPM5dg8FVb659iiJa"; @@ -18,6 +27,10 @@ describe("Coders smoke tests", () => { expect(base58.decode(encodedBase58)).to.be.deep.equal(decodedBase58); }); + /** + * @description For testing base58check coder + * @expected it should encode and decode correctly + */ test("base58check coder roundtrip", () => { const decodedBase58check = utf8.decode("this is a base58check encoded string"); const encodedBase58check = "6nURSRrD1s933Ruwq4Gi9XzULMhuRQbX1mYrnY2jknX9pW67uKbADDk"; diff --git a/packages/crypto/src/coders/utf8.spec.ts b/packages/crypto/src/coders/utf8.spec.ts index b76c9bb1..8c29e377 100644 --- a/packages/crypto/src/coders/utf8.spec.ts +++ b/packages/crypto/src/coders/utf8.spec.ts @@ -2,12 +2,20 @@ import { describe, expect, it, test } from "vitest"; import { utf8 } from "./utf8"; describe("UTF-8 <> bytes serialization", () => { + /** + * @description For testing UTF-8 coder + * @expected it should encode and decode correctly + */ it("Should roundtrip", () => { expect(utf8.encode(utf8.decode("this is a regular string"))).to.be.equal( "this is a regular string" ); }); + /** + * @description For testing UTF-8 coder + * @expected it should encode and decode correctly + */ test("utf8 to bytes with invalid inputs", () => { const notAString = true as unknown as string; expect(() => utf8.decode(notAString)).to.throw( @@ -15,6 +23,10 @@ describe("UTF-8 <> bytes serialization", () => { ); }); + /** + * @description For testing UTF-8 coder + * @expected it should encode and decode correctly + */ test("bytes to utf8 with invalid inputs", () => { const invalidBytes = {} as unknown as Uint8Array; expect(() => utf8.encode(invalidBytes)).to.throw( diff --git a/packages/crypto/src/hashes.spec.ts b/packages/crypto/src/hashes.spec.ts index e5f5f005..cc0eced8 100644 --- a/packages/crypto/src/hashes.spec.ts +++ b/packages/crypto/src/hashes.spec.ts @@ -3,12 +3,20 @@ import { hex, utf8 } from "./coders"; import { blake2b256, sha256 } from "./hashes"; describe("Hashes smoke tests", () => { + /** + * @description For testing BLAKE2b256 Hash + * @expected it should hash to a correct value + */ it("Should hash message using BLAKE2b256", () => { expect(blake2b256(utf8.decode("blake2b256"))).to.be.deep.equal( hex.decode("eb95e6932cedac15db722fcdb0cfd21437f94690339a716251fad2f89842ea8b") ); }); + /** + * @description For testing SHA256 Hash, regardless of input format + * @expected it should hash to a correct value + */ it("Should have the same result regardless input format", () => { const byte = Uint8Array.from([0xde, 0xad, 0xbe, 0xef]); const hex = "deadbeef"; @@ -17,6 +25,10 @@ describe("Hashes smoke tests", () => { expect(sha256(byte)).to.be.deep.equal(sha256(hex)); }); + /** + * @description For testing SHA256 Hash + * @expected it should hash to a correct value + */ it("Should hash message using sha256", () => { expect(sha256(utf8.decode("sha256"))).to.be.deep.equal( hex.decode("5d5b09f6dcb2d53a5fffc60c4ac0d55fabdf556069d6631545f42aa6e3500f2e") From 453051d99dfe3462f5d02c1083ac0adb788cc999 Mon Sep 17 00:00:00 2001 From: SepehrGanji Date: Sat, 4 Nov 2023 19:43:46 -0600 Subject: [PATCH 3/3] fix lint --- packages/crypto/src/coders/index.spec.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/crypto/src/coders/index.spec.ts b/packages/crypto/src/coders/index.spec.ts index dfc21d7a..9729483b 100644 --- a/packages/crypto/src/coders/index.spec.ts +++ b/packages/crypto/src/coders/index.spec.ts @@ -2,7 +2,6 @@ import { describe, expect, test } from "vitest"; import { base58, base58check, base64, utf8 } from "."; describe("Coders smoke tests", () => { - /** * @description For testing base64 coder * @expected it should encode and decode correctly