@waku/rln 0.0.1 → 0.0.2-c86e056.0

package/src/resources/witness_calculator.d.ts

@@ -0,0 +1,11 @@
+export async function builder(
+  code: Uint8Array,
+  sanityCheck: boolean
+): Promise<WitnessCalculator>;
+
+export class WitnessCalculator {
+  public calculateWitness(
+    input: unknown,
+    sanityCheck: boolean
+  ): Promise<Array<bigint>>;
+}

package/src/rln.ts

@@ -1,136 +1,299 @@
-import * as resources from "./resources";
-import * as wc from "./witness_calculator";
-import * as zerokitRLN from "./zerokit/rln_wasm";
+import { createDecoder, createEncoder } from "@waku/core";
+import type {
+  ContentTopic,
+  IDecodedMessage,
+  EncoderOptions as WakuEncoderOptions
+} from "@waku/interfaces";
+import { Logger } from "@waku/utils";
+import init from "@waku/zerokit-rln-wasm";
+import * as zerokitRLN from "@waku/zerokit-rln-wasm";
+import { ethers } from "ethers";
 
-/**
- * Convert a base64 string into uint8Array
- * @param base64
- * @returns Uint8Array
- */
-function base64ToUint8Array(base64: string): Uint8Array {
-  const binary_string = window.atob(base64);
-  const len = binary_string.length;
-  const bytes = new Uint8Array(len);
-  for (let i = 0; i < len; i++) {
-    bytes[i] = binary_string.charCodeAt(i);
-  }
-  return bytes;
-}
+import {
+  createRLNDecoder,
+  createRLNEncoder,
+  type RLNDecoder,
+  type RLNEncoder
+} from "./codec.js";
+import { RLNContract, SEPOLIA_CONTRACT } from "./contract/index.js";
+import { IdentityCredential } from "./identity.js";
+import { Keystore } from "./keystore/index.js";
+import type {
+  DecryptedCredentials,
+  EncryptedCredentials
+} from "./keystore/index.js";
+import { KeystoreEntity, Password } from "./keystore/types.js";
+import verificationKey from "./resources/verification_key";
+import * as wc from "./resources/witness_calculator";
+import { WitnessCalculator } from "./resources/witness_calculator";
+import { extractMetaMaskSigner } from "./utils/index.js";
+import { Zerokit } from "./zerokit.js";
 
-/**
- * Concatenate Uint8Arrays
- * @param input
- * @returns concatenation of all Uint8Array received as input
- */
-function concatenate(...input: Uint8Array[]): Uint8Array {
-  let totalLength = 0;
-  for (const arr of input) {
-    totalLength += arr.length;
-  }
-  const result = new Uint8Array(totalLength);
-  let offset = 0;
-  for (const arr of input) {
-    result.set(arr, offset);
-    offset += arr.length;
-  }
-  return result;
-}
+const log = new Logger("waku:rln");
 
-const DEPTH = 20;
-const VERIFICATION_KEY = base64ToUint8Array(resources.verification_key);
-const ZKEY = base64ToUint8Array(resources.zkey);
-const CIRCUIT = base64ToUint8Array(resources.circuit);
+async function loadWitnessCalculator(): Promise<WitnessCalculator> {
+  const url = new URL("./resources/rln.wasm", import.meta.url);
+  const response = await fetch(url);
+  return await wc.builder(new Uint8Array(await response.arrayBuffer()), false);
+}
 
-zerokitRLN.init_panic_hook();
+async function loadZkey(): Promise<Uint8Array> {
+  const url = new URL("./resources/rln_final.zkey", import.meta.url);
+  const response = await fetch(url);
+  return new Uint8Array(await response.arrayBuffer());
+}
 
 /**
  * Create an instance of RLN
  * @returns RLNInstance
  */
 export async function create(): Promise<RLNInstance> {
-  const witnessCalculator = await wc.builder(CIRCUIT, false);
-  const zkRLN = zerokitRLN.newRLN(DEPTH, ZKEY, VERIFICATION_KEY);
-  return new RLNInstance(zkRLN, witnessCalculator);
-}
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    await (init as any)?.();
+    zerokitRLN.init_panic_hook();
+
+    const witnessCalculator = await loadWitnessCalculator();
+    const zkey = await loadZkey();
 
-export class MembershipKey {
-  readonly IDKey: Uint8Array;
-  readonly IDCommitment: Uint8Array;
+    const stringEncoder = new TextEncoder();
+    const vkey = stringEncoder.encode(JSON.stringify(verificationKey));
 
-  constructor(memKeys: Uint8Array) {
-    this.IDKey = memKeys.subarray(0, 32);
-    this.IDCommitment = memKeys.subarray(32);
+    const DEPTH = 20;
+    const zkRLN = zerokitRLN.newRLN(DEPTH, zkey, vkey);
+    const zerokit = new Zerokit(zkRLN, witnessCalculator);
+
+    return new RLNInstance(zerokit);
+  } catch (error) {
+    log.error("Failed to initialize RLN:", error);
+    throw error;
   }
 }
 
+type StartRLNOptions = {
+  /**
+   * If not set - will extract MetaMask account and get signer from it.
+   */
+  signer?: ethers.Signer;
+  /**
+   * If not set - will use default SEPOLIA_CONTRACT address.
+   */
+  address?: string;
+  /**
+   * Credentials to use for generating proofs and connecting to the contract and network.
+   * If provided used for validating the network chainId and connecting to registry contract.
+   */
+  credentials?: EncryptedCredentials | DecryptedCredentials;
+  /**
+   * Rate limit for the member.
+   */
+  rateLimit?: number;
+};
+
+type RegisterMembershipOptions =
+  | { signature: string }
+  | { identity: IdentityCredential };
+
+type WakuRLNEncoderOptions = WakuEncoderOptions & {
+  credentials: EncryptedCredentials | DecryptedCredentials;
+};
+
 export class RLNInstance {
-  zkRLN: number;
-  witnessCalculator: any;
+  private started = false;
+  private starting = false;
+
+  private _contract: undefined | RLNContract;
+  private _signer: undefined | ethers.Signer;
+
+  private keystore = Keystore.create();
+  private _credentials: undefined | DecryptedCredentials;
+
+  public constructor(public zerokit: Zerokit) {}
 
-  constructor(zkRLN: number, wc: any) {
-    this.zkRLN = zkRLN;
-    this.witnessCalculator = wc;
+  public get contract(): undefined | RLNContract {
+    return this._contract;
   }
 
-  generateMembershipKey(): MembershipKey {
-    const memKeys = zerokitRLN.generateMembershipKey(this.zkRLN);
-    return new MembershipKey(memKeys);
+  public get signer(): undefined | ethers.Signer {
+    return this._signer;
   }
 
-  inserMember(idCommitment: Uint8Array): void {
-    zerokitRLN.insertMember(this.zkRLN, idCommitment);
+  public async start(options: StartRLNOptions = {}): Promise<void> {
+    if (this.started || this.starting) {
+      return;
+    }
+
+    this.starting = true;
+
+    try {
+      const { credentials, keystore } =
+        await RLNInstance.decryptCredentialsIfNeeded(options.credentials);
+      const { signer, address } = await this.determineStartOptions(
+        options,
+        credentials
+      );
+
+      if (keystore) {
+        this.keystore = keystore;
+      }
+
+      this._credentials = credentials;
+      this._signer = signer!;
+      this._contract = await RLNContract.init(this, {
+        address: address!,
+        signer: signer!,
+        rateLimit: options.rateLimit
+      });
+      this.started = true;
+    } finally {
+      this.starting = false;
+    }
   }
 
-  serializeMessage(
-    uint8Msg: Uint8Array,
-    memIndex: number,
-    epoch: Uint8Array,
-    idKey: Uint8Array
-  ): Uint8Array {
-    if (epoch.length != 32) throw "invalid epoch";
-    if (idKey.length != 32) throw "invalid id key";
-
-    // calculate message length
-    const msgLen = Buffer.allocUnsafe(8);
-    msgLen.writeUIntLE(uint8Msg.length, 0, 8);
-
-    // Converting index to LE bytes
-    const memIndexBytes = Buffer.allocUnsafe(8);
-    memIndexBytes.writeUIntLE(memIndex, 0, 8);
-
-    // [ id_key<32> | id_index<8> | epoch<32> | signal_len<8> | signal<var> ]
-    return concatenate(idKey, memIndexBytes, epoch, msgLen, uint8Msg);
+  private async determineStartOptions(
+    options: StartRLNOptions,
+    credentials: KeystoreEntity | undefined
+  ): Promise<StartRLNOptions> {
+    let chainId = credentials?.membership.chainId;
+    const address =
+      credentials?.membership.address ||
+      options.address ||
+      SEPOLIA_CONTRACT.address;
+
+    if (address === SEPOLIA_CONTRACT.address) {
+      chainId = SEPOLIA_CONTRACT.chainId;
+    }
+
+    const signer = options.signer || (await extractMetaMaskSigner());
+    const currentChainId = await signer.getChainId();
+
+    if (chainId && chainId !== currentChainId) {
+      throw Error(
+        `Failed to start RLN contract, chain ID of contract is different from current one: contract-${chainId}, current network-${currentChainId}`
+      );
+    }
+
+    return {
+      signer,
+      address
+    };
   }
 
-  async generateProof(
-    msg: Uint8Array,
-    index: number,
-    epoch: Uint8Array,
-    idKey: Uint8Array
-  ): Promise<Uint8Array> {
-    if (epoch.length != 32) throw "invalid epoch";
-    if (idKey.length != 32) throw "invalid id key";
-    if (index < 0) throw "index must be >= 0";
-
-    const serialized_msg = this.serializeMessage(msg, index, epoch, idKey);
-    const rlnWitness = zerokitRLN.getSerializedRLNWitness(
-      this.zkRLN,
-      serialized_msg
-    );
-    const inputs = zerokitRLN.RLNWitnessToJson(this.zkRLN, rlnWitness);
-    const calculatedWitness = await this.witnessCalculator.calculateWitness(
-      inputs,
-      false
-    ); // no sanity check being used in zerokit
-
-    return zerokitRLN.generate_rln_proof_with_witness(
-      this.zkRLN,
-      calculatedWitness,
-      rlnWitness
+  private static async decryptCredentialsIfNeeded(
+    credentials?: EncryptedCredentials | DecryptedCredentials
+  ): Promise<{ credentials?: DecryptedCredentials; keystore?: Keystore }> {
+    if (!credentials) {
+      return {};
+    }
+
+    if ("identity" in credentials) {
+      return { credentials };
+    }
+
+    const keystore = Keystore.fromString(credentials.keystore);
+
+    if (!keystore) {
+      return {};
+    }
+
+    const decryptedCredentials = await keystore.readCredential(
+      credentials.id,
+      credentials.password
     );
+
+    return {
+      keystore,
+      credentials: decryptedCredentials
+    };
+  }
+
+  public async registerMembership(
+    options: RegisterMembershipOptions
+  ): Promise<undefined | DecryptedCredentials> {
+    if (!this.contract) {
+      throw Error("RLN Contract is not initialized.");
+    }
+
+    let identity = "identity" in options && options.identity;
+
+    if ("signature" in options) {
+      identity = this.zerokit.generateSeededIdentityCredential(
+        options.signature
+      );
+    }
+
+    if (!identity) {
+      throw Error("Missing signature or identity to register membership.");
+    }
+
+    return this.contract.registerWithIdentity(identity);
+  }
+
+  /**
+   * Changes credentials in use by relying on provided Keystore earlier in rln.start
+   * @param id: string, hash of credentials to select from Keystore
+   * @param password: string or bytes to use to decrypt credentials from Keystore
+   */
+  public async useCredentials(id: string, password: Password): Promise<void> {
+    this._credentials = await this.keystore?.readCredential(id, password);
+  }
+
+  public async createEncoder(
+    options: WakuRLNEncoderOptions
+  ): Promise<RLNEncoder> {
+    const { credentials: decryptedCredentials } =
+      await RLNInstance.decryptCredentialsIfNeeded(options.credentials);
+    const credentials = decryptedCredentials || this._credentials;
+
+    if (!credentials) {
+      throw Error(
+        "Failed to create Encoder: missing RLN credentials. Use createRLNEncoder directly."
+      );
+    }
+
+    await this.verifyCredentialsAgainstContract(credentials);
+
+    return createRLNEncoder({
+      encoder: createEncoder(options),
+      rlnInstance: this,
+      index: credentials.membership.treeIndex,
+      credential: credentials.identity
+    });
+  }
+
+  private async verifyCredentialsAgainstContract(
+    credentials: KeystoreEntity
+  ): Promise<void> {
+    if (!this._contract) {
+      throw Error(
+        "Failed to verify chain coordinates: no contract initialized."
+      );
+    }
+
+    const registryAddress = credentials.membership.address;
+    const currentRegistryAddress = this._contract.contract.address;
+    if (registryAddress !== currentRegistryAddress) {
+      throw Error(
+        `Failed to verify chain coordinates: credentials contract address=${registryAddress} is not equal to registryContract address=${currentRegistryAddress}`
+      );
+    }
+
+    const chainId = credentials.membership.chainId;
+    const network = await this._contract.contract.provider.getNetwork();
+    const currentChainId = network.chainId;
+    if (chainId !== currentChainId) {
+      throw Error(
+        `Failed to verify chain coordinates: credentials chainID=${chainId} is not equal to registryContract chainID=${currentChainId}`
+      );
+    }
   }
 
-  verifyProof(proof: Uint8Array): boolean {
-    return zerokitRLN.verifyProof(this.zkRLN, proof);
+  public createDecoder(
+    contentTopic: ContentTopic
+  ): RLNDecoder<IDecodedMessage> {
+    return createRLNDecoder({
+      rlnInstance: this,
+      decoder: createDecoder(contentTopic)
+    });
   }
 }

package/src/root_tracker.ts

@@ -0,0 +1,92 @@
+class RootPerBlock {
+  public constructor(
+    public root: Uint8Array,
+    public blockNumber: number
+  ) {}
+}
+
+const maxBufferSize = 20;
+
+export class MerkleRootTracker {
+  private validMerkleRoots: Array<RootPerBlock> = new Array<RootPerBlock>();
+  private merkleRootBuffer: Array<RootPerBlock> = new Array<RootPerBlock>();
+
+  public constructor(
+    private acceptableRootWindowSize: number,
+    initialRoot: Uint8Array
+  ) {
+    this.pushRoot(0, initialRoot);
+  }
+
+  public backFill(fromBlockNumber: number): void {
+    if (this.validMerkleRoots.length == 0) return;
+
+    let numBlocks = 0;
+    for (let i = this.validMerkleRoots.length - 1; i >= 0; i--) {
+      if (this.validMerkleRoots[i].blockNumber >= fromBlockNumber) {
+        numBlocks++;
+      }
+    }
+
+    if (numBlocks == 0) return;
+
+    const olderBlock = fromBlockNumber < this.validMerkleRoots[0].blockNumber;
+
+    // Remove last roots
+    let rootsToPop = numBlocks;
+    if (this.validMerkleRoots.length < rootsToPop) {
+      rootsToPop = this.validMerkleRoots.length;
+    }
+
+    this.validMerkleRoots = this.validMerkleRoots.slice(
+      0,
+      this.validMerkleRoots.length - rootsToPop
+    );
+
+    if (this.merkleRootBuffer.length == 0) return;
+
+    if (olderBlock) {
+      const idx = this.merkleRootBuffer.findIndex(
+        (x) => x.blockNumber == fromBlockNumber
+      );
+      if (idx > -1) {
+        this.merkleRootBuffer = this.merkleRootBuffer.slice(0, idx);
+      }
+    }
+
+    // Backfill the tree's acceptable roots
+    let rootsToRestore =
+      this.acceptableRootWindowSize - this.validMerkleRoots.length;
+    if (this.merkleRootBuffer.length < rootsToRestore) {
+      rootsToRestore = this.merkleRootBuffer.length;
+    }
+
+    for (let i = 0; i < rootsToRestore; i++) {
+      const x = this.merkleRootBuffer.pop();
+      if (x) this.validMerkleRoots.unshift(x);
+    }
+  }
+
+  public pushRoot(blockNumber: number, root: Uint8Array): void {
+    this.validMerkleRoots.push(new RootPerBlock(root, blockNumber));
+
+    // Maintain valid merkle root window
+    if (this.validMerkleRoots.length > this.acceptableRootWindowSize) {
+      const x = this.validMerkleRoots.shift();
+      if (x) this.merkleRootBuffer.push(x);
+    }
+
+    // Maintain merkle root buffer
+    if (this.merkleRootBuffer.length > maxBufferSize) {
+      this.merkleRootBuffer.shift();
+    }
+  }
+
+  public roots(): Array<Uint8Array> {
+    return this.validMerkleRoots.map((x) => x.root);
+  }
+
+  public buffer(): Array<Uint8Array> {
+    return this.merkleRootBuffer.map((x) => x.root);
+  }
+}

package/src/utils/bytes.ts

@@ -0,0 +1,84 @@
+/**
+ * Concatenate Uint8Arrays
+ * @param input
+ * @returns concatenation of all Uint8Array received as input
+ */
+export function concatenate(...input: Uint8Array[]): Uint8Array {
+  let totalLength = 0;
+  for (const arr of input) {
+    totalLength += arr.length;
+  }
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const arr of input) {
+    result.set(arr, offset);
+    offset += arr.length;
+  }
+  return result;
+}
+
+// Adapted from https://github.com/feross/buffer
+function checkInt(
+  buf: Uint8Array,
+  value: number,
+  offset: number,
+  ext: number,
+  max: number,
+  min: number
+): void {
+  if (value > max || value < min)
+    throw new RangeError('"value" argument is out of bounds');
+  if (offset + ext > buf.length) throw new RangeError("Index out of range");
+}
+
+export function writeUIntLE(
+  buf: Uint8Array,
+  value: number,
+  offset: number,
+  byteLength: number,
+  noAssert?: boolean
+): Uint8Array {
+  value = +value;
+  offset = offset >>> 0;
+  byteLength = byteLength >>> 0;
+  if (!noAssert) {
+    const maxBytes = Math.pow(2, 8 * byteLength) - 1;
+    checkInt(buf, value, offset, byteLength, maxBytes, 0);
+  }
+
+  let mul = 1;
+  let i = 0;
+  buf[offset] = value & 0xff;
+  while (++i < byteLength && (mul *= 0x100)) {
+    buf[offset + i] = (value / mul) & 0xff;
+  }
+
+  return buf;
+}
+
+/**
+ * Transforms Uint8Array into BigInt
+ * @param array: Uint8Array
+ * @returns BigInt
+ */
+export function buildBigIntFromUint8Array(
+  array: Uint8Array,
+  byteOffset: number = 0
+): bigint {
+  const dataView = new DataView(array.buffer);
+  return dataView.getBigUint64(byteOffset, true);
+}
+
+/**
+ * Fills with zeros to set length
+ * @param array little endian Uint8Array
+ * @param length amount to pad
+ * @returns little endian Uint8Array padded with zeros to set length
+ */
+export function zeroPadLE(array: Uint8Array, length: number): Uint8Array {
+  const result = new Uint8Array(length);
+  for (let i = 0; i < length; i++) {
+    result[i] = array[i] || 0;
+  }
+  return result;
+}

package/src/utils/epoch.ts

@@ -0,0 +1,30 @@
+import { Logger } from "@waku/utils";
+
+const DefaultEpochUnitSeconds = 10; // the rln-relay epoch length in seconds
+
+const log = new Logger("waku:rln:epoch");
+
+export function dateToEpoch(
+  timestamp: Date,
+  epochUnitSeconds: number = DefaultEpochUnitSeconds
+): number {
+  const time = timestamp.getTime();
+  const epoch = Math.floor(time / 1000 / epochUnitSeconds);
+  log.info("generated epoch", epoch);
+  return epoch;
+}
+
+export function epochIntToBytes(epoch: number): Uint8Array {
+  const bytes = new Uint8Array(32);
+  const db = new DataView(bytes.buffer);
+  db.setUint32(0, epoch, true);
+  log.info("encoded epoch", epoch, bytes);
+  return bytes;
+}
+
+export function epochBytesToInt(bytes: Uint8Array): number {
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const epoch = dv.getUint32(0, true);
+  log.info("decoded epoch", epoch, bytes);
+  return epoch;
+}

package/src/utils/hash.ts

@@ -0,0 +1,15 @@
+import * as zerokitRLN from "@waku/zerokit-rln-wasm";
+
+import { concatenate, writeUIntLE } from "./bytes.js";
+
+export function poseidonHash(...input: Array<Uint8Array>): Uint8Array {
+  const inputLen = writeUIntLE(new Uint8Array(8), input.length, 0, 8);
+  const lenPrefixedData = concatenate(inputLen, ...input);
+  return zerokitRLN.poseidonHash(lenPrefixedData);
+}
+
+export function sha256(input: Uint8Array): Uint8Array {
+  const inputLen = writeUIntLE(new Uint8Array(8), input.length, 0, 8);
+  const lenPrefixedData = concatenate(inputLen, input);
+  return zerokitRLN.hash(lenPrefixedData);
+}

package/src/utils/index.ts

@@ -0,0 +1,9 @@
+export { extractMetaMaskSigner } from "./metamask.js";
+export {
+  concatenate,
+  writeUIntLE,
+  buildBigIntFromUint8Array,
+  zeroPadLE
+} from "./bytes.js";
+export { sha256, poseidonHash } from "./hash.js";
+export { dateToEpoch, epochIntToBytes, epochBytesToInt } from "./epoch.js";

package/src/utils/metamask.ts

@@ -0,0 +1,17 @@
+import { ethers } from "ethers";
+
+export const extractMetaMaskSigner = async (): Promise<ethers.Signer> => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const ethereum = (window as any).ethereum;
+
+  if (!ethereum) {
+    throw Error(
+      "Missing or invalid Ethereum provider. Please install a Web3 wallet such as MetaMask."
+    );
+  }
+
+  await ethereum.request({ method: "eth_requestAccounts" });
+  const provider = new ethers.providers.Web3Provider(ethereum, "any");
+
+  return provider.getSigner();
+};