@silvana-one/mina-utils 0.2.0

package/src/utils/fee.ts

@@ -0,0 +1,11 @@
+import { UInt64 } from "o1js";
+import config from "../config.js";
+
+/**
+ * Calculate the fee for a transaction
+ * @returns the fee for a transaction
+ */
+export async function fee(): Promise<UInt64> {
+  //TODO: update after mainnet launch and resolution of the issue https://github.com/o1-labs/o1js/issues/1626
+  return UInt64.fromJSON(config.MINAFEE);
+}

package/src/utils/fetch.ts

@@ -0,0 +1,130 @@
+import {
+  PublicKey,
+  Field,
+  Mina,
+  fetchAccount,
+  checkZkappTransaction,
+} from "o1js";
+import { sleep } from "./utils.js";
+
+/**
+ * Fetches the Mina account for a given public key with error handling
+ * @param params the parameters for fetching the account
+ * @param params.publicKey the public key of the account
+ * @param params.tokenId the token id of the account
+ * @param params.force whether to force the fetch - use it only if you are sure the account exists
+ * @returns the account object
+ */
+export async function fetchMinaAccount(params: {
+  publicKey: string | PublicKey;
+  tokenId?: string | Field | undefined;
+  force?: boolean;
+}) {
+  const { publicKey, tokenId, force = false } = params;
+  const timeout = 1000 * 60 * 3; // 3 minutes
+  let attempt = 0;
+  const startTime = Date.now();
+  let result = { account: undefined };
+  while (Date.now() - startTime < timeout) {
+    try {
+      const result = await fetchAccount(
+        {
+          publicKey,
+          tokenId,
+        },
+        undefined,
+        { timeout: 5 * 1000 }
+      );
+      return result;
+    } catch (error: any) {
+      if (force === true)
+        console.log("Error in fetchMinaAccount:", {
+          error,
+          publicKey:
+            typeof publicKey === "string" ? publicKey : publicKey.toBase58(),
+          tokenId: tokenId?.toString(),
+          force,
+        });
+      else {
+        console.log("fetchMinaAccount error", {
+          error,
+          publicKey:
+            typeof publicKey === "string" ? publicKey : publicKey.toBase58(),
+          tokenId: tokenId?.toString(),
+          force,
+        });
+        return result;
+      }
+    }
+    attempt++;
+    await sleep(1000 * 6 * attempt); // to handle rate limit we increase the interval
+  }
+  if (force === true)
+    throw new Error(
+      `fetchMinaAccount timeout
+      ${{
+        publicKey:
+          typeof publicKey === "string" ? publicKey : publicKey.toBase58(),
+        tokenId: tokenId?.toString(),
+        force,
+      }}`
+    );
+  else
+    console.log(
+      "fetchMinaAccount timeout",
+      typeof publicKey === "string" ? publicKey : publicKey.toBase58(),
+      tokenId?.toString(),
+      force
+    );
+  return result;
+}
+
+/**
+ * Fetches the Mina actions for a given public key with error handling
+ * @param publicKey the public key of the contract
+ * @param fromActionState the starting action state
+ * @param endActionState the ending action state
+ * @returns the actions array
+ */
+
+export async function fetchMinaActions(
+  publicKey: PublicKey,
+  fromActionState: Field,
+  endActionState?: Field
+) {
+  const timeout = 1000 * 60 * 600; // 10 hours
+  const startTime = Date.now();
+  while (Date.now() - startTime < timeout) {
+    try {
+      let actions = await Mina.fetchActions(publicKey, {
+        fromActionState,
+        endActionState,
+      });
+      if (Array.isArray(actions)) return actions;
+      else console.log("Cannot fetch actions - wrong format");
+    } catch (error: any) {
+      console.log(
+        "Error in fetchMinaActions",
+        error.toString().substring(0, 300)
+      );
+    }
+    await sleep(1000 * 60 * 2);
+  }
+  console.log("Timeout in fetchMinaActions");
+  return undefined;
+}
+
+/**
+ * Fetches the Mina transaction for a given hash with error handling
+ * @param hash the hash of the transaction
+ * @returns the transaction object
+ */
+export async function checkMinaZkappTransaction(hash: string) {
+  try {
+    const result = await checkZkappTransaction(hash);
+    return result;
+  } catch (error) {
+    console.error("Error in checkZkappTransaction:", error);
+    return { success: false };
+  }
+}

package/src/utils/fields.ts

@@ -0,0 +1,39 @@
+import { Field, Poseidon } from "o1js";
+import { fieldToBase64, fieldFromBase64 } from "./base64-field.js";
+
+/**
+ * Serialize fields to a string using base64 URL-friendly encoding
+ * @param fields the fields array to serialize
+ * @returns the serialized string
+ */
+export function serializeFields(fields: Field[]): string {
+  const hash = Poseidon.hash(fields);
+  const value = [Field(fields.length), hash, ...fields];
+  //return value.map((f) => f.toBigInt().toString(36)).join(".");
+  return value.map((f) => fieldToBase64(f)).join(".");
+}
+
+/**
+ * Deserialize fields from a string using base64 URL-friendly encoding
+ * @param s the string to deserialize
+ * @returns the deserialized fields array
+ */
+export function deserializeFields(s: string): Field[] {
+  try {
+    //const value = s.split(".").map((n) => Field(BigInt(convert(n, 36))));
+    const value = s.split(".").map((n) => fieldFromBase64(n));
+    const length = value[0];
+    if (
+      Field(value.length - 2)
+        .equals(length)
+        .toBoolean() === false
+    )
+      throw new Error("deserializeFields: invalid length");
+    const hash = Poseidon.hash(value.slice(2));
+    if (hash.equals(value[1]).toBoolean()) {
+      return value.slice(2);
+    } else throw new Error("deserializeFields: invalid hash: data mismatch");
+  } catch (e: any) {
+    throw new Error(`deserializeFields: invalid string: ${s}: ${e}`);
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,8 @@
+export * from "./base64-field.js";
+export * from "./base64.js";
+export * from "./fetch.js";
+export * from "./fields.js";
+export * from "./fee.js";
+export * from "./mina.js";
+export * from "./indexed-map.js";
+export * from "./utils.js";

package/src/utils/indexed-map.ts

@@ -0,0 +1,170 @@
+import { Experimental, Field } from "o1js";
+import { bigintToBase64, bigintFromBase64 } from "./base64.js";
+import { sleep } from "./utils.js";
+import { pinJSON } from "../storage/pinata.js";
+
+const { IndexedMerkleMap } = Experimental;
+type IndexedMerkleMap = Experimental.IndexedMerkleMap;
+
+export interface IndexedMapSerialized {
+  height: number;
+  root: string;
+  length: string;
+  nodes: string;
+  sortedLeaves: string;
+}
+
+export async function loadIndexedMerkleMap(params: {
+  url: string;
+  type: ReturnType<typeof IndexedMerkleMap>;
+  timeout?: number;
+  attempts?: number;
+}) {
+  const { url, type, timeout = 60000, attempts = 5 } = params;
+  let attempt = 0;
+  const start = Date.now();
+  let response = await fetch(url);
+  while (!response.ok && attempt < attempts && Date.now() - start < timeout) {
+    attempt++;
+    await sleep(5000 * attempt); // handle rate limiting
+    response = await fetch(url);
+  }
+  if (!response.ok) {
+    throw new Error("Failed to fetch IndexedMerkleMap");
+  }
+
+  const json = await response.json();
+  const serializedIndexedMap = (
+    json as unknown as { map: IndexedMapSerialized }
+  ).map;
+  if (!serializedIndexedMap)
+    throw new Error("wrong IndexedMerkleMap json format");
+  const map = deserializeIndexedMerkleMapInternal({
+    serializedIndexedMap,
+    type,
+  });
+  if (!map) {
+    throw new Error("Failed to deserialize whitelist");
+  }
+  return map;
+}
+
+export async function saveIndexedMerkleMap(params: {
+  map: IndexedMerkleMap;
+  name?: string;
+  keyvalues?: { key: string; value: string }[];
+  auth: string;
+}): Promise<string | undefined> {
+  const { map, name = "indexed-map", keyvalues, auth } = params;
+  const serialized = serializeIndexedMap(map);
+  const ipfsHash = await pinJSON({
+    data: { map: serialized },
+    name,
+    keyvalues,
+    auth,
+  });
+  return ipfsHash;
+}
+
+export function serializeIndexedMap(
+  map: IndexedMerkleMap
+): IndexedMapSerialized {
+  return {
+    height: map.height,
+    root: map.root.toJSON(),
+    length: map.length.toJSON(),
+    nodes: JSON.stringify(map.data.get().nodes, (_, v) =>
+      typeof v === "bigint" ? "n" + bigintToBase64(v) : v
+    ),
+    sortedLeaves: JSON.stringify(
+      map.data
+        .get()
+        .sortedLeaves.map((v) => [
+          bigintToBase64(v.key),
+          bigintToBase64(v.nextKey),
+          bigintToBase64(v.value),
+          bigintToBase64(BigInt(v.index)),
+        ])
+    ),
+  };
+}
+
+export function deserializeIndexedMerkleMap(params: {
+  serializedIndexedMap: IndexedMapSerialized;
+  type?: ReturnType<typeof IndexedMerkleMap>;
+}): InstanceType<ReturnType<typeof IndexedMerkleMap>> | undefined {
+  try {
+    const { serializedIndexedMap, type } = params;
+    return deserializeIndexedMerkleMapInternal({
+      serializedIndexedMap,
+      type: type ?? IndexedMerkleMap(serializedIndexedMap.height),
+    });
+  } catch (error: any) {
+    console.error("Error deserializing map:", error?.message ?? error);
+    return undefined;
+  }
+}
+
+export function parseIndexedMapSerialized(
+  serializedMap: string
+): IndexedMapSerialized {
+  const json = JSON.parse(serializedMap);
+  if (
+    json.height === undefined ||
+    json.root === undefined ||
+    json.length === undefined ||
+    json.nodes === undefined ||
+    json.sortedLeaves === undefined
+  )
+    throw new Error("wrong IndexedMerkleMap json format");
+  if (typeof json.height !== "number")
+    throw new Error("wrong IndexedMerkleMap height format");
+  if (typeof json.root !== "string")
+    throw new Error("wrong IndexedMerkleMap root format");
+  if (typeof json.length !== "string")
+    throw new Error("wrong IndexedMerkleMap length format");
+  if (typeof json.nodes !== "string")
+    throw new Error("wrong IndexedMerkleMap nodes format");
+  if (typeof json.sortedLeaves !== "string")
+    throw new Error("wrong IndexedMerkleMap sortedLeaves format");
+  return json;
+}
+
+function deserializeIndexedMerkleMapInternal(params: {
+  serializedIndexedMap: IndexedMapSerialized;
+  type: ReturnType<typeof IndexedMerkleMap>;
+}): InstanceType<ReturnType<typeof IndexedMerkleMap>> {
+  const { serializedIndexedMap, type } = params;
+  const map = new type();
+  if (serializedIndexedMap.height !== map.height) {
+    throw new Error("wrong IndexedMap height");
+  }
+  const nodes = JSON.parse(serializedIndexedMap.nodes, (_, v) => {
+    // Check if the value is a string that represents a BigInt
+    if (typeof v === "string" && v[0] === "n") {
+      // Remove the first 'n' and convert the string to a BigInt
+      return bigintFromBase64(v.slice(1));
+    }
+    return v;
+  });
+  const sortedLeaves = JSON.parse(serializedIndexedMap.sortedLeaves).map(
+    (row: any) => {
+      return {
+        key: bigintFromBase64(row[0]),
+        nextKey: bigintFromBase64(row[1]),
+        value: bigintFromBase64(row[2]),
+        index: Number(bigintFromBase64(row[3])),
+      };
+    }
+  );
+
+  map.root = Field.fromJSON(serializedIndexedMap.root);
+  map.length = Field.fromJSON(serializedIndexedMap.length);
+  map.data.updateAsProver(() => {
+    return {
+      nodes: nodes.map((row: any) => [...row]),
+      sortedLeaves: [...sortedLeaves],
+    };
+  });
+  return map;
+}

package/src/utils/mina.ts

@@ -0,0 +1,171 @@
+export {
+  initBlockchain,
+  accountBalance,
+  accountBalanceMina,
+  MinaNetworkInstance,
+  currentNetwork,
+  getNetworkIdHash,
+  getCurrentNetwork,
+  getDeployer,
+};
+
+import {
+  Mina,
+  PublicKey,
+  PrivateKey,
+  UInt64,
+  fetchAccount,
+  Field,
+  Lightnet,
+  CircuitString,
+} from "o1js";
+import { networks, blockchain, MinaNetwork, Local } from "../networks.js";
+
+/**
+ * MinaNetworkInstance is the data structure for a Mina network instance, keeping track of the keys, network, and network ID hash.
+ */
+interface MinaNetworkInstance {
+  /** The keys for the deployers */
+  keys: Mina.TestPublicKey[];
+
+  /** The network */
+  network: MinaNetwork;
+
+  /** The network ID hash */
+  networkIdHash: Field;
+}
+
+let currentNetwork: MinaNetworkInstance | undefined = undefined;
+
+function getNetworkIdHash(): Field {
+  if (currentNetwork === undefined) {
+    throw new Error("Network is not initialized");
+  }
+  return currentNetwork.networkIdHash;
+}
+
+function getCurrentNetwork(): MinaNetworkInstance {
+  if (currentNetwork === undefined) {
+    throw new Error("Network is not initialized");
+  }
+  return currentNetwork;
+}
+
+function getDeployer(): Mina.TestPublicKey | undefined {
+  if (currentNetwork === undefined) {
+    throw new Error("Network is not initialized");
+  }
+  if (currentNetwork.keys.length < 1) return undefined;
+  return currentNetwork.keys[0];
+}
+
+/**
+ * Initializes the Mina blockchain network
+ * Due to the limitations of the Mina SDK, only one network can be initialized at a time
+ * This function should be called before any other Mina functions
+ * @param instance the blockchain instance to initialize
+ * @param deployersNumber the number of deployers to use for the network (only for local and lightnet networks)
+ * @returns the Mina network instance
+ */
+async function initBlockchain(
+  instance: blockchain,
+  deployersNumber: number = 0,
+  proofsEnabled: boolean = true
+): Promise<MinaNetworkInstance> {
+  /*
+  if (instance === "mainnet") {
+    throw new Error("Mainnet is not supported yet by zkApps");
+  }
+  */
+  if (currentNetwork !== undefined) {
+    if (currentNetwork?.network.chainId === instance) {
+      return currentNetwork;
+    } else {
+      throw new Error(
+        `Network is already initialized to different chain ${currentNetwork.network.chainId}, cannot initialize to ${instance}`
+      );
+    }
+  }
+  const networkIdHash = CircuitString.fromString(instance).hash();
+
+  // await used for compatibility with future versions of o1js
+  if (instance === "local") {
+    const local = await Mina.LocalBlockchain({
+      proofsEnabled,
+    });
+    Mina.setActiveInstance(local);
+    if (deployersNumber > local.testAccounts.length)
+      throw new Error("Not enough test accounts");
+    currentNetwork = {
+      keys: local.testAccounts,
+      network: Local,
+      networkIdHash,
+    };
+    return currentNetwork;
+  }
+
+  const network = networks.find((n) => n.chainId === instance);
+  if (network === undefined) {
+    throw new Error("Unknown network");
+  }
+
+  const networkInstance = Mina.Network({
+    mina: network.mina,
+    archive: network.archive,
+    lightnetAccountManager: network.accountManager,
+    networkId: instance === "mainnet" ? "mainnet" : "testnet",
+  });
+  Mina.setActiveInstance(networkInstance);
+
+  const keys: Mina.TestPublicKey[] = [];
+
+  if (deployersNumber > 0) {
+    if (instance === "lightnet") {
+      for (let i = 0; i < deployersNumber; i++) {
+        const keyPair = await Lightnet.acquireKeyPair();
+        const key = Mina.TestPublicKey(keyPair.privateKey);
+        keys.push(key);
+      }
+    } else {
+      const deployers = process.env.DEPLOYERS;
+      if (
+        deployers === undefined ||
+        Array.isArray(deployers) === false ||
+        deployers.length < deployersNumber
+      )
+        throw new Error("Deployers are not set");
+      for (let i = 0; i < deployersNumber; i++) {
+        const privateKey = PrivateKey.fromBase58(deployers[i]);
+        const key = Mina.TestPublicKey(privateKey);
+        keys.push(key);
+      }
+    }
+  }
+
+  currentNetwork = {
+    keys,
+    network,
+    networkIdHash,
+  };
+  return currentNetwork;
+}
+
+/**
+ * Fetches the account balance for a given public key
+ * @param address the public key
+ * @returns the account balance
+ */
+async function accountBalance(address: PublicKey): Promise<UInt64> {
+  await fetchAccount({ publicKey: address });
+  if (Mina.hasAccount(address)) return Mina.getBalance(address);
+  else return UInt64.from(0);
+}
+
+/**
+ * Fetches the account balance for a given public key and returns it in Mina
+ * @param address the public key
+ * @returns the account balance in MINA
+ */
+async function accountBalanceMina(address: PublicKey): Promise<number> {
+  return Number((await accountBalance(address)).toBigInt()) / 1e9;
+}

package/src/utils/utils.ts

@@ -0,0 +1,79 @@
+export function sleep(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function makeString(length: number): string {
+  // eslint-disable-next-line @typescript-eslint/no-inferrable-types
+  let outString: string = ``;
+  // eslint-disable-next-line @typescript-eslint/no-inferrable-types
+  const inOptions: string = `ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789`;
+
+  for (let i = 0; i < length; i++) {
+    outString += inOptions.charAt(Math.floor(Math.random() * inOptions.length));
+  }
+
+  return outString;
+}
+
+export function formatTime(ms: number): string {
+  if (ms === undefined) return "";
+  if (ms < 1000) return ms.toString() + " ms";
+  if (ms < 60 * 1000)
+    return parseInt((ms / 1000).toString()).toString() + " sec";
+  if (ms < 60 * 60 * 1000) {
+    const minutes = parseInt((ms / 1000 / 60).toString());
+    const seconds = parseInt(((ms - minutes * 60 * 1000) / 1000).toString());
+    return minutes.toString() + " min " + seconds.toString() + " sec";
+  } else {
+    const hours = parseInt((ms / 1000 / 60 / 60).toString());
+    const minutes = parseInt(
+      ((ms - hours * 60 * 60 * 1000) / 1000 / 60).toString()
+    );
+    return hours.toString() + " h " + minutes.toString() + " min";
+  }
+}
+
+export class Memory {
+  // eslint-disable-next-line @typescript-eslint/no-inferrable-types
+  static rss: number = 0;
+  constructor() {
+    Memory.rss = 0;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-inferrable-types
+  public static info(description: string = ``, fullInfo: boolean = false) {
+    const memoryData = process.memoryUsage();
+    const formatMemoryUsage = (data: number) =>
+      `${Math.round(data / 1024 / 1024)} MB`;
+    const oldRSS = Memory.rss;
+    Memory.rss = Math.round(memoryData.rss / 1024 / 1024);
+
+    const memoryUsage = fullInfo
+      ? {
+          step: `${description}:`,
+          rssDelta: `${(oldRSS === 0
+            ? 0
+            : Memory.rss - oldRSS
+          ).toString()} MB -> Resident Set Size memory change`,
+          rss: `${formatMemoryUsage(
+            memoryData.rss
+          )} -> Resident Set Size - total memory allocated`,
+          heapTotal: `${formatMemoryUsage(
+            memoryData.heapTotal
+          )} -> total size of the allocated heap`,
+          heapUsed: `${formatMemoryUsage(
+            memoryData.heapUsed
+          )} -> actual memory used during the execution`,
+          external: `${formatMemoryUsage(
+            memoryData.external
+          )} -> V8 external memory`,
+        }
+      : `RSS memory ${description}: ${formatMemoryUsage(memoryData.rss)}${
+          oldRSS === 0
+            ? ``
+            : `, changed by ` + (Memory.rss - oldRSS).toString() + ` MB`
+        }`;
+
+    console.log(memoryUsage);
+  }
+}