@silvana-one/storage 0.1.0

package/src/storage/pinata.ts

@@ -0,0 +1,56 @@
+export async function pinJSON(params: {
+  data: string | object;
+  name?: string;
+  keyvalues?: object;
+  auth?: string;
+}): Promise<string | undefined> {
+  const {
+    data,
+    name = "data.json",
+    keyvalues = { library: "zkcloudworker" },
+  } = params;
+  const auth =
+    params.auth ??
+    process.env.PINATA_JWT ??
+    process.env.NEXT_PUBLIC_PINATA_JWT ??
+    process.env.REACT_APP_PINATA_JWT;
+  if (!auth)
+    throw new Error(
+      "pinJSON: auth, PINATA_JWT, NEXT_PUBLIC_PINATA_JWT or REACT_APP_PINATA_JWT should be defined"
+    );
+
+  try {
+    const pinataData = {
+      pinataOptions: {
+        cidVersion: 1,
+      },
+      pinataMetadata: {
+        name,
+        keyvalues,
+      },
+      pinataContent: data,
+    };
+
+    const res = await fetch("https://api.pinata.cloud/pinning/pinJSONToIPFS", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: "Bearer " + auth,
+      },
+      body: JSON.stringify(pinataData),
+    });
+
+    if (!res.ok) {
+      throw new Error(`Pinata error: status: ${res.status} ${res.statusText}`);
+    }
+
+    const responseData = await res.json();
+    console.log("saveToIPFS result:", responseData);
+    return (
+      responseData as unknown as { IpfsHash: string | undefined } | undefined
+    )?.IpfsHash;
+  } catch (error: any) {
+    console.error("saveToIPFS error:", error?.message);
+    return undefined;
+  }
+}

package/src/storage/storage.ts

@@ -0,0 +1,65 @@
+import { Field, Bool, Struct, Encoding, Provable } from "o1js";
+
+export type IpfsHash = string;
+/**
+ * Represents the off-chain storage information,
+ * such as an IPFS hash.
+ */
+export class Storage extends Struct({
+  url: Provable.Array(Field, 2),
+}) {
+  constructor(value: { url: [Field, Field] }) {
+    super(value);
+  }
+
+  /**
+   * Asserts that two Storage instances are equal.
+   * @param a The first Storage instance.
+   * @param b The second Storage instance.
+   */
+  static assertEquals(a: Storage, b: Storage) {
+    a.url[0].assertEquals(b.url[0]);
+    a.url[1].assertEquals(b.url[1]);
+  }
+
+  /**
+   * Checks if two Storage instances are equal.
+   * @param a The first Storage instance.
+   * @param b The second Storage instance.
+   * @returns A Bool indicating whether the two instances are equal.
+   */
+  static equals(a: Storage, b: Storage): Bool {
+    return a.url[0].equals(b.url[0]).and(a.url[1].equals(b.url[1]));
+  }
+
+  /**
+   * Creates a Storage instance from a string.
+   * @param url The string representing the storage URL.
+   * @returns A new Storage instance.
+   */
+  static fromString(url: IpfsHash): Storage {
+    if (url === "") return Storage.empty();
+    const fields = Encoding.stringToFields(url);
+    if (fields.length !== 2) throw new Error("Invalid string length");
+    return new Storage({ url: [fields[0], fields[1]] });
+  }
+
+  /**
+   * Converts the Storage instance to a string.
+   * @returns The string representation of the storage URL.
+   */
+  toString(): IpfsHash {
+    if (this.isEmpty().toBoolean()) {
+      return "";
+    }
+    return Encoding.stringFromFields([this.url[0], this.url[1]]);
+  }
+
+  static empty(): Storage {
+    return new Storage({ url: [Field(0), Field(0)] });
+  }
+
+  isEmpty(): Bool {
+    return this.url[0].equals(Field(0)).and(this.url[1].equals(Field(0)));
+  }
+}

package/src/util/index.ts

@@ -0,0 +1 @@
+export * from "./sleep.js";

package/src/util/sleep.ts

@@ -0,0 +1,3 @@
+export function sleep(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/whitelist/index.ts

@@ -0,0 +1,2 @@
+export * from "./whitelist.js";
+export * from "./offchain-map.js";

package/src/whitelist/offchain-map.ts

@@ -0,0 +1,341 @@
+import { Experimental, Struct, Field, Option, Provable, Bool } from "o1js";
+import {
+  serializeIndexedMap,
+  loadIndexedMerkleMap,
+  IndexedMapSerialized,
+  IndexedMapSerializedJson,
+} from "../indexed-map/indexed-map.js";
+import { sleep } from "../util/sleep.js";
+import { Storage, IpfsHash } from "../storage/storage.js";
+import { createIpfsURL } from "../storage/ipfs.js";
+import { pinJSON } from "../storage/pinata.js";
+
+const { IndexedMerkleMap } = Experimental;
+type IndexedMerkleMap = Experimental.IndexedMerkleMap;
+const OFFCHAIN_MAP_HEIGHT = 20;
+
+export interface OffchainMapSerialized extends IndexedMapSerializedJson {
+  [key: string]: {
+    map: IndexedMapSerialized;
+    list: { key: string; value?: string }[];
+    data?: object;
+  };
+}
+
+/** Represents the Offchain Map using an Indexed Merkle Map. */
+export class OffchainMap extends IndexedMerkleMap(OFFCHAIN_MAP_HEIGHT) {}
+export class OffchainMapOption extends Option(OffchainMap) {}
+export class FieldOption extends Option(Field) {}
+export interface OffChainMapEntry {
+  key: Field | bigint | number | string;
+  value?: Field | bigint | number | string; // default is 0
+}
+
+/**
+ * IpfsHash is used when the map is already pinned to IPFS, it should be string with IPFS hash
+ */
+export type OffChainMapEntries = OffChainMapEntry[] | IpfsHash;
+
+/**
+ * Base class for offchain lists and maps that does not have storage
+ */
+export class OffChainListBase extends Struct({
+  /** The root hash of the Merkle tree representing the whitelist. */
+  root: Field,
+}) {
+  isNone(): Bool {
+    return this.root.equals(Field(0));
+  }
+
+  isSome(): Bool {
+    return this.isNone().not();
+  }
+
+  async load(
+    storage: Storage,
+    name: string = "offchain-map"
+  ): Promise<OffchainMapOption> {
+    const isNone = this.isNone();
+    const map = await Provable.witnessAsync(OffchainMapOption, async () => {
+      if (isNone.toBoolean()) return OffchainMapOption.none();
+      else
+        return OffchainMapOption.fromValue(
+          await loadIndexedMerkleMap({
+            url: createIpfsURL({ hash: storage.toString() }),
+            type: OffchainMap,
+            name,
+          })
+        );
+    });
+    isNone.assertEquals(map.isSome.not());
+    const root = Provable.if(
+      map.isSome,
+      map.orElse(new OffchainMap()).root,
+      Field(0)
+    );
+    root.assertEquals(this.root);
+    return map;
+  }
+
+  /**
+   * The function fetches a whitelisted amount associated with a given key using a map and returns it
+   * as a FieldOption.
+   * @param {Field} key - The `key` parameter is of type `Field`,
+   * which represents a field element in the context of a cryptographic system.
+   * @returns The `getValue` function returns a `Promise` that resolves to a `FieldOption`
+   * object. This object contains a `value` property representing the amount retrieved from a map based
+   * on the provided key. The `isSome` property indicates whether the value is present or not.
+   * The value is not present if the list is NOT empty and the key is NOT in the map.
+   * The value is present if the list IS empty or the key IS in the map.
+   * The value is present and equals to Field(0) if the list IS empty.
+   */
+  async getValue(
+    key: Field,
+    storage: Storage,
+    name: string = "offchain-map"
+  ): Promise<FieldOption> {
+    const map = await this.load(storage, name);
+    const value = map.orElse(new OffchainMap()).getOption(key);
+    const valueField = value.orElse(Field(0));
+    return new FieldOption({
+      value: valueField,
+      isSome: value.isSome.or(this.isNone()),
+    });
+  }
+
+  static empty(): OffChainListBase {
+    return new OffChainListBase({
+      root: Field(0),
+    });
+  }
+
+  /**
+   * Creates a new OffchainListBase
+   * @param params - The parameters for creating the list.
+   * @param params.list - The list of entries to be added to the map.
+   * @param params.data - The JSON data that should be added to the IPFS storage that represent the initial data
+   * @returns A new `OffChainList` instance.
+   */
+  static async create(params: {
+    list: OffChainMapEntry[] | { key: string; value?: number }[];
+    name?: string;
+    data?: object;
+  }): Promise<{
+    listBase: OffChainListBase;
+    json: OffchainMapSerialized;
+  }> {
+    function toField(
+      value: bigint | string | number | Field | undefined
+    ): Field {
+      if (!value) return Field(0);
+      if (typeof value === "string") return Field.fromJSON(value);
+      if (typeof value === "bigint" || typeof value === "number")
+        return Field(value);
+      return value;
+    }
+
+    const list = params.list.map((item) => ({
+      key: toField(item.key),
+      value: toField(item.value),
+    }));
+    const map = new OffchainMap();
+    for (const item of list) {
+      map.insert(item.key, item.value);
+    }
+    const serializedMap = serializeIndexedMap(map);
+    const json: OffchainMapSerialized = {
+      [params.name ?? "offchain-map"]: {
+        map: serializedMap,
+        list: list.map((item) => ({
+          key: item.key.toJSON(),
+          value: item.value?.toJSON(),
+        })),
+        data: params.data,
+      },
+    };
+
+    return {
+      listBase: new OffChainListBase({
+        root: map.root,
+      }),
+      json,
+    };
+  }
+
+  toString(): string {
+    return JSON.stringify({ root: this.root.toJSON() }, null, 2);
+  }
+
+  static fromString(str: string): OffChainListBase {
+    const json = JSON.parse(str);
+    return new OffChainListBase({
+      root: Field.fromJSON(json.root),
+    });
+  }
+}
+
+export class OffChainList extends Struct({
+  /** The root hash of the Merkle tree representing the whitelist. */
+  root: Field,
+  /** Off-chain storage information, typically an IPFS hash pointing to the whitelist data. */
+  storage: Storage,
+}) {
+  isNone(): Bool {
+    return this.root.equals(Field(0)).or(this.storage.isEmpty());
+  }
+
+  isSome(): Bool {
+    return this.isNone().not();
+  }
+
+  async load(
+    name: string | undefined = "offchain-map"
+  ): Promise<OffchainMapOption> {
+    const isNone = this.isNone();
+    const map = await Provable.witnessAsync(OffchainMapOption, async () => {
+      if (isNone.toBoolean()) return OffchainMapOption.none();
+      else
+        return OffchainMapOption.fromValue(
+          await loadIndexedMerkleMap({
+            url: createIpfsURL({ hash: this.storage.toString() }),
+            type: OffchainMap,
+            name,
+          })
+        );
+    });
+    isNone.assertEquals(map.isSome.not());
+    const root = Provable.if(
+      map.isSome,
+      map.orElse(new OffchainMap()).root,
+      Field(0)
+    );
+    root.assertEquals(this.root);
+    return map;
+  }
+
+  /**
+   * The function fetches a whitelisted amount associated with a given key using a map and returns it
+   * as a FieldOption.
+   * @param {Field} key - The `key` parameter is of type `Field`,
+   * which represents a field element in the context of a cryptographic system.
+   * @returns The `getValue` function returns a `Promise` that resolves to a `FieldOption`
+   * object. This object contains a `value` property representing the amount retrieved from a map based
+   * on the provided key. The `isSome` property indicates whether the value is present or not.
+   * The value is not present if the list is NOT empty and the key is NOT in the map.
+   * The value is present if the list IS empty or the key IS in the map.
+   * The value is present and equals to Field(0) if the list IS empty.
+   */
+  async getValue(
+    key: Field,
+    name: string | undefined = "offchain-map"
+  ): Promise<FieldOption> {
+    const map = await this.load(name);
+    const value = map.orElse(new OffchainMap()).getOption(key);
+    const valueField = value.orElse(Field(0));
+    return new FieldOption({
+      value: valueField,
+      isSome: value.isSome.or(this.isNone()),
+    });
+  }
+
+  static empty(): OffChainList {
+    return new OffChainList({
+      root: Field(0),
+      storage: Storage.empty(),
+    });
+  }
+
+  /**
+   * Creates a new OffchainList
+   * and pins it to IPFS.
+   * @param params - The parameters for creating the list.
+   * @param params.list - The list of entries to be added to the map.
+   * @param params.data - The JSON data that should be added to the IPFS storage that represent the initial data
+   * @returns A new `OffChainList` instance.
+   */
+  static async create(params: {
+    list: OffChainMapEntry[] | { key: string; value?: number }[];
+    data?: object;
+    name?: string;
+    filename?: string;
+    keyvalues?: object;
+    timeout?: number;
+    attempts?: number;
+    auth?: string;
+    pin?: boolean;
+    json?: OffchainMapSerialized;
+  }): Promise<{ list: OffChainList; json: OffchainMapSerialized }> {
+    const {
+      name = "offchain-map",
+      filename = "offchain-list.json",
+      keyvalues,
+      timeout = 60 * 1000,
+      attempts = 5,
+      auth,
+      pin = true,
+      json: initialJson = {},
+    } = params;
+
+    const { listBase, json: newJson } = await OffChainListBase.create({
+      list: params.list,
+      data: params.data,
+      name,
+    });
+    const json = { ...initialJson, ...newJson };
+
+    if (process.env.DEBUG === "true")
+      console.log("OffChainList.create:", { json, name, keyvalues });
+    if (pin) {
+      let attempt = 0;
+      const start = Date.now();
+      let hash = await pinJSON({
+        data: json,
+        name: filename,
+        keyvalues,
+        auth,
+      });
+      while (!hash && attempt < attempts && Date.now() - start < timeout) {
+        attempt++;
+        await sleep(5000 * attempt); // handle rate-limits
+        hash = await pinJSON({
+          data: json,
+          name,
+          keyvalues,
+          auth,
+        });
+      }
+      if (!hash) throw new Error("Failed to pin OffchainMap");
+      return {
+        list: new OffChainList({
+          root: listBase.root,
+          storage: Storage.fromString(hash),
+        }),
+        json,
+      };
+    }
+
+    return {
+      list: new OffChainList({
+        root: listBase.root,
+        storage: Storage.empty(),
+      }),
+      json,
+    };
+  }
+
+  toString(): string {
+    return JSON.stringify(
+      { root: this.root.toJSON(), storage: this.storage.toString() },
+      null,
+      2
+    );
+  }
+
+  static fromString(str: string): OffChainList {
+    const json = JSON.parse(str);
+    return new OffChainList({
+      root: Field.fromJSON(json.root),
+      storage: Storage.fromString(json.storage),
+    });
+  }
+}

package/src/whitelist/whitelist.ts

@@ -0,0 +1,139 @@
+import { Struct, Field, Option, PublicKey, UInt64, Poseidon, Bool } from "o1js";
+import {
+  OffChainList,
+  OffchainMapOption,
+  OffchainMap,
+  OffchainMapSerialized,
+} from "./offchain-map.js";
+
+export class UInt64Option extends Option(UInt64) {}
+export class WhitelistedAddress {
+  address: PublicKey | string;
+  amount?: UInt64 | number; // Maximum permitted amount of the whitelisted transaction, default is 0
+}
+
+export class Whitelist extends Struct({
+  list: OffChainList,
+}) {
+  isNone(): Bool {
+    return this.list.isNone();
+  }
+
+  isSome(): Bool {
+    return this.list.isSome();
+  }
+
+  async load(): Promise<OffchainMapOption> {
+    return this.list.load();
+  }
+
+  /**
+   * The function fetches a whitelisted amount associated with a given address using a map and returns it
+   * as a UInt64Option.
+   * @param {PublicKey} address - The `address` parameter is of type `PublicKey`,
+   * used to retrieve a whitelisted amount for the given address.
+   * @returns The `fetchWhitelistedAmount` function returns a `Promise` that resolves to a `UInt64Option`
+   * object. This object contains a `value` property representing the amount retrieved from a map based
+   * on the provided address. The `isSome` property indicates whether the value is present or not.
+   * The value is not present if the whitelist is NOT empty and the address is NOT whitelisted.
+   * The value is present if the whitelist is NOT empty or the address IS whitelisted.
+   * The value is present and equals to UInt64.MAXINT() if the whitelist IS empty.
+   */
+  async getWhitelistedAmount(
+    address: PublicKey,
+    name: string = "whitelist"
+  ): Promise<UInt64Option> {
+    const map = await this.list.load(name);
+    const key = Poseidon.hashPacked(PublicKey, address);
+    const value = map.orElse(new OffchainMap()).getOption(key);
+    const valueField = value.orElse(UInt64.MAXINT().value);
+    valueField.assertLessThanOrEqual(UInt64.MAXINT().value);
+    const amount = UInt64.Unsafe.fromField(valueField);
+    return new UInt64Option({
+      value: amount,
+      isSome: value.isSome.or(this.isNone()),
+    });
+  }
+
+  static empty(): Whitelist {
+    return new Whitelist({
+      list: OffChainList.empty(),
+    });
+  }
+
+  /**
+   * Creates a new whitelist and pins it to IPFS.
+   * @param params - The parameters for creating the whitelist.
+   * @returns A new `Whitelist` instance.
+   */
+  static async create(params: {
+    list: WhitelistedAddress[];
+    name?: string;
+    filename?: string;
+    keyvalues?: object;
+    timeout?: number;
+    attempts?: number;
+    auth?: string;
+    pin?: boolean;
+    json?: OffchainMapSerialized;
+  }): Promise<{ whitelist: Whitelist; json: OffchainMapSerialized }> {
+    const {
+      name = "whitelist",
+      filename = "whitelist.json",
+      keyvalues,
+      timeout,
+      attempts,
+      auth,
+      pin = true,
+      json: initialJson = {},
+    } = params;
+
+    function parseAddress(address: string | PublicKey): PublicKey {
+      return typeof address === "string"
+        ? PublicKey.fromBase58(address)
+        : address;
+    }
+    function parseAmount(amount?: number | UInt64): UInt64 {
+      if (amount === undefined) return UInt64.zero;
+      return typeof amount === "number"
+        ? UInt64.from(Math.round(amount))
+        : amount;
+    }
+
+    const entries: { address: PublicKey; amount: UInt64 }[] = params.list.map(
+      (item) => ({
+        address: parseAddress(item.address),
+        amount: parseAmount(item.amount),
+      })
+    );
+
+    const { list, json } = await OffChainList.create({
+      list: entries.map((item) => ({
+        key: Poseidon.hashPacked(PublicKey, item.address),
+        value: item.amount.value,
+      })),
+      data: entries.map((item) => ({
+        address: item.address.toBase58(),
+        amount: Number(item.amount.toBigInt()),
+      })),
+      name,
+      filename,
+      keyvalues,
+      timeout,
+      attempts,
+      auth,
+      pin,
+      json: initialJson,
+    });
+
+    return { whitelist: new Whitelist({ list }), json };
+  }
+
+  toString(): string {
+    return this.list.toString();
+  }
+
+  static fromString(str: string): Whitelist {
+    return new Whitelist({ list: OffChainList.fromString(str) });
+  }
+}