@gurge/sdk 0.3.142 → 0.3.151

package/common/src/data-structures/crypto-keys/keys.d.ts

@@ -0,0 +1,117 @@
+import { JubPoint } from '../../crypto/babyJub';
+import { AttachableMemoryCacheDevice } from '../cacheDevices/AttachableMemoryCacheDevice';
+export declare const stealthPairCacheDevice: AttachableMemoryCacheDevice<{
+    H0: [bigint, bigint];
+    H1: [bigint, bigint];
+}>;
+export interface EncryptionKeyPair {
+    privateKey: string;
+    publicKey: string;
+}
+export declare const EncryptionKeyPairDefaultValue: EncryptionKeyPair;
+export declare class UserKeys {
+    private signature;
+    private nullifyingKey;
+    private readonly PREFIX_FOR_SPENDING_PAIR;
+    constructor(_signature?: string, _nullifyingKey?: string);
+    getSignature(): string;
+    hasSignature(): boolean;
+    setSignature(_signature: string): void;
+    private requireSignature;
+    private requireKeyMaterial;
+    verifyTronMessage(signingMessage: string, signerAddress: string): boolean;
+    /**
+     * get shielded private key from message signature used to login to the application,
+     * this private key is used to generate encryption keypairs as well as public key
+     * @retuns 0x-prefixed shielded private key
+     */
+    getShieldedPrivateKey: () => string;
+    /**
+     * getShieldedPrivateKey() is constrained to < 2^250 to match the circuit's nullifyingPrivateKey
+     * range check, so it's no longer 32 bytes and can't be used directly as raw key material for
+     * libraries that require a full-length seed.
+     * This re-expands it back to a full 32-byte seed via keccak256 for those use sites.
+     * @returns 32-byte 0x-prefixed seed
+     */
+    private getShieldedPrivateKeySeed;
+    /**
+     * generate shielded public key from private key
+     * @param privateKey the key used to generate the shielded public key, this should be the signature
+     * that the user provided
+     * @retuns shielded public key in hexstring with 0x prefixed
+     */
+    getShieldedPublicKey: () => string;
+    /**
+     * derive the EdDSA-Poseidon BabyJubJub public key for the spending private key. This must match
+     * the key that `signEddsa` (circomlib's signPoseidon) signs with, i.e. the scalar is derived from
+     * blake512(prv) + clamping, not from privSpendingKey directly.
+     */
+    getSpendingKeyPair: () => {
+        privSpendingKey: string;
+        pubSpendingBJJPoint: JubPoint;
+    };
+    /**
+     * EdDSA-Poseidon sign a message (a circom field element as bigint) using the shielded private key
+     * as the EdDSA secret. Returns { R8, S } with R8 as a JubPoint and S as a bigint scalar.
+     */
+    signEddsa: (message: bigint) => {
+        R8: JubPoint;
+        S: bigint;
+    };
+    /**
+     * Currently used for creating shielded private keys for deposit UTXOs, which are encrypted and sent to enclave for private send
+     * @param nonce Used to deterministically generate new shielded private key
+     * @returns new shielded private key in hexstring with 0x prefixed
+     */
+    getShieldedPrivateKeyFromNonce: (nonce: bigint) => string;
+    getClaimableSignatureFromNonce: (nonce: bigint) => string;
+    /**
+     * deterministically derive the user's NEAR Intents account id from the shielded private key.
+     * The account id is the NEAR implicit account (lowercase hex of the ed25519 public key) of the
+     * same keypair returned by getDerivedSolanaPublicKey. Used as a private cross-chain refund
+     * destination so refunds never expose the user's public main wallet.
+     */
+    getNearIntentsAccountId: () => string;
+    /**
+     * deterministically derive the NEAR Intents signing key from the shielded private key,
+     * formatted as a near-api-js KeyPair string ("ed25519:<base58 secret>"). Pairs with
+     * getNearIntentsAccountId() and is used client-side to authorize claiming cross-chain
+     * bridge refunds back out of the user's Intents account.
+     */
+    getNearIntentsKeyPairString: () => string;
+    /**
+     * generate access token, this accessKey is what should be sent to the server for signing
+     * @returns accessKey in hexstring with 0x prefixed
+     */
+    getSignerPrivateKeyFromNonce: (walletNonce: bigint) => string;
+    getSignerSolanaPrivateKeyFromNonce: (walletNonce: bigint) => string;
+    verifyMessage(signingMessage: string): string;
+    verifySolanaMessage(signingMessage: string, signerPublicKey: string): boolean;
+    static getRandomizedStealthPair: (s: bigint, privateKey: string) => {
+        H0: [bigint, bigint];
+        H1: [bigint, bigint];
+    };
+    static getH1FromH0: (H0: JubPoint, privateKey: string) => JubPoint;
+    static verifyStealthPair: (H0: JubPoint, H1: JubPoint, privateKey: string, onlyYCheck?: boolean) => boolean;
+    static getStealthAddress: (H0: JubPoint, nullifyingPrivateKey: string, spendingPublicKey?: bigint[]) => string;
+    static findCorrectRandomization(initialRandomization: bigint, privateKey?: string): bigint;
+    static getH0FromRandomization: (randomization: bigint) => JubPoint;
+    static findH0(randomization: bigint, privateKey: string | undefined): JubPoint | undefined;
+    /**
+     * generate private and public keypair
+     * @param privateKey seed to use to deterministically generate key, any DataHexString;
+     * since nullifyingKey/shieldedPrivateKey are now constrained to < 2^250 (not 32 bytes),
+     * this re-expands the input via keccak256 to get a full 32-byte seed for sodium
+     */
+    static getEncryptionKeyPair: (privateKey: string) => EncryptionKeyPair;
+    /**
+     * generate access token, this accessKey is what should be sent to the server for signing
+     * @returns accessKey in hexstring with 0x prefixed
+     */
+    getAccessKey: () => string;
+    /**
+     * generate backend token, which is used for access control on backend
+     * @returns accessKey in hexstring with 0x prefixed
+     */
+    getBackendToken: () => string;
+}

package/common/src/data-structures/crypto-keys/keys.mjs

@@ -1,27 +1,29 @@
-import { CIRCOM_P as e } from "../../constants/protocol.constants.mjs";
-import { poseidonHash as t } from "../../crypto/poseidon.mjs";
-import { babyJubInstance as n } from "../../crypto/babyJub.mjs";
-import { eddsaInstance as r } from "../../crypto/eddsa.mjs";
-import { AttachableMemoryCacheDevice as i } from "../cacheDevices/AttachableMemoryCacheDevice.mjs";
-import { getCircomSign as a } from "./keyUtils.mjs";
-import { ethers as o } from "ethers";
-import { Keypair as s, PublicKey as c } from "@solana/web3.js";
-import l from "bs58";
-import u from "libsodium-wrappers";
-import d from "tweetnacl";
-import { Trx as f } from "tronweb";
+import { CIRCOM_P as e, NULLIFYING_PRIVATE_KEY_MOD as t } from "../../constants/protocol.constants.mjs";
+import { poseidonHash as n } from "../../crypto/poseidon.mjs";
+import { babyJubInstance as r } from "../../crypto/babyJub.mjs";
+import { eddsaInstance as i } from "../../crypto/eddsa.mjs";
+import { AttachableMemoryCacheDevice as a } from "../cacheDevices/AttachableMemoryCacheDevice.mjs";
+import { getCircomSign as o } from "./keyUtils.mjs";
+import { ethers as s } from "ethers";
+import { Keypair as c, PublicKey as l } from "@solana/web3.js";
+import u from "bs58";
+import d from "libsodium-wrappers";
+import f from "tweetnacl";
+import { Trx as p } from "tronweb";
 //#region libs/shared/common/src/data-structures/crypto-keys/keys.ts
-var p = new i(), m = new i(), h = new i(), g = class {
+var m = new a(), h = class {
 	signature;
 	nullifyingKey;
 	PREFIX_FOR_SPENDING_PAIR = "1";
-	PREFIX_FOR_NULLIFYING_PAIR = "2";
 	constructor(e, t) {
 		this.signature = e, this.nullifyingKey = t;
 	}
 	getSignature() {
 		return this.requireSignature(), this.signature;
 	}
+	hasSignature() {
+		return !!this.signature;
+	}
 	setSignature(e) {
 		this.signature = e;
 	}
@@ -32,21 +34,28 @@ var p = new i(), m = new i(), h = new i(), g = class {
 		if (!this.signature && !this.nullifyingKey) throw Error("No signature or private key provided");
 	}
 	verifyTronMessage(e, t) {
-		return this.requireSignature(), t === f.verifyMessageV2(e, this.signature);
+		return this.requireSignature(), t === p.verifyMessageV2(e, this.signature);
 	}
-	getShieldedPrivateKey = () => (this.requireKeyMaterial(), this.nullifyingKey ||= o.keccak256(this.signature), this.nullifyingKey);
-	getShieldedPublicKey = () => (this.requireKeyMaterial(), t(this.getShieldedPrivateKey()));
+	getShieldedPrivateKey = () => {
+		if (this.requireKeyMaterial(), !this.nullifyingKey) {
+			let e = BigInt(n(this.signature));
+			this.nullifyingKey = s.toBeHex(e % t);
+		}
+		return this.nullifyingKey;
+	};
+	getShieldedPrivateKeySeed = () => s.keccak256(this.getShieldedPrivateKey());
+	getShieldedPublicKey = () => (this.requireKeyMaterial(), n(this.getShieldedPrivateKey()));
 	getSpendingKeyPair = () => {
 		this.requireSignature();
-		let e = r(), i = n(), a = t(this.PREFIX_FOR_SPENDING_PAIR, this.getSignature()), s = Buffer.from(o.getBytes(a)), c = e.prv2pub(s);
+		let e = i(), t = r(), a = n(this.PREFIX_FOR_SPENDING_PAIR, this.getSignature()), o = Buffer.from(s.getBytes(a)), c = e.prv2pub(o);
 		return {
 			privSpendingKey: a,
-			pubSpendingBJJPoint: [BigInt(i.F.toString(c[0])), BigInt(i.F.toString(c[1]))]
+			pubSpendingBJJPoint: [BigInt(t.F.toString(c[0])), BigInt(t.F.toString(c[1]))]
 		};
 	};
 	signEddsa = (e) => {
 		this.requireSignature();
-		let t = n(), i = r(), a = Buffer.from(o.getBytes(this.getSpendingKeyPair().privSpendingKey)), s = t.F.e(e), c = i.signPoseidon(a, s);
+		let t = r(), n = i(), a = Buffer.from(s.getBytes(this.getSpendingKeyPair().privSpendingKey)), o = t.F.e(e), c = n.signPoseidon(a, o);
 		return {
 			R8: [BigInt(t.F.toString(c.R8[0])), BigInt(t.F.toString(c.R8[1]))],
 			S: BigInt(c.S)
@@ -54,96 +63,72 @@ var p = new i(), m = new i(), h = new i(), g = class {
 	};
 	getShieldedPrivateKeyFromNonce = (e) => {
 		this.requireKeyMaterial();
-		let n = t(e, this.getShieldedPrivateKey(), this.getShieldedPublicKey());
-		return o.keccak256(o.toUtf8Bytes(`hinkal-offchain-shielded-key:${n}`));
+		let t = n(e, this.getShieldedPrivateKey(), this.getShieldedPublicKey());
+		return s.keccak256(s.toUtf8Bytes(`hinkal-offchain-shielded-key:${t}`));
 	};
 	getClaimableSignatureFromNonce = (e) => {
 		this.requireKeyMaterial();
-		let n = t(e, this.getShieldedPrivateKey(), this.getShieldedPublicKey());
-		return o.keccak256(o.toUtf8Bytes(`hinkal-claimable-utxo-signature:${n}`));
+		let t = n(e, this.getShieldedPrivateKey(), this.getShieldedPublicKey());
+		return s.keccak256(s.toUtf8Bytes(`hinkal-claimable-utxo-signature:${t}`));
 	};
-	getDerivedEthereumAddress = () => (this.requireKeyMaterial(), new o.Wallet(this.getShieldedPrivateKey()).address);
-	getDerivedSolanaPublicKey = () => (this.requireKeyMaterial(), s.fromSeed(o.getBytes(this.getShieldedPrivateKey())).publicKey.toBase58());
 	getNearIntentsAccountId = () => {
 		this.requireKeyMaterial();
-		let e = s.fromSeed(o.getBytes(this.getShieldedPrivateKey()));
-		return o.hexlify(e.publicKey.toBytes()).slice(2);
+		let e = c.fromSeed(s.getBytes(this.getShieldedPrivateKeySeed()));
+		return s.hexlify(e.publicKey.toBytes()).slice(2);
 	};
 	getNearIntentsKeyPairString = () => {
 		this.requireKeyMaterial();
-		let e = s.fromSeed(o.getBytes(this.getShieldedPrivateKey()));
-		return `ed25519:${l.encode(e.secretKey)}`;
+		let e = c.fromSeed(s.getBytes(this.getShieldedPrivateKeySeed()));
+		return `ed25519:${u.encode(e.secretKey)}`;
 	};
 	getSignerPrivateKeyFromNonce = (e) => {
 		this.requireKeyMaterial();
-		let n = t(e, this.getShieldedPrivateKey(), this.getShieldedPublicKey());
-		return o.keccak256(o.toUtf8Bytes(n));
+		let t = n(e, this.getShieldedPrivateKey(), this.getShieldedPublicKey());
+		return s.keccak256(s.toUtf8Bytes(t));
 	};
 	getSignerSolanaPrivateKeyFromNonce = (e) => {
-		let t = this.getSignerPrivateKeyFromNonce(e), n = o.getBytes(t), r = s.fromSeed(n);
-		return l.encode(r.secretKey);
+		let t = this.getSignerPrivateKeyFromNonce(e), n = s.getBytes(t), r = c.fromSeed(n);
+		return u.encode(r.secretKey);
 	};
 	verifyMessage(e) {
-		return this.requireSignature(), o.verifyMessage(e, this.signature);
+		return this.requireSignature(), s.verifyMessage(e, this.signature);
 	}
 	verifySolanaMessage(e, t) {
 		this.requireSignature();
-		let n = new TextEncoder().encode(e), r = o.getBytes(this.signature), i = new c(t).toBytes();
-		return d.sign.detached.verify(n, r, i);
+		let n = new TextEncoder().encode(e), r = s.getBytes(this.signature), i = new l(t).toBytes();
+		return f.sign.detached.verify(n, r, i);
 	}
-	static getRandomizedStealthPairOld = m.attach((t, r) => {
-		let i = n(), a = t * (BigInt(r) % e) % e, o = i.mulPointEscalar(i.Base8, t), s = i.mulPointEscalar(i.Base8, a);
-		return {
-			H0: [BigInt(i.F.toString(o[0])), BigInt(i.F.toString(o[1]))],
-			H1: [BigInt(i.F.toString(s[0])), BigInt(i.F.toString(s[1]))]
-		};
-	});
-	static getRandomizedStealthPair = p.attach((t, r) => {
-		let i = n(), a = BigInt(r) % e, o = i.mulPointEscalar(i.Base8, t), s = i.mulPointEscalar(o, a);
+	static getRandomizedStealthPair = m.attach((e, t) => {
+		let n = r(), i = n.mulPointEscalar(n.Base8, e), a = n.mulPointEscalar(i, BigInt(t));
 		return {
-			H0: [BigInt(i.F.toString(o[0])), BigInt(i.F.toString(o[1]))],
-			H1: [BigInt(i.F.toString(s[0])), BigInt(i.F.toString(s[1]))]
+			H0: [BigInt(n.F.toString(i[0])), BigInt(n.F.toString(i[1]))],
+			H1: [BigInt(n.F.toString(a[0])), BigInt(n.F.toString(a[1]))]
 		};
 	});
-	static getStealthAddressCompressedPoints = (e, t) => {
-		let { H0: n, H1: r } = this.getRandomizedStealthPairOld(e, t), [i, o] = [n, r].map((e) => BigInt(e[1]) + 2n ** 255n * a(e[0]));
-		return {
-			h0: i,
-			h1: o
-		};
-	};
-	static checkSignature = (e, t, n, r) => {
-		let { h0: i, h1: a } = this.getStealthAddressCompressedPoints(e, r);
-		return t === i && n === a;
-	};
-	static getStealthAddress = h.attach((e, n) => {
-		let { H0: r, H1: i } = this.getRandomizedStealthPairOld(e, n);
-		return t(2n * a(r[0]) + a(i[0]), r[1], i[1]);
-	});
-	static getH1FromH0 = (t, r) => {
-		let i = n(), a = BigInt(r) % e, o = [i.F.e(t[0]), i.F.e(t[1])], s = i.mulPointEscalar(o, a);
-		return [BigInt(i.F.toString(s[0])), BigInt(i.F.toString(s[1]))];
+	static getH1FromH0 = (e, t) => {
+		let n = r(), i = [n.F.e(e[0]), n.F.e(e[1])], a = n.mulPointEscalar(i, BigInt(t));
+		return [BigInt(n.F.toString(a[0])), BigInt(n.F.toString(a[1]))];
 	};
 	static verifyStealthPair = (e, t, n, r = !0) => {
 		let i = this.getH1FromH0(e, n);
 		return r ? i[1] === t[1] : i === t;
 	};
-	static getStealthAddressNewStyle = (e, n, r) => {
+	static getStealthAddress = (e, t, r) => {
 		if (r?.length !== 2) throw Error("Spending public key must be an array of 2 elements");
-		let i = this.getH1FromH0(e, n);
-		return t(2n * a(e[0]) + a(i[0]), e[1], i[1], r[0], r[1], n);
+		let i = this.getH1FromH0(e, t);
+		return n(2n * o(e[0]) + o(i[0]), e[1], i[1], r[0], r[1], t);
 	};
 	static findCorrectRandomization(t, n) {
 		if (!n) throw Error("No Private Shielded Key Provided");
-		let r = BigInt(n) % e, i, a, o = 0n;
+		let r = BigInt(n), i, a, o = 0n;
 		do
 			i = t * 10n ** o % e, a = i * r % e, o += 1n;
-		while (a >= 2n ** 253n || i >= 2n ** 253n);
+		while (a >= 2n ** 250n || i >= 2n ** 250n);
 		return i;
 	}
 	static getH0FromRandomization = (e) => {
-		let t = n(), r = t.mulPointEscalar(t.Base8, e);
-		return [BigInt(t.F.toString(r[0])), BigInt(t.F.toString(r[1]))];
+		let t = r(), n = t.mulPointEscalar(t.Base8, e);
+		return [BigInt(t.F.toString(n[0])), BigInt(t.F.toString(n[1]))];
 	};
 	static findH0(e, t) {
 		if (!t) return;
@@ -151,14 +136,14 @@ var p = new i(), m = new i(), h = new i(), g = class {
 		return n;
 	}
 	static getEncryptionKeyPair = (e) => {
-		let t = u.crypto_box_seed_keypair(o.getBytes(e));
+		let t = d.crypto_box_seed_keypair(s.getBytes(s.keccak256(e)));
 		return {
-			privateKey: o.hexlify(t.privateKey),
-			publicKey: o.hexlify(t.publicKey)
+			privateKey: s.hexlify(t.privateKey),
+			publicKey: s.hexlify(t.publicKey)
 		};
 	};
-	getAccessKey = () => (this.requireKeyMaterial(), t(this.getShieldedPrivateKey(), this.getShieldedPublicKey()));
-	getBackendToken = () => (this.requireKeyMaterial(), t(this.getAccessKey(), this.getShieldedPublicKey()));
+	getAccessKey = () => (this.requireKeyMaterial(), n(this.getShieldedPrivateKey(), this.getShieldedPublicKey()));
+	getBackendToken = () => (this.requireKeyMaterial(), n(this.getAccessKey(), this.getShieldedPublicKey()));
 };
 //#endregion
-export { g as UserKeys, h as stealthAddressCacheDevice, p as stealthPairCacheDevice, m as stealthPairOldCacheDevice };
+export { h as UserKeys, m as stealthPairCacheDevice };

package/common/src/data-structures/custom-token-registry/CustomTokenRegistry.d.ts

@@ -0,0 +1,12 @@
+import { ERC20Token } from '../../types';
+declare class CustomTokenRegistry {
+    tokenRegistry: ERC20Token[];
+    constructor();
+    setTokensFromCache(newTokenRegistries: ERC20Token[]): void;
+    getCustomTokens(chainId: number): ERC20Token[];
+    tokenExists(registry: ERC20Token[], tokenToCheck: ERC20Token): ERC20Token | undefined;
+    addCustomToken(token: ERC20Token): void;
+    removeCustomToken(tokenToRemove: ERC20Token): void;
+}
+export declare const customTokenRegistry: CustomTokenRegistry;
+export {};

package/common/src/data-structures/event-service/evm/AbstractCommitmentsSnapshotService.d.ts

@@ -0,0 +1,34 @@
+import { MerkleTree, MerkleTreeJson } from '../../merkle-tree';
+import { CommitmentEvent, EncryptedOutputWithCommitment, EncryptedOutputWithSign } from '../../../types';
+import { AbstractSnapshotService, Snapshot } from './AbstractSnapshotService';
+import { BlockchainEventEmitter } from './BlockchainEventEmitter';
+import { BlockchainEvent } from '../../BlockchainEvent/BlockchainEvent';
+export type CommitmentsSnapshotPayload = {
+    readonly merkleTree: MerkleTree<bigint>;
+    readonly encryptedOutputs: EncryptedOutputWithSign[];
+    readonly encryptedOutputsByCommitment: Map<bigint, string>;
+};
+export type CommitmentsSerializedSnapshot = {
+    latestBlockNumber?: number;
+    merkleTree?: MerkleTreeJson;
+    encryptedOutputs?: EncryptedOutputWithSign<string>[];
+    encryptedOutputsByCommitment?: EncryptedOutputWithCommitment[];
+};
+export declare abstract class AbstractCommitmentsSnapshotService extends AbstractSnapshotService<CommitmentEvent<bigint>, CommitmentsSnapshotPayload, CommitmentsSerializedSnapshot> {
+    constructor(hinkalEventEmitter: BlockchainEventEmitter);
+    private _merkleTree;
+    private _encryptedOutputs;
+    private _encryptedOutputsByCommitment;
+    get merkleTree(): MerkleTree<bigint>;
+    get encryptedOutputs(): EncryptedOutputWithSign<boolean>[];
+    protected serializeSnapshot(snapshot: Snapshot<CommitmentsSnapshotPayload>): CommitmentsSerializedSnapshot;
+    protected deserializeSnapshot(serializedSnapshot: CommitmentsSerializedSnapshot): Snapshot<CommitmentsSnapshotPayload>;
+    protected getSnapshotPayload(): {
+        merkleTree: MerkleTree<bigint>;
+        encryptedOutputs: EncryptedOutputWithSign<boolean>[];
+        encryptedOutputsByCommitment: Map<bigint, string>;
+    };
+    protected populateSnapshot({ payload: { merkleTree, encryptedOutputs, encryptedOutputsByCommitment }, }: Snapshot<CommitmentsSnapshotPayload>): void;
+    protected mapEvent(event: BlockchainEvent): CommitmentEvent<bigint>;
+    protected acceptEvent(event: CommitmentEvent<bigint>, _blockNumber: number, _txHash?: string, isBlocked?: boolean): boolean;
+}

package/common/src/data-structures/event-service/evm/AbstractEventService.d.ts

@@ -0,0 +1,14 @@
+import { BlockchainEvent } from '../../BlockchainEvent/BlockchainEvent';
+import { BlockchainEventEmitter } from './BlockchainEventEmitter';
+export declare abstract class AbstractEventService<EventType> {
+    protected blockchainEventEmitter: BlockchainEventEmitter;
+    protected readonly eventName: string;
+    protected constructor(blockchainEventEmitter: BlockchainEventEmitter, eventName: string);
+    get latestBlockNumber(): number;
+    get chainId(): number;
+    intervalClear(): void;
+    private processEventsPage;
+    protected abstract acceptEvent(event: EventType, blockNumber: number, txHash?: string, isBlocked?: boolean): boolean | Promise<boolean>;
+    protected abstract mapEvent(event: BlockchainEvent): EventType;
+    protected abstract afterEventsAccepted(eventsCount: number): Promise<void>;
+}

package/common/src/data-structures/event-service/evm/AbstractNullifierSnapshotService.d.ts

@@ -0,0 +1,22 @@
+import { NullifierEvent } from '../../../types/commitments.types';
+import { AbstractSnapshotService, Snapshot } from './AbstractSnapshotService';
+import { BlockchainEventEmitter } from './BlockchainEventEmitter';
+import { BlockchainEvent } from '../../BlockchainEvent/BlockchainEvent';
+export type NullifierSnapshotPayload = {
+    readonly nullifiers: Set<string>;
+};
+export type NullifierSerializedSnapshot = {
+    latestBlockNumber?: number;
+    nullifiers?: string[];
+};
+export declare abstract class AbstractNullifierSnapshotService extends AbstractSnapshotService<NullifierEvent<string>, NullifierSnapshotPayload, NullifierSerializedSnapshot> {
+    constructor(hinkalEventEmitter: BlockchainEventEmitter);
+    private _nullifiers;
+    get nullifiers(): Set<string>;
+    protected serializeSnapshot(snapshot: Snapshot<NullifierSnapshotPayload>): NullifierSerializedSnapshot;
+    protected deserializeSnapshot(serializedSnapshot: NullifierSerializedSnapshot): Snapshot<NullifierSnapshotPayload>;
+    protected acceptEvent(event: NullifierEvent<string>, _blockNumber: number): boolean;
+    protected mapEvent(event: BlockchainEvent): NullifierEvent<string>;
+    protected getSnapshotPayload(): NullifierSnapshotPayload;
+    protected populateSnapshot({ payload: { nullifiers } }: Snapshot<NullifierSnapshotPayload>): void;
+}

package/common/src/data-structures/event-service/evm/AbstractSnapshotService.d.ts

@@ -0,0 +1,22 @@
+import { AbstractEventService } from './AbstractEventService';
+import { BlockchainEventEmitter } from './BlockchainEventEmitter';
+export interface Snapshot<SnapshotPayloadType> {
+    readonly latestBlockNumber: number;
+    readonly payload: SnapshotPayloadType;
+}
+export declare abstract class AbstractSnapshotService<EventType, SnapshotPayloadType, SerializedSnapshotType> extends AbstractEventService<EventType> {
+    private savedLatestBlockNumber;
+    protected constructor(blockchainEventEmitter: BlockchainEventEmitter, eventName: string);
+    init(): Promise<void>;
+    retrieveEventsFromLatestBlock(): Promise<void>;
+    get isReady(): boolean;
+    private loadSnapshot;
+    protected saveSnapshot(): Promise<unknown>;
+    protected afterEventsAccepted(eventsCount: number): Promise<void>;
+    protected abstract getSnapshotPayload(): SnapshotPayloadType;
+    protected abstract populateSnapshot(snapshot: Snapshot<SnapshotPayloadType>): void;
+    protected abstract serializeSnapshot(snapshot: Snapshot<SnapshotPayloadType>): SerializedSnapshotType;
+    protected abstract deserializeSnapshot(serializedSnapshot: SerializedSnapshotType): Snapshot<SnapshotPayloadType>;
+    protected abstract fetchSnapshot(): Promise<SerializedSnapshotType>;
+    protected abstract persistSnapshot(serializedSnapshot: SerializedSnapshotType): Promise<unknown>;
+}

package/common/src/data-structures/event-service/evm/BlockchainEventEmitter.cjs

@@ -1 +1 @@
-require(`../../../../../_virtual/_rolldown/runtime.cjs`);const e=require(`../../../error-handling/logger.cjs`),t=require(`../../../functions/utils/resolve-sync.utils.cjs`),n=require(`../../../constants/reorg-depths.constants.cjs`),r=require(`../../../functions/utils/getSignerFromContract.cjs`),i=require(`../../BlockchainEvent/BlockchainEvent.cjs`);let a=require(`ethers`);var o=class{RETRY_MIN_PAGE_SIZE=100;MAX_RETRIES=20;_chainId;contract;depositOnChainUtxosContract;_latestBlockNumber;_initialBlockNumber;onEventsProcessed;eventProcessors=new Set;maxPageSize;_isReady=!1;isServer;inProgress;eventsFetchingMutex;constructor(e,t,n,r,i,a,o){this.contract=t,this.depositOnChainUtxosContract=o,this._chainId=e,this._initialBlockNumber=n,this.maxPageSize=a,this.isServer=r,this.inProgress=!1,this.eventsFetchingMutex=i}get latestBlockNumber(){return this._latestBlockNumber??this._initialBlockNumber}get chainId(){return this._chainId}get isReady(){return this._isReady}syncFromAtMost(e){(this._latestBlockNumber===void 0||e<this._latestBlockNumber)&&(this._latestBlockNumber=e)}advanceLatestBlockNumber(e){e>(this._latestBlockNumber??this._initialBlockNumber)&&(this._latestBlockNumber=e)}intervalClear(){this._isReady=!1,this.eventProcessors=new Set,this.clear()}async init(){if(this._isReady)throw Error(`Already initialized`);this._isReady=!0,await this.retrieveEvents(this.latestBlockNumber+1),this.startUpdateListener()}requireReady(){if(!this._isReady)throw Error(`Not ready`)}async getEventsForSingleContract(e,t,n,r=0){try{return(await e.queryFilter(`*`,t,n)).filter(e=>e instanceof a.ethers.EventLog)}catch(i){if(r<this.MAX_RETRIES&&n-t>this.RETRY_MIN_PAGE_SIZE){let i=Math.floor((t+n)/2),a=await this.getEventsForSingleContract(e,t,i,r+1),o=await this.getEventsForSingleContract(e,i+1,n,r+1);return[...a,...o]}throw i}}addEventProcessorFunction(e){if(this._isReady)throw Error(`Can't add event processor after event emitter initialized`);this.eventProcessors.add(e)}async getEventsInRange(e,n){let r=[],a=t.getSequence(e,n,this.maxPageSize);await t.resolveSync(a.map(({from:e,to:t})=>async()=>{let n=await this.getEventsForSingleContract(this.contract,e,t);r.push(...n)}));let o=this.depositOnChainUtxosContract;return o&&await t.resolveSync(a.map(({from:e,to:t})=>async()=>{let n=await this.getEventsForSingleContract(o,e,t);r.push(...n)})),r.map(e=>i.BlockchainEvent.fromEthers(e))}async getLastBlockNumberForEventRequest(){let e=await r.getProviderFromContract(this.contract).getBlockNumber();if(!this.isServer)return e;let{chainId:t}=await r.getProviderFromContract(this.contract).getNetwork();return Math.max(this.latestBlockNumber,e-n.blockReorgDepth[Number(t)]+1)}async retrieveEvents(t,n=!1){return this.requireReady(),await this.eventsFetchingMutex.runExclusive(async()=>{try{if(this.inProgress&&!n)return!1;this.inProgress=!0;let e=await this.getLastBlockNumberForEventRequest();if(e<t)return this.inProgress=!1,!1;let r=await this.getEventsInRange(t,e);return await this.processEvents(r,e),this._latestBlockNumber=e,this.inProgress=!1,!0}catch(t){return e.Logger.error(`retrieveEvents error`,t),this.inProgress=!1,!1}})}async processEvents(e,t){let n=(await Promise.all([...this.eventProcessors].map(n=>n(e,t)))).reduce((e,t)=>e+t,0);this.onEventsProcessed?.(n)}};exports.BlockchainEventEmitter=o;
+require(`../../../../../_virtual/_rolldown/runtime.cjs`);const e=require(`../../../constants/chains.constants.cjs`),t=require(`../../../error-handling/logger.cjs`),n=require(`../../../types/ethereum-network.types.cjs`),r=require(`../../../constants/contracts.constants.cjs`),i=require(`../../../functions/web3/getContractMetadata.cjs`),a=require(`../../../functions/utils/getSignerFromContract.cjs`),o=require(`../../../functions/utils/resolve-sync.utils.cjs`),s=require(`../../../constants/reorg-depths.constants.cjs`),c=require(`../../BlockchainEvent/BlockchainEvent.cjs`);let l=require(`ethers`);var u=class{RETRY_MIN_PAGE_SIZE=100;MAX_RETRIES=20;_chainId;contract;_latestBlockNumber;_blockedUtxosContract;_initialBlockNumber;onEventsProcessed;eventProcessors=new Set;maxPageSize;_isReady=!1;isServer;inProgress;eventsFetchingMutex;constructor(e,t,n,r,i,a){this.contract=t,this._chainId=e,this._initialBlockNumber=n,this.maxPageSize=a,this.isServer=r,this.inProgress=!1,this.eventsFetchingMutex=i}get latestBlockNumber(){return this._latestBlockNumber??this._initialBlockNumber}get chainId(){return this._chainId}get isReady(){return this._isReady}syncFromAtMost(e){(this._latestBlockNumber===void 0||e<this._latestBlockNumber)&&(this._latestBlockNumber=e)}advanceLatestBlockNumber(e){e>(this._latestBlockNumber??this._initialBlockNumber)&&(this._latestBlockNumber=e)}intervalClear(){this._isReady=!1,this.eventProcessors=new Set,this.clear()}async init(){if(this._isReady)throw Error(`Already initialized`);this._isReady=!0,await this.retrieveEvents(this.latestBlockNumber+1),this.startUpdateListener()}requireReady(){if(!this._isReady)throw Error(`Not ready`)}async getEventsForSingleContract(e,t,n,r=0,i=`*`){try{return(await e.queryFilter(i,t,n)).filter(e=>e instanceof l.ethers.EventLog)}catch(a){if(r<this.MAX_RETRIES&&n-t>this.RETRY_MIN_PAGE_SIZE){let a=Math.floor((t+n)/2),o=await this.getEventsForSingleContract(e,t,a,r+1,i),s=await this.getEventsForSingleContract(e,a+1,n,r+1,i);return[...o,...s]}throw a}}get blockedUtxosContract(){if(this._blockedUtxosContract===void 0){let t=e.getNonLocalhostChainId(this._chainId);this._blockedUtxosContract=r.getDepositOnChainUtxosAddress(t)?i.getContractWithFetcherByChainId(t,n.ContractType.DepositOnChainUtxosContract):null}return this._blockedUtxosContract??void 0}addEventProcessorFunction(e){if(this._isReady)throw Error(`Can't add event processor after event emitter initialized`);this.eventProcessors.add(e)}async getEventsInRange(e,t){let n=[];return await o.resolveSync(o.getSequence(e,t,this.maxPageSize).map(({from:e,to:t})=>async()=>{let r=await this.getEventsForSingleContract(this.contract,e,t);n.push(...r);let i=this.blockedUtxosContract;i&&n.push(...await this.getEventsForSingleContract(i,e,t,0,`BlockedUtxosCreated`))})),n.map(e=>c.BlockchainEvent.fromEthers(e))}async getLastBlockNumberForEventRequest(){let e=await a.getProviderFromContract(this.contract).getBlockNumber();if(!this.isServer)return e;let{chainId:t}=await a.getProviderFromContract(this.contract).getNetwork();return Math.max(this.latestBlockNumber,e-s.blockReorgDepth[Number(t)]+1)}async retrieveEvents(e,n=!1){return this.requireReady(),await this.eventsFetchingMutex.runExclusive(async()=>{try{if(this.inProgress&&!n)return!1;this.inProgress=!0;let t=await this.getLastBlockNumberForEventRequest();if(t<e)return this.inProgress=!1,!1;let r=await this.getEventsInRange(e,t);return await this.processEvents(r,t),this._latestBlockNumber=t,this.inProgress=!1,!0}catch(e){return t.Logger.error(`retrieveEvents error`,e),this.inProgress=!1,!1}})}async processEvents(e,t){let n=(await Promise.all([...this.eventProcessors].map(n=>n(e,t)))).reduce((e,t)=>e+t,0);this.onEventsProcessed?.(n)}};exports.BlockchainEventEmitter=u;

package/common/src/data-structures/event-service/evm/BlockchainEventEmitter.d.ts

@@ -0,0 +1,38 @@
+import { ethers } from 'ethers';
+import { ChainBalanceFetchingLock } from '../../../mutexes/chainBalanceRwLock';
+import { EventProcessorFunction } from '../../../types/events.types';
+import { BlockchainEvent } from '../../BlockchainEvent/BlockchainEvent';
+export declare abstract class BlockchainEventEmitter {
+    private readonly RETRY_MIN_PAGE_SIZE;
+    private readonly MAX_RETRIES;
+    private readonly _chainId;
+    readonly contract: ethers.Contract;
+    private _latestBlockNumber;
+    private _blockedUtxosContract;
+    private _initialBlockNumber;
+    onEventsProcessed?: (acceptedEventCount: number) => void;
+    private eventProcessors;
+    private readonly maxPageSize?;
+    private _isReady;
+    protected isServer: boolean;
+    private inProgress;
+    protected eventsFetchingMutex: ChainBalanceFetchingLock;
+    constructor(chainId: number, contract: ethers.Contract, initialBlockNumber: number, isServer: boolean, eventsFetchingMutex: ChainBalanceFetchingLock, maxPageSize?: number);
+    get latestBlockNumber(): number;
+    get chainId(): number;
+    get isReady(): boolean;
+    syncFromAtMost(blockNumber: number): void;
+    protected advanceLatestBlockNumber(blockNumber: number): void;
+    intervalClear(): void;
+    init(): Promise<void>;
+    private requireReady;
+    private getEventsForSingleContract;
+    private get blockedUtxosContract();
+    addEventProcessorFunction(eventProcessorFunction: EventProcessorFunction): void;
+    getEventsInRange(fromBlockNumber: number, toBlockNumber: number): Promise<BlockchainEvent[]>;
+    getLastBlockNumberForEventRequest(): Promise<number>;
+    retrieveEvents(fromBlockNumber: number, useForce?: boolean): Promise<boolean>;
+    protected processEvents(events: BlockchainEvent[], scannedToBlock?: number): Promise<void>;
+    protected abstract clear(): void;
+    protected abstract startUpdateListener(): void;
+}

package/common/src/data-structures/event-service/evm/BlockchainEventEmitter.mjs

@@ -1,17 +1,21 @@
-import { Logger as e } from "../../../error-handling/logger.mjs";
-import { getSequence as t, resolveSync as n } from "../../../functions/utils/resolve-sync.utils.mjs";
-import { blockReorgDepth as r } from "../../../constants/reorg-depths.constants.mjs";
-import { getProviderFromContract as i } from "../../../functions/utils/getSignerFromContract.mjs";
-import { BlockchainEvent as a } from "../../BlockchainEvent/BlockchainEvent.mjs";
-import { ethers as o } from "ethers";
+import { getNonLocalhostChainId as e } from "../../../constants/chains.constants.mjs";
+import { Logger as t } from "../../../error-handling/logger.mjs";
+import { ContractType as n } from "../../../types/ethereum-network.types.mjs";
+import { getDepositOnChainUtxosAddress as r } from "../../../constants/contracts.constants.mjs";
+import { getContractWithFetcherByChainId as i } from "../../../functions/web3/getContractMetadata.mjs";
+import { getProviderFromContract as a } from "../../../functions/utils/getSignerFromContract.mjs";
+import { getSequence as o, resolveSync as s } from "../../../functions/utils/resolve-sync.utils.mjs";
+import { blockReorgDepth as c } from "../../../constants/reorg-depths.constants.mjs";
+import { BlockchainEvent as l } from "../../BlockchainEvent/BlockchainEvent.mjs";
+import { ethers as u } from "ethers";
 //#region libs/shared/common/src/data-structures/event-service/evm/BlockchainEventEmitter.ts
-var s = class {
+var d = class {
 	RETRY_MIN_PAGE_SIZE = 100;
 	MAX_RETRIES = 20;
 	_chainId;
 	contract;
-	depositOnChainUtxosContract;
 	_latestBlockNumber;
+	_blockedUtxosContract;
 	_initialBlockNumber;
 	onEventsProcessed;
 	eventProcessors = /* @__PURE__ */ new Set();
@@ -20,8 +24,8 @@ var s = class {
 	isServer;
 	inProgress;
 	eventsFetchingMutex;
-	constructor(e, t, n, r, i, a, o) {
-		this.contract = t, this.depositOnChainUtxosContract = o, this._chainId = e, this._initialBlockNumber = n, this.maxPageSize = a, this.isServer = r, this.inProgress = !1, this.eventsFetchingMutex = i;
+	constructor(e, t, n, r, i, a) {
+		this.contract = t, this._chainId = e, this._initialBlockNumber = n, this.maxPageSize = a, this.isServer = r, this.inProgress = !1, this.eventsFetchingMutex = i;
 	}
 	get latestBlockNumber() {
 		return this._latestBlockNumber ?? this._initialBlockNumber;
@@ -48,50 +52,54 @@ var s = class {
 	requireReady() {
 		if (!this._isReady) throw Error("Not ready");
 	}
-	async getEventsForSingleContract(e, t, n, r = 0) {
+	async getEventsForSingleContract(e, t, n, r = 0, i = "*") {
 		try {
-			return (await e.queryFilter("*", t, n)).filter((e) => e instanceof o.EventLog);
-		} catch (i) {
+			return (await e.queryFilter(i, t, n)).filter((e) => e instanceof u.EventLog);
+		} catch (a) {
 			if (r < this.MAX_RETRIES && n - t > this.RETRY_MIN_PAGE_SIZE) {
-				let i = Math.floor((t + n) / 2), a = await this.getEventsForSingleContract(e, t, i, r + 1), o = await this.getEventsForSingleContract(e, i + 1, n, r + 1);
-				return [...a, ...o];
+				let a = Math.floor((t + n) / 2), o = await this.getEventsForSingleContract(e, t, a, r + 1, i), s = await this.getEventsForSingleContract(e, a + 1, n, r + 1, i);
+				return [...o, ...s];
 			}
-			throw i;
+			throw a;
 		}
 	}
+	get blockedUtxosContract() {
+		if (this._blockedUtxosContract === void 0) {
+			let t = e(this._chainId);
+			this._blockedUtxosContract = r(t) ? i(t, n.DepositOnChainUtxosContract) : null;
+		}
+		return this._blockedUtxosContract ?? void 0;
+	}
 	addEventProcessorFunction(e) {
 		if (this._isReady) throw Error("Can't add event processor after event emitter initialized");
 		this.eventProcessors.add(e);
 	}
-	async getEventsInRange(e, r) {
-		let i = [], o = t(e, r, this.maxPageSize);
-		await n(o.map(({ from: e, to: t }) => async () => {
-			let n = await this.getEventsForSingleContract(this.contract, e, t);
-			i.push(...n);
-		}));
-		let s = this.depositOnChainUtxosContract;
-		return s && await n(o.map(({ from: e, to: t }) => async () => {
-			let n = await this.getEventsForSingleContract(s, e, t);
-			i.push(...n);
-		})), i.map((e) => a.fromEthers(e));
+	async getEventsInRange(e, t) {
+		let n = [];
+		return await s(o(e, t, this.maxPageSize).map(({ from: e, to: t }) => async () => {
+			let r = await this.getEventsForSingleContract(this.contract, e, t);
+			n.push(...r);
+			let i = this.blockedUtxosContract;
+			i && n.push(...await this.getEventsForSingleContract(i, e, t, 0, "BlockedUtxosCreated"));
+		})), n.map((e) => l.fromEthers(e));
 	}
 	async getLastBlockNumberForEventRequest() {
-		let e = await i(this.contract).getBlockNumber();
+		let e = await a(this.contract).getBlockNumber();
 		if (!this.isServer) return e;
-		let { chainId: t } = await i(this.contract).getNetwork();
-		return Math.max(this.latestBlockNumber, e - r[Number(t)] + 1);
+		let { chainId: t } = await a(this.contract).getNetwork();
+		return Math.max(this.latestBlockNumber, e - c[Number(t)] + 1);
 	}
-	async retrieveEvents(t, n = !1) {
+	async retrieveEvents(e, n = !1) {
 		return this.requireReady(), await this.eventsFetchingMutex.runExclusive(async () => {
 			try {
 				if (this.inProgress && !n) return !1;
 				this.inProgress = !0;
-				let e = await this.getLastBlockNumberForEventRequest();
-				if (e < t) return this.inProgress = !1, !1;
-				let r = await this.getEventsInRange(t, e);
-				return await this.processEvents(r, e), this._latestBlockNumber = e, this.inProgress = !1, !0;
-			} catch (t) {
-				return e.error("retrieveEvents error", t), this.inProgress = !1, !1;
+				let t = await this.getLastBlockNumberForEventRequest();
+				if (t < e) return this.inProgress = !1, !1;
+				let r = await this.getEventsInRange(e, t);
+				return await this.processEvents(r, t), this._latestBlockNumber = t, this.inProgress = !1, !0;
+			} catch (e) {
+				return t.error("retrieveEvents error", e), this.inProgress = !1, !1;
 			}
 		});
 	}
@@ -101,4 +109,4 @@ var s = class {
 	}
 };
 //#endregion
-export { s as BlockchainEventEmitter };
+export { d as BlockchainEventEmitter };