@waku/rln 0.1.8-e224c05.0 → 0.1.8-e800af3.0

package/dist/zerokit.js

@@ -1,6 +1,8 @@
 import * as zerokitRLN from "@waku/zerokit-rln-wasm";
-import { DEFAULT_RATE_LIMIT } from "./contract/constants.js";
+import { DEFAULT_RATE_LIMIT, RATE_LIMIT_PARAMS } from "./contract/constants.js";
 import { IdentityCredential } from "./identity.js";
+import { Proof, proofToBytes } from "./proof.js";
+import { BytesUtils, dateToEpoch, epochIntToBytes } from "./utils/index.js";
 export class Zerokit {
     zkRLN;
     witnessCalculator;
@@ -19,11 +21,105 @@ export class Zerokit {
     get rateLimit() {
         return this._rateLimit;
     }
+    generateIdentityCredentials() {
+        const memKeys = zerokitRLN.generateExtendedMembershipKey(this.zkRLN); // TODO: rename this function in zerokit rln-wasm
+        return IdentityCredential.fromBytes(memKeys);
+    }
     generateSeededIdentityCredential(seed) {
         const stringEncoder = new TextEncoder();
         const seedBytes = stringEncoder.encode(seed);
+        // TODO: rename this function in zerokit rln-wasm
         const memKeys = zerokitRLN.generateSeededExtendedMembershipKey(this.zkRLN, seedBytes);
         return IdentityCredential.fromBytes(memKeys);
     }
+    insertMember(idCommitment) {
+        zerokitRLN.insertMember(this.zkRLN, idCommitment);
+    }
+    insertMembers(index, ...idCommitments) {
+        // serializes a seq of IDCommitments to a byte seq
+        // the order of serialization is |id_commitment_len<8>|id_commitment<var>|
+        const idCommitmentLen = BytesUtils.writeUIntLE(new Uint8Array(8), idCommitments.length, 0, 8);
+        const idCommitmentBytes = BytesUtils.concatenate(idCommitmentLen, ...idCommitments);
+        zerokitRLN.setLeavesFrom(this.zkRLN, index, idCommitmentBytes);
+    }
+    deleteMember(index) {
+        zerokitRLN.deleteLeaf(this.zkRLN, index);
+    }
+    getMerkleRoot() {
+        return zerokitRLN.getRoot(this.zkRLN);
+    }
+    serializeMessage(uint8Msg, memIndex, epoch, idKey, rateLimit) {
+        // calculate message length
+        const msgLen = BytesUtils.writeUIntLE(new Uint8Array(8), uint8Msg.length, 0, 8);
+        const memIndexBytes = BytesUtils.writeUIntLE(new Uint8Array(8), memIndex, 0, 8);
+        const rateLimitBytes = BytesUtils.writeUIntLE(new Uint8Array(8), rateLimit ?? this.rateLimit, 0, 8);
+        // [ id_key<32> | id_index<8> | epoch<32> | signal_len<8> | signal<var> | rate_limit<8> ]
+        return BytesUtils.concatenate(idKey, memIndexBytes, epoch, msgLen, uint8Msg, rateLimitBytes);
+    }
+    async generateRLNProof(msg, index, epoch, idSecretHash, rateLimit) {
+        if (epoch === undefined) {
+            epoch = epochIntToBytes(dateToEpoch(new Date()));
+        }
+        else if (epoch instanceof Date) {
+            epoch = epochIntToBytes(dateToEpoch(epoch));
+        }
+        const effectiveRateLimit = rateLimit ?? this.rateLimit;
+        if (epoch.length !== 32)
+            throw new Error("invalid epoch");
+        if (idSecretHash.length !== 32)
+            throw new Error("invalid id secret hash");
+        if (index < 0)
+            throw new Error("index must be >= 0");
+        if (effectiveRateLimit < RATE_LIMIT_PARAMS.MIN_RATE ||
+            effectiveRateLimit > RATE_LIMIT_PARAMS.MAX_RATE) {
+            throw new Error(`Rate limit must be between ${RATE_LIMIT_PARAMS.MIN_RATE} and ${RATE_LIMIT_PARAMS.MAX_RATE}`);
+        }
+        const serialized_msg = this.serializeMessage(msg, index, epoch, idSecretHash, effectiveRateLimit);
+        const rlnWitness = zerokitRLN.getSerializedRLNWitness(this.zkRLN, serialized_msg);
+        const inputs = zerokitRLN.RLNWitnessToJson(this.zkRLN, rlnWitness);
+        const calculatedWitness = await this.witnessCalculator.calculateWitness(inputs, false);
+        const proofBytes = zerokitRLN.generate_rln_proof_with_witness(this.zkRLN, calculatedWitness, rlnWitness);
+        return new Proof(proofBytes);
+    }
+    verifyRLNProof(proof, msg, rateLimit) {
+        let pBytes;
+        if (proof instanceof Uint8Array) {
+            pBytes = proof;
+        }
+        else {
+            pBytes = proofToBytes(proof);
+        }
+        // calculate message length
+        const msgLen = BytesUtils.writeUIntLE(new Uint8Array(8), msg.length, 0, 8);
+        const rateLimitBytes = BytesUtils.writeUIntLE(new Uint8Array(8), rateLimit ?? this.rateLimit, 0, 8);
+        return zerokitRLN.verifyRLNProof(this.zkRLN, BytesUtils.concatenate(pBytes, msgLen, msg, rateLimitBytes));
+    }
+    verifyWithRoots(proof, msg, roots, rateLimit) {
+        let pBytes;
+        if (proof instanceof Uint8Array) {
+            pBytes = proof;
+        }
+        else {
+            pBytes = proofToBytes(proof);
+        }
+        // calculate message length
+        const msgLen = BytesUtils.writeUIntLE(new Uint8Array(8), msg.length, 0, 8);
+        const rateLimitBytes = BytesUtils.writeUIntLE(new Uint8Array(8), rateLimit ?? this.rateLimit, 0, 8);
+        const rootsBytes = BytesUtils.concatenate(...roots);
+        return zerokitRLN.verifyWithRoots(this.zkRLN, BytesUtils.concatenate(pBytes, msgLen, msg, rateLimitBytes), rootsBytes);
+    }
+    verifyWithNoRoot(proof, msg, rateLimit) {
+        let pBytes;
+        if (proof instanceof Uint8Array) {
+            pBytes = proof;
+        }
+        else {
+            pBytes = proofToBytes(proof);
+        }
+        // calculate message length
+        const msgLen = BytesUtils.writeUIntLE(new Uint8Array(8), msg.length, 0, 8);
+        const rateLimitBytes = BytesUtils.writeUIntLE(new Uint8Array(8), rateLimit ?? this.rateLimit, 0, 8);
+        return zerokitRLN.verifyWithRoots(this.zkRLN, BytesUtils.concatenate(pBytes, msgLen, msg, rateLimitBytes), new Uint8Array());
+    }
 }
 //# sourceMappingURL=zerokit.js.map

package/dist/zerokit.js.map

@@ -1 +1 @@
-{"version":3,"file":"zerokit.js","sourceRoot":"","sources":["../src/zerokit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,UAAU,MAAM,wBAAwB,CAAC;AAErD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAGnD,MAAM,OAAO,OAAO;IAEC;IACA;IACA;IAHnB,YACmB,KAAa,EACb,iBAAoC,EACpC,aAAqB,kBAAkB;QAFvC,UAAK,GAAL,KAAK,CAAQ;QACb,sBAAiB,GAAjB,iBAAiB,CAAmB;QACpC,eAAU,GAAV,UAAU,CAA6B;IACvD,CAAC;IAEJ,IAAW,QAAQ;QACjB,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,IAAW,oBAAoB;QAC7B,OAAO,IAAI,CAAC,iBAAiB,CAAC;IAChC,CAAC;IAED,IAAW,SAAS;QAClB,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAEM,gCAAgC,CAAC,IAAY;QAClD,MAAM,aAAa,GAAG,IAAI,WAAW,EAAE,CAAC;QACxC,MAAM,SAAS,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC7C,MAAM,OAAO,GAAG,UAAU,CAAC,mCAAmC,CAC5D,IAAI,CAAC,KAAK,EACV,SAAS,CACV,CAAC;QACF,OAAO,kBAAkB,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IAC/C,CAAC;CACF"}
+{"version":3,"file":"zerokit.js","sourceRoot":"","sources":["../src/zerokit.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1 +1 @@
-{"name":"@waku/rln","version":"0.1.8-e224c05.0","description":"RLN (Rate Limiting Nullifier) implementation for Waku","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"type":"module","homepage":"https://github.com/waku-org/js-waku/tree/master/packages/rln#readme","repository":{"type":"git","url":"https://github.com/waku-org/js-waku.git"},"bugs":{"url":"https://github.com/waku-org/js-waku/issues"},"license":"MIT OR Apache-2.0","keywords":["waku","rln","rate-limiting","privacy","web3"],"scripts":{"build":"run-s build:**","build:copy":"mkdir -p dist/resources && cp -r src/resources/* dist/resources/","build:esm":"tsc","build:bundle":"rollup --config rollup.config.js","fix":"run-s fix:*","fix:lint":"eslint src *.js --fix","check":"run-s check:*","check:tsc":"tsc -p tsconfig.dev.json","check:lint":"eslint \"src/!(resources)/**/*.{ts,js}\" *.js","check:spelling":"cspell \"{README.md,src/**/*.ts}\"","test":"NODE_ENV=test run-s test:*","test:browser":"karma start karma.conf.cjs","watch:build":"tsc -p tsconfig.json -w","watch:test":"mocha --watch","prepublish":"npm run build","reset-hard":"git clean -dfx -e .idea && git reset --hard && npm i && npm run build"},"engines":{"node":">=22"},"devDependencies":{"@rollup/plugin-commonjs":"^25.0.7","@rollup/plugin-json":"^6.0.0","@rollup/plugin-node-resolve":"^15.2.3","@types/chai":"^5.0.1","@types/chai-spies":"^1.0.6","@waku/interfaces":"0.0.33-e224c05.0","@types/deep-equal-in-any-order":"^1.0.4","@types/lodash":"^4.17.15","@types/sinon":"^17.0.3","@waku/build-utils":"^1.0.0","@waku/message-encryption":"0.0.36-e224c05.0","deep-equal-in-any-order":"^2.0.6","fast-check":"^3.23.2","rollup-plugin-copy":"^3.5.0"},"files":["dist","bundle","src/**/*.ts","!**/*.spec.*","!**/*.json","CHANGELOG.md","LICENSE","README.md"],"dependencies":{"@chainsafe/bls-keystore":"3.0.0","@waku/core":"0.0.38-e224c05.0","@waku/utils":"0.0.26-e224c05.0","@noble/hashes":"^1.2.0","@waku/zerokit-rln-wasm":"^0.2.1","ethereum-cryptography":"^3.1.0","ethers":"^5.7.2","lodash":"^4.17.21","uuid":"^11.0.5","chai":"^5.1.2","chai-as-promised":"^8.0.1","chai-spies":"^1.1.0","chai-subset":"^1.6.0","sinon":"^19.0.2"}}
+{"name":"@waku/rln","version":"0.1.8-e800af3.0","description":"RLN (Rate Limiting Nullifier) implementation for Waku","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"type":"module","homepage":"https://github.com/waku-org/js-waku/tree/master/packages/rln#readme","repository":{"type":"git","url":"https://github.com/waku-org/js-waku.git"},"bugs":{"url":"https://github.com/waku-org/js-waku/issues"},"license":"MIT OR Apache-2.0","keywords":["waku","rln","rate-limiting","privacy","web3"],"scripts":{"build":"run-s build:**","build:copy":"mkdir -p dist/resources && cp -r src/resources/* dist/resources/","build:esm":"tsc","build:bundle":"rollup --config rollup.config.js","fix":"run-s fix:*","fix:lint":"eslint src *.js --fix","check":"run-s check:*","check:tsc":"tsc -p tsconfig.dev.json","check:lint":"eslint \"src/!(resources)/**/*.{ts,js}\" *.js","check:spelling":"cspell \"{README.md,src/**/*.ts}\"","test":"NODE_ENV=test run-s test:*","test:browser":"karma start karma.conf.cjs","watch:build":"tsc -p tsconfig.json -w","watch:test":"mocha --watch","prepublish":"npm run build","reset-hard":"git clean -dfx -e .idea && git reset --hard && npm i && npm run build"},"engines":{"node":">=22"},"devDependencies":{"@rollup/plugin-commonjs":"^25.0.7","@rollup/plugin-json":"^6.0.0","@rollup/plugin-node-resolve":"^15.2.3","@types/chai":"^5.0.1","@types/chai-spies":"^1.0.6","@waku/interfaces":"0.0.33-e800af3.0","@types/deep-equal-in-any-order":"^1.0.4","@types/lodash":"^4.17.15","@types/sinon":"^17.0.3","@waku/build-utils":"^1.0.0","@waku/message-encryption":"0.0.36-e800af3.0","deep-equal-in-any-order":"^2.0.6","fast-check":"^3.23.2","rollup-plugin-copy":"^3.5.0"},"files":["dist","bundle","src/**/*.ts","!**/*.spec.*","!**/*.json","CHANGELOG.md","LICENSE","README.md"],"dependencies":{"@chainsafe/bls-keystore":"3.0.0","@waku/core":"0.0.38-e800af3.0","@waku/utils":"0.0.26-e800af3.0","@noble/hashes":"^1.2.0","@waku/zerokit-rln-wasm":"^0.0.13","ethereum-cryptography":"^3.1.0","ethers":"^5.7.2","lodash":"^4.17.21","uuid":"^11.0.5","chai":"^5.1.2","chai-as-promised":"^8.0.1","chai-spies":"^1.1.0","chai-subset":"^1.6.0","sinon":"^19.0.2"}}

package/src/codec.test-utils.ts

@@ -0,0 +1,88 @@
+import type { IProtoMessage } from "@waku/interfaces";
+import { createRoutingInfo } from "@waku/utils";
+import { expect } from "chai";
+
+import { createRLN } from "./create.js";
+import type { IdentityCredential } from "./identity.js";
+
+export interface TestRLNCodecSetup {
+  rlnInstance: any;
+  credential: IdentityCredential;
+  index: number;
+  payload: Uint8Array;
+}
+
+export const TEST_CONSTANTS = {
+  contentTopic: "/test/1/waku-message/utf8",
+  emptyPubsubTopic: "",
+  defaultIndex: 0,
+  defaultPayload: new Uint8Array([1, 2, 3, 4, 5]),
+  routingInfo: createRoutingInfo(
+    {
+      clusterId: 0,
+      numShardsInCluster: 2
+    },
+    { contentTopic: "/test/1/waku-message/utf8" }
+  )
+} as const;
+
+export const EMPTY_PROTO_MESSAGE = {
+  timestamp: undefined,
+  contentTopic: "",
+  ephemeral: undefined,
+  meta: undefined,
+  rateLimitProof: undefined,
+  version: undefined
+} as const;
+
+/**
+ * Creates a basic RLN setup for codec tests
+ */
+export async function createTestRLNCodecSetup(): Promise<TestRLNCodecSetup> {
+  const rlnInstance = await createRLN();
+  const credential = rlnInstance.zerokit.generateIdentityCredentials();
+  rlnInstance.zerokit.insertMember(credential.IDCommitment);
+
+  return {
+    rlnInstance,
+    credential,
+    index: TEST_CONSTANTS.defaultIndex,
+    payload: TEST_CONSTANTS.defaultPayload
+  };
+}
+
+/**
+ * Creates a meta setter function for testing
+ */
+export function createTestMetaSetter(): (
+  msg: IProtoMessage & { meta: undefined }
+) => Uint8Array {
+  return (msg: IProtoMessage & { meta: undefined }): Uint8Array => {
+    const buffer = new ArrayBuffer(4);
+    const view = new DataView(buffer);
+    view.setUint32(0, msg.payload.length, false);
+    return new Uint8Array(buffer);
+  };
+}
+
+/**
+ * Verifies common RLN message properties
+ */
+export function verifyRLNMessage(
+  msg: any,
+  payload: Uint8Array,
+  contentTopic: string,
+  version: number,
+  rlnInstance: any
+): void {
+  expect(msg.rateLimitProof).to.not.be.undefined;
+  expect(msg.verify([rlnInstance.zerokit.getMerkleRoot()])).to.be.true;
+  expect(msg.verifyNoRoot()).to.be.true;
+  expect(msg.epoch).to.not.be.undefined;
+  expect(msg.epoch).to.be.gt(0);
+
+  expect(msg.contentTopic).to.eq(contentTopic);
+  expect(msg.msg.version).to.eq(version);
+  expect(msg.payload).to.deep.eq(payload);
+  expect(msg.timestamp).to.not.be.undefined;
+}

package/src/codec.ts

@@ -0,0 +1,138 @@
+import type {
+  IDecodedMessage,
+  IDecoder,
+  IEncoder,
+  IMessage,
+  IProtoMessage,
+  IRateLimitProof,
+  IRoutingInfo
+} from "@waku/interfaces";
+import { Logger } from "@waku/utils";
+
+import type { IdentityCredential } from "./identity.js";
+import { RlnMessage, toRLNSignal } from "./message.js";
+import { RLNInstance } from "./rln.js";
+
+const log = new Logger("waku:rln:encoder");
+
+export class RLNEncoder implements IEncoder {
+  private readonly idSecretHash: Uint8Array;
+
+  public constructor(
+    private readonly encoder: IEncoder,
+    private readonly rlnInstance: RLNInstance,
+    private readonly index: number,
+    identityCredential: IdentityCredential
+  ) {
+    if (index < 0) throw new Error("Invalid membership index");
+    this.idSecretHash = identityCredential.IDSecretHash;
+  }
+
+  public async toWire(message: IMessage): Promise<Uint8Array | undefined> {
+    message.rateLimitProof = await this.generateProof(message);
+    log.info("Proof generated", message.rateLimitProof);
+    return this.encoder.toWire(message);
+  }
+
+  public async toProtoObj(
+    message: IMessage
+  ): Promise<IProtoMessage | undefined> {
+    const protoMessage = await this.encoder.toProtoObj(message);
+    if (!protoMessage) return;
+
+    protoMessage.contentTopic = this.contentTopic;
+    protoMessage.rateLimitProof = await this.generateProof(message);
+    log.info("Proof generated", protoMessage.rateLimitProof);
+    return protoMessage;
+  }
+
+  private async generateProof(message: IMessage): Promise<IRateLimitProof> {
+    const signal = toRLNSignal(this.contentTopic, message);
+    return this.rlnInstance.zerokit.generateRLNProof(
+      signal,
+      this.index,
+      message.timestamp,
+      this.idSecretHash
+    );
+  }
+
+  public get pubsubTopic(): string {
+    return this.encoder.pubsubTopic;
+  }
+
+  public get routingInfo(): IRoutingInfo {
+    return this.encoder.routingInfo;
+  }
+
+  public get contentTopic(): string {
+    return this.encoder.contentTopic;
+  }
+
+  public get ephemeral(): boolean {
+    return this.encoder.ephemeral;
+  }
+}
+
+type RLNEncoderOptions = {
+  encoder: IEncoder;
+  rlnInstance: RLNInstance;
+  index: number;
+  credential: IdentityCredential;
+};
+
+export const createRLNEncoder = (options: RLNEncoderOptions): RLNEncoder => {
+  return new RLNEncoder(
+    options.encoder,
+    options.rlnInstance,
+    options.index,
+    options.credential
+  );
+};
+
+export class RLNDecoder<T extends IDecodedMessage>
+  implements IDecoder<RlnMessage<T>>
+{
+  public constructor(
+    private readonly rlnInstance: RLNInstance,
+    private readonly decoder: IDecoder<T>
+  ) {}
+
+  public get pubsubTopic(): string {
+    return this.decoder.pubsubTopic;
+  }
+
+  public get contentTopic(): string {
+    return this.decoder.contentTopic;
+  }
+
+  public fromWireToProtoObj(
+    bytes: Uint8Array
+  ): Promise<IProtoMessage | undefined> {
+    const protoMessage = this.decoder.fromWireToProtoObj(bytes);
+    log.info("Message decoded", protoMessage);
+    return Promise.resolve(protoMessage);
+  }
+
+  public async fromProtoObj(
+    pubsubTopic: string,
+    proto: IProtoMessage
+  ): Promise<RlnMessage<T> | undefined> {
+    const msg: T | undefined = await this.decoder.fromProtoObj(
+      pubsubTopic,
+      proto
+    );
+    if (!msg) return;
+    return new RlnMessage(this.rlnInstance, msg, proto.rateLimitProof);
+  }
+}
+
+type RLNDecoderOptions<T extends IDecodedMessage> = {
+  decoder: IDecoder<T>;
+  rlnInstance: RLNInstance;
+};
+
+export const createRLNDecoder = <T extends IDecodedMessage>(
+  options: RLNDecoderOptions<T>
+): RLNDecoder<T> => {
+  return new RLNDecoder(options.rlnInstance, options.decoder);
+};

package/src/contract/constants.ts

@@ -19,16 +19,26 @@ export const PRICE_CALCULATOR_CONTRACT = {
  * @see https://github.com/waku-org/specs/blob/master/standards/core/rln-contract.md#implementation-suggestions
  */
 export const RATE_LIMIT_TIERS = {
-  STANDARD: 300,
-  MAX: 600
+  LOW: 20, // Suggested minimum rate - 20 messages per epoch
+  MEDIUM: 200,
+  HIGH: 600 // Suggested maximum rate - 600 messages per epoch
 } as const;
 
 // Global rate limit parameters
 export const RATE_LIMIT_PARAMS = {
-  MIN_RATE: RATE_LIMIT_TIERS.STANDARD,
-  MAX_RATE: RATE_LIMIT_TIERS.MAX,
-  MAX_TOTAL_RATE: 160_000,
-  EPOCH_LENGTH: 600
+  MIN_RATE: RATE_LIMIT_TIERS.LOW,
+  MAX_RATE: RATE_LIMIT_TIERS.HIGH,
+  MAX_TOTAL_RATE: 160_000, // Maximum total rate limit across all memberships
+  EPOCH_LENGTH: 600 // Epoch length in seconds (10 minutes)
 } as const;
 
+/**
+ * Default Q value for the RLN contract
+ * This is the upper bound for the ID commitment
+ * @see https://github.com/waku-org/specs/blob/master/standards/core/rln-contract.md#implementation-suggestions
+ */
+export const RLN_Q = BigInt(
+  "21888242871839275222246405745257275088548364400416034343698204186575808495617"
+);
+
 export const DEFAULT_RATE_LIMIT = RATE_LIMIT_PARAMS.MAX_RATE;

package/src/contract/index.ts

@@ -1,2 +1,3 @@
+export { RLNContract } from "./rln_contract.js";
 export * from "./constants.js";
 export * from "./types.js";

package/src/contract/rln_base_contract.ts

@@ -3,6 +3,7 @@ import { ethers } from "ethers";
 
 import { IdentityCredential } from "../identity.js";
 import { DecryptedCredentials } from "../keystore/types.js";
+import { BytesUtils } from "../utils/bytes.js";
 
 import { RLN_ABI } from "./abi/rln.js";
 import {
@@ -631,7 +632,7 @@ export class RLNBaseContract {
           permit.v,
           permit.r,
           permit.s,
-          identity.IDCommitmentBigInt,
+          BytesUtils.buildBigIntFromUint8ArrayBE(identity.IDCommitment),
           this.rateLimit,
           idCommitmentsToErase.map((id) => ethers.BigNumber.from(id))
         );

package/src/contract/rln_contract.ts

@@ -0,0 +1,147 @@
+import { Logger } from "@waku/utils";
+import { hexToBytes } from "@waku/utils/bytes";
+import { ethers } from "ethers";
+
+import type { RLNInstance } from "../rln.js";
+import { MerkleRootTracker } from "../root_tracker.js";
+import { BytesUtils } from "../utils/bytes.js";
+
+import { RLNBaseContract } from "./rln_base_contract.js";
+import { RLNContractInitOptions } from "./types.js";
+
+const log = new Logger("waku:rln:contract");
+
+export class RLNContract extends RLNBaseContract {
+  private instance: RLNInstance;
+  private merkleRootTracker: MerkleRootTracker;
+
+  /**
+   * Asynchronous initializer for RLNContract.
+   * Allows injecting a mocked contract for testing purposes.
+   */
+  public static async init(
+    rlnInstance: RLNInstance,
+    options: RLNContractInitOptions
+  ): Promise<RLNContract> {
+    const rlnContract = new RLNContract(rlnInstance, options);
+
+    return rlnContract;
+  }
+
+  private constructor(
+    rlnInstance: RLNInstance,
+    options: RLNContractInitOptions
+  ) {
+    super(options);
+
+    this.instance = rlnInstance;
+
+    const initialRoot = rlnInstance.zerokit.getMerkleRoot();
+    this.merkleRootTracker = new MerkleRootTracker(5, initialRoot);
+  }
+
+  public override processEvents(events: ethers.Event[]): void {
+    const toRemoveTable = new Map<number, number[]>();
+    const toInsertTable = new Map<number, ethers.Event[]>();
+
+    events.forEach((evt) => {
+      if (!evt.args) {
+        return;
+      }
+
+      if (
+        evt.event === "MembershipErased" ||
+        evt.event === "MembershipExpired"
+      ) {
+        let index = evt.args.index;
+
+        if (!index) {
+          return;
+        }
+
+        if (typeof index === "number" || typeof index === "string") {
+          index = ethers.BigNumber.from(index);
+        } else {
+          log.error("Index is not a number or string", {
+            index,
+            event: evt
+          });
+          return;
+        }
+
+        const toRemoveVal = toRemoveTable.get(evt.blockNumber);
+        if (toRemoveVal != undefined) {
+          toRemoveVal.push(index.toNumber());
+          toRemoveTable.set(evt.blockNumber, toRemoveVal);
+        } else {
+          toRemoveTable.set(evt.blockNumber, [index.toNumber()]);
+        }
+      } else if (evt.event === "MembershipRegistered") {
+        let eventsPerBlock = toInsertTable.get(evt.blockNumber);
+        if (eventsPerBlock == undefined) {
+          eventsPerBlock = [];
+        }
+
+        eventsPerBlock.push(evt);
+        toInsertTable.set(evt.blockNumber, eventsPerBlock);
+      }
+    });
+
+    this.removeMembers(this.instance, toRemoveTable);
+    this.insertMembers(this.instance, toInsertTable);
+  }
+
+  private insertMembers(
+    rlnInstance: RLNInstance,
+    toInsert: Map<number, ethers.Event[]>
+  ): void {
+    toInsert.forEach((events: ethers.Event[], blockNumber: number) => {
+      events.forEach((evt) => {
+        if (!evt.args) return;
+
+        const _idCommitment = evt.args.idCommitment as string;
+        let index = evt.args.index;
+
+        if (!_idCommitment || !index) {
+          return;
+        }
+
+        if (typeof index === "number" || typeof index === "string") {
+          index = ethers.BigNumber.from(index);
+        }
+
+        const idCommitment = BytesUtils.zeroPadLE(
+          hexToBytes(_idCommitment),
+          32
+        );
+        rlnInstance.zerokit.insertMember(idCommitment);
+
+        const numericIndex = index.toNumber();
+        this._members.set(numericIndex, {
+          index,
+          idCommitment: _idCommitment
+        });
+      });
+
+      const currentRoot = rlnInstance.zerokit.getMerkleRoot();
+      this.merkleRootTracker.pushRoot(blockNumber, currentRoot);
+    });
+  }
+
+  private removeMembers(
+    rlnInstance: RLNInstance,
+    toRemove: Map<number, number[]>
+  ): void {
+    const removeDescending = new Map([...toRemove].reverse());
+    removeDescending.forEach((indexes: number[], blockNumber: number) => {
+      indexes.forEach((index) => {
+        if (this._members.has(index)) {
+          this._members.delete(index);
+          rlnInstance.zerokit.deleteMember(index);
+        }
+      });
+
+      this.merkleRootTracker.backFill(blockNumber);
+    });
+  }
+}

package/src/contract/test_setup.ts

@@ -0,0 +1,86 @@
+import { hexToBytes } from "@waku/utils/bytes";
+import { ethers } from "ethers";
+import sinon from "sinon";
+
+import { createRLN } from "../create.js";
+import type { IdentityCredential } from "../identity.js";
+
+import { DEFAULT_RATE_LIMIT, RLN_CONTRACT } from "./constants.js";
+import { RLNContract } from "./rln_contract.js";
+
+export interface TestRLNInstance {
+  rlnInstance: any;
+  identity: IdentityCredential;
+  insertMemberSpy: sinon.SinonStub;
+}
+
+/**
+ * Creates a test RLN instance with basic setup
+ */
+export async function createTestRLNInstance(): Promise<TestRLNInstance> {
+  const rlnInstance = await createRLN();
+  const insertMemberSpy = sinon.stub();
+  rlnInstance.zerokit.insertMember = insertMemberSpy;
+
+  const mockSignature =
+    "0xdeb8a6b00a8e404deb1f52d3aa72ed7f60a2ff4484c737eedaef18a0aacb2dfb4d5d74ac39bb71fa358cf2eb390565a35b026cc6272f2010d4351e17670311c21c";
+  const identity =
+    rlnInstance.zerokit.generateSeededIdentityCredential(mockSignature);
+
+  return {
+    rlnInstance,
+    identity,
+    insertMemberSpy
+  };
+}
+
+/**
+ * Initializes an RLN contract with the given registry contract
+ */
+export async function initializeRLNContract(
+  rlnInstance: any,
+  mockedRegistryContract: ethers.Contract
+): Promise<RLNContract> {
+  const provider = new ethers.providers.JsonRpcProvider();
+  const voidSigner = new ethers.VoidSigner(RLN_CONTRACT.address, provider);
+
+  const originalRegister = mockedRegistryContract.register;
+  (mockedRegistryContract as any).register = function (...args: any[]) {
+    const result = originalRegister.apply(this, args);
+
+    if (args[0] && rlnInstance.zerokit) {
+      const idCommitmentBigInt = args[0];
+      const idCommitmentHex =
+        "0x" + idCommitmentBigInt.toString(16).padStart(64, "0");
+      const idCommitment = ethers.utils.zeroPad(
+        hexToBytes(idCommitmentHex),
+        32
+      );
+      rlnInstance.zerokit.insertMember(idCommitment);
+    }
+
+    return result;
+  };
+
+  const contract = await RLNContract.init(rlnInstance, {
+    address: RLN_CONTRACT.address,
+    signer: voidSigner,
+    rateLimit: DEFAULT_RATE_LIMIT,
+    contract: mockedRegistryContract
+  });
+
+  return contract;
+}
+
+/**
+ * Common test message data
+ */
+export const TEST_DATA = {
+  contentTopic: "/test/1/waku-message/utf8",
+  emptyPubsubTopic: "",
+  testMessage: Uint8Array.from(
+    "Hello World".split("").map((x) => x.charCodeAt(0))
+  ),
+  mockSignature:
+    "0xdeb8a6b00a8e404deb1f52d3aa72ed7f60a2ff4484c737eedaef18a0aacb2dfb4d5d74ac39bb71fa358cf2eb390565a35b026cc6272f2010d4351e17670311c21c"
+};