@silvana-one/storage 0.1.0

package/dist/web/whitelist/whitelist.d.ts

@@ -0,0 +1,122 @@
+import { Field, Option, PublicKey, UInt64, Bool } from "o1js";
+import { OffChainList, OffchainMapOption, OffchainMapSerialized } from "./offchain-map.js";
+declare const UInt64Option_base: Omit<import("node_modules/o1js/dist/node/lib/provable/types/provable-intf.js").Provable<Option<UInt64, bigint>, bigint | undefined>, "fromFields"> & {
+    fromFields: (fields: import("node_modules/o1js/dist/node/lib/provable/field.js").Field[]) => Option<UInt64, bigint>;
+} & (new (option: {
+    isSome: Bool;
+    value: UInt64;
+}) => Option<UInt64, bigint>) & {
+    fromValue(value: bigint | UInt64 | {
+        isSome: boolean | Bool;
+        value: bigint | UInt64;
+    } | undefined): Option<UInt64, bigint>;
+    from(value?: bigint | UInt64 | undefined): Option<UInt64, bigint>;
+    none(): Option<UInt64, bigint>;
+};
+export declare class UInt64Option extends UInt64Option_base {
+}
+export declare class WhitelistedAddress {
+    address: PublicKey | string;
+    amount?: UInt64 | number;
+}
+declare const Whitelist_base: (new (value: {
+    list: OffChainList;
+}) => {
+    list: OffChainList;
+}) & {
+    _isStruct: true;
+} & Omit<import("node_modules/o1js/dist/node/lib/provable/types/provable-intf.js").Provable<{
+    list: OffChainList;
+}, {
+    list: {
+        root: bigint;
+        storage: {
+            url: bigint[];
+        };
+    };
+}>, "fromFields"> & {
+    fromFields: (fields: import("node_modules/o1js/dist/node/lib/provable/field.js").Field[]) => {
+        list: OffChainList;
+    };
+} & {
+    fromValue: (value: {
+        list: OffChainList | {
+            root: string | number | bigint | import("node_modules/o1js/dist/node/lib/provable/field.js").Field;
+            storage: import("../index.js").Storage | {
+                url: import("node_modules/o1js/dist/node/lib/provable/field.js").Field[] | bigint[];
+            };
+        };
+    }) => {
+        list: OffChainList;
+    };
+    toInput: (x: {
+        list: OffChainList;
+    }) => {
+        fields?: Field[] | undefined;
+        packed?: [Field, number][] | undefined;
+    };
+    toJSON: (x: {
+        list: OffChainList;
+    }) => {
+        list: {
+            root: string;
+            storage: {
+                url: string[];
+            };
+        };
+    };
+    fromJSON: (x: {
+        list: {
+            root: string;
+            storage: {
+                url: string[];
+            };
+        };
+    }) => {
+        list: OffChainList;
+    };
+    empty: () => {
+        list: OffChainList;
+    };
+};
+export declare class Whitelist extends Whitelist_base {
+    isNone(): Bool;
+    isSome(): Bool;
+    load(): Promise<OffchainMapOption>;
+    /**
+     * 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.
+     */
+    getWhitelistedAmount(address: PublicKey, name?: string): Promise<UInt64Option>;
+    static empty(): Whitelist;
+    /**
+     * Creates a new whitelist and pins it to IPFS.
+     * @param params - The parameters for creating the whitelist.
+     * @returns A new `Whitelist` instance.
+     */
+    static 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;
+    }>;
+    toString(): string;
+    static fromString(str: string): Whitelist;
+}
+export {};

package/dist/web/whitelist/whitelist.js

@@ -0,0 +1,98 @@
+import { Struct, Option, PublicKey, UInt64, Poseidon } from "o1js";
+import { OffChainList, OffchainMap, } from "./offchain-map.js";
+export class UInt64Option extends Option(UInt64) {
+}
+export class WhitelistedAddress {
+}
+export class Whitelist extends Struct({
+    list: OffChainList,
+}) {
+    isNone() {
+        return this.list.isNone();
+    }
+    isSome() {
+        return this.list.isSome();
+    }
+    async load() {
+        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, name = "whitelist") {
+        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() {
+        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) {
+        const { name = "whitelist", filename = "whitelist.json", keyvalues, timeout, attempts, auth, pin = true, json: initialJson = {}, } = params;
+        function parseAddress(address) {
+            return typeof address === "string"
+                ? PublicKey.fromBase58(address)
+                : address;
+        }
+        function parseAmount(amount) {
+            if (amount === undefined)
+                return UInt64.zero;
+            return typeof amount === "number"
+                ? UInt64.from(Math.round(amount))
+                : amount;
+        }
+        const entries = 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() {
+        return this.list.toString();
+    }
+    static fromString(str) {
+        return new Whitelist({ list: OffChainList.fromString(str) });
+    }
+}
+//# sourceMappingURL=whitelist.js.map

package/dist/web/whitelist/whitelist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"whitelist.js","sourceRoot":"","sources":["../../../src/whitelist/whitelist.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@silvana-one/storage",
+  "description": "Silvana Storage Library",
+  "version": "0.1.0",
+  "author": "DFST",
+  "bugs": "https://github.com/SilvanaOne/silvana-lib/issues",
+  "dependencies": {
+    "tslib": "^2.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "esbuild": "^0.24.0",
+    "o1js": "^2.2.0",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "exports": {
+    "types": "./dist/node/index.d.ts",
+    "node": {
+      "import": "./dist/node/index.js",
+      "require": "./dist/node/index.cjs"
+    },
+    "browser": "./dist/web/index.js",
+    "default": "./dist/web/index.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "homepage": "https://docs.silvana.one",
+  "keywords": [
+    "cloud",
+    "mina-protocol",
+    "silvana",
+    "whitelist",
+    "proving",
+    "storage",
+    "typescript"
+  ],
+  "license": "Apache-2.0",
+  "main": "dist/web/index.js",
+  "peerDependencies": {
+    "o1js": "^2.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": "SilvanaOne/silvana-lib.git",
+  "scripts": {
+    "build": "rm -rf dist && tsc && tsc --build tsconfig.web.json && node build-cjs.js",
+    "release": "npm publish --access public"
+  },
+  "type": "module",
+  "types": "./dist/node/index.d.ts"
+}

package/src/base64/bigint.ts

@@ -0,0 +1,87 @@
+// URL friendly base64 encoding
+const TABLE =
+  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+export function bigintToBase56(value: bigint): string {
+  const digits = toBase(value, 56n);
+  //console.log("digits:", digits);
+  const str = digits.map((x) => TABLE[Number(x)]).join("");
+  //console.log("str:", str);
+  return str;
+}
+
+export function bigintFromBase56(str: string): bigint {
+  const base56Digits = str.split("").map((x) => BigInt(TABLE.indexOf(x)));
+  const x = fromBase(base56Digits, 56n);
+  return x;
+}
+
+export function bigintToBase64(value: bigint): string {
+  const digits = toBase(value, 64n);
+  //console.log("digits:", digits);
+  const str = digits.map((x) => TABLE[Number(x)]).join("");
+  //console.log("str:", str);
+  return str;
+}
+
+export function bigintFromBase64(str: string): bigint {
+  const base64Digits = str.split("").map((x) => BigInt(TABLE.indexOf(x)));
+  const x = fromBase(base64Digits, 64n);
+  return x;
+}
+
+export function fromBase(digits: bigint[], base: bigint) {
+  if (base <= 0n) throw Error("fromBase: base must be positive");
+  // compute powers base, base^2, base^4, ..., base^(2^k)
+  // with largest k s.t. n = 2^k < digits.length
+  let basePowers = [];
+  for (let power = base, n = 1; n < digits.length; power **= 2n, n *= 2) {
+    basePowers.push(power);
+  }
+  let k = basePowers.length;
+  // pad digits array with zeros s.t. digits.length === 2^k
+  digits = digits.concat(Array(2 ** k - digits.length).fill(0n));
+  // accumulate [x0, x1, x2, x3, ...] -> [x0 + base*x1, x2 + base*x3, ...] -> [x0 + base*x1 + base^2*(x2 + base*x3), ...] -> ...
+  // until we end up with a single element
+  for (let i = 0; i < k; i++) {
+    let newDigits = Array(digits.length >> 1);
+    let basePower = basePowers[i];
+    for (let j = 0; j < newDigits.length; j++) {
+      newDigits[j] = digits[2 * j] + basePower * digits[2 * j + 1];
+    }
+    digits = newDigits;
+  }
+  console.assert(digits.length === 1);
+  let [digit] = digits;
+  return digit;
+}
+
+export function toBase(x: bigint, base: bigint) {
+  if (base <= 0n) throw Error("toBase: base must be positive");
+  // compute powers base, base^2, base^4, ..., base^(2^k)
+  // with largest k s.t. base^(2^k) < x
+  let basePowers = [];
+  for (let power = base; power <= x; power **= 2n) {
+    basePowers.push(power);
+  }
+  let digits = [x]; // single digit w.r.t base^(2^(k+1))
+  // successively split digits w.r.t. base^(2^j) into digits w.r.t. base^(2^(j-1))
+  // until we arrive at digits w.r.t. base
+  let k = basePowers.length;
+  for (let i = 0; i < k; i++) {
+    let newDigits = Array(2 * digits.length);
+    let basePower = basePowers[k - 1 - i];
+    for (let j = 0; j < digits.length; j++) {
+      let x = digits[j];
+      let high = x / basePower;
+      newDigits[2 * j + 1] = high;
+      newDigits[2 * j] = x - high * basePower;
+    }
+    digits = newDigits;
+  }
+  // pop "leading" zero digits
+  while (digits[digits.length - 1] === 0n) {
+    digits.pop();
+  }
+  return digits;
+}

package/src/base64/field.ts

@@ -0,0 +1,34 @@
+import { Field } from "o1js";
+import { toBase, fromBase } from "./bigint.js";
+
+// URL friendly base64 encoding
+const TABLE =
+  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+export function fieldToBase56(field: Field): string {
+  const digits = toBase(field.toBigInt(), 56n);
+  //console.log("digits:", digits);
+  const str = digits.map((x) => TABLE[Number(x)]).join("");
+  //console.log("str:", str);
+  return str;
+}
+
+export function fieldFromBase56(str: string): Field {
+  const base56Digits = str.split("").map((x) => BigInt(TABLE.indexOf(x)));
+  const x = fromBase(base56Digits, 56n);
+  return Field(x);
+}
+
+export function fieldToBase64(field: Field): string {
+  const digits = toBase(field.toBigInt(), 64n);
+  //console.log("digits:", digits);
+  const str = digits.map((x) => TABLE[Number(x)]).join("");
+  //console.log("str:", str);
+  return str;
+}
+
+export function fieldFromBase64(str: string): Field {
+  const base64Digits = str.split("").map((x) => BigInt(TABLE.indexOf(x)));
+  const x = fromBase(base64Digits, 64n);
+  return Field(x);
+}

package/src/base64/index.ts

@@ -0,0 +1,2 @@
+export * from "./bigint.js";
+export * from "./field.js";

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./base64/index.js";
+export * from "./indexed-map/index.js";
+export * from "./storage/index.js";
+export * from "./util/index.js";
+export * from "./whitelist/index.js";

package/src/indexed-map/index.ts

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

package/src/indexed-map/indexed-map.ts

@@ -0,0 +1,189 @@
+import { Experimental, Field } from "o1js";
+import { bigintToBase64, bigintFromBase64 } from "../base64/bigint.js";
+import { sleep } from "../util/sleep.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 type IndexedMapSerializedJson = {
+  [key: string]: { map: IndexedMapSerialized };
+};
+
+export async function loadIndexedMerkleMap(params: {
+  url: string;
+  type: ReturnType<typeof IndexedMerkleMap>;
+  name?: string;
+  timeout?: number;
+  attempts?: number;
+}) {
+  const {
+    url,
+    type,
+    name = "indexed-map",
+    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 IndexedMapSerializedJson)[
+    name
+  ].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;
+  filename?: string;
+  keyvalues?: { key: string; value: string }[];
+  auth: string;
+}): Promise<string | undefined> {
+  const {
+    map,
+    name = "indexed-map",
+    keyvalues,
+    auth,
+    filename = "indexed-map",
+  } = params;
+  const serialized = serializeIndexedMap(map);
+  const json: IndexedMapSerializedJson = { [name]: { map: serialized } };
+  const ipfsHash = await pinJSON({
+    data: json,
+    name: filename,
+    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/storage/index.ts

@@ -0,0 +1,3 @@
+export * from "./ipfs.js";
+export * from "./pinata.js";
+export * from "./storage.js";

package/src/storage/ipfs.ts

@@ -0,0 +1,20 @@
+export function createIpfsURL(params: {
+  hash: string;
+  gateway?: string;
+  apiToken?: string;
+}): string {
+  let { hash, gateway, apiToken } = params;
+  gateway ??=
+    process.env.PINATA_IPFS_GATEWAY ??
+    process.env.NEXT_PUBLIC_PINATA_IPFS_GATEWAY ??
+    process.env.REACT_APP_PINATA_IPFS_GATEWAY;
+  apiToken ??=
+    process.env.PINATA_GATEWAY_TOKEN ??
+    process.env.NEXT_PUBLIC_PINATA_GATEWAY_TOKEN ??
+    process.env.REACT_APP_PINATA_GATEWAY_TOKEN;
+
+  if (!gateway) {
+    gateway = "https://gateway.pinata.cloud/ipfs/";
+  }
+  return gateway + hash + (apiToken ? "?pinataGatewayToken=" + apiToken : "");
+}