Merge branch 'main' into refactor/destruct-candid-type

packages/ic-management/src/index.ts

@@ -2,3 +2,4 @@ export { ICManagementCanister } from "./ic-management.canister";
 export * from "./types/canister.options";
 export * from "./types/ic-management.params";
 export * from "./types/ic-management.responses";
+export * from "./utils/ic-management.utils";

packages/ic-management/src/utils/ic-management.utils.spec.ts

@@ -0,0 +1,32 @@
+import { mockCanisterId } from "../ic-management.mock";
+import { decodeSnapshotId, encodeSnapshotId } from "./ic-management.utils";
+
+describe("ic-management.utils", () => {
+  const mockLocalSubnetId = [0, 0, 0, 0, 0, 0, 0, 1];
+
+  const mockSnapshotId = Uint8Array.from([
+    ...mockCanisterId.toUint8Array(),
+    ...mockLocalSubnetId,
+  ]);
+
+  const snapshotIdHex = "000000000000000201010000000000000001";
+
+  it("should correctly encode a snapshot ID with encodeSnapshotId", () => {
+    const encoded = encodeSnapshotId(mockSnapshotId);
+
+    expect(encoded).toBe(snapshotIdHex);
+  });
+
+  it("should correctly decode a snapshot ID with decodeSnapshotId", () => {
+    const decoded = decodeSnapshotId(snapshotIdHex);
+
+    expect(decoded).toEqual(mockSnapshotId);
+  });
+
+  it("should encodeSnapshotId and decodeSnapshotId", () => {
+    const encoded = encodeSnapshotId(mockSnapshotId);
+    const decoded = decodeSnapshotId(encoded);
+
+    expect(decoded).toEqual(mockSnapshotId);
+  });
+});

packages/ic-management/src/utils/ic-management.utils.ts

@@ -0,0 +1,28 @@
+import { hexStringToUint8Array, uint8ArrayToHexString } from "@dfinity/utils";
+import type { snapshot_id } from "../../candid/ic-management";
+
+/**
+ * Encodes a snapshot ID into a hex string representation.
+ *
+ * A snapshot ID is a tuple `(CanisterId, u64)`, where:
+ * - `CanisterId` is a unique identifier for a canister.
+ * - `u64` is a subnet-local number (incremented for each new snapshot).
+ *
+ * @param {snapshot_id} snapshotId - The snapshot ID to encode, represented as a `Uint8Array` or an array of numbers.
+ * @returns {string} The hex string representation of the snapshot ID.
+ */
+export const encodeSnapshotId = (snapshotId: snapshot_id): string =>
+  uint8ArrayToHexString(snapshotId);
+
+/**
+ * Decodes a hex string representation of a snapshot ID back into its original format.
+ *
+ * A snapshot ID is a tuple `(CanisterId, u64)`, where:
+ * - `CanisterId` is a unique identifier for a canister.
+ * - `u64` is a subnet-local number (incremented for each new snapshot).
+ *
+ * @param {string} snapshotId - The hex string representation of the snapshot ID.
+ * @returns {snapshot_id} The decoded snapshot ID as a `Uint8Array`.
+ */
+export const decodeSnapshotId = (snapshotId: string): snapshot_id =>
+  hexStringToUint8Array(snapshotId);