@0xpolygonid/js-sdk 1.31.1 → 1.31.3

package/dist/node/cjs/credentials/status/on-chain-revocation.js

@@ -21,8 +21,9 @@ class OnChainResolver {
      * @public
      * @param {Array<EthConnectionConfig>} _configs - list of ethereum network connections
      */
-    constructor(_configs) {
+    constructor(_configs, _opts) {
         this._configs = _configs;
+        this._stateStorage = new state_1.EthStateStorage(_configs, _opts?.stateStorageOptions);
     }
     /**
      * resolve is a method to resolve a credential status from the blockchain.
@@ -53,8 +54,7 @@ class OnChainResolver {
         const issuerId = js_iden3_core_1.DID.idFromDID(issuer);
         let latestIssuerState;
         try {
-            const ethStorage = this._getStateStorageForIssuer(issuerId);
-            const latestStateInfo = await ethStorage.getLatestStateById(issuerId.bigInt());
+            const latestStateInfo = await this._stateStorage.getLatestStateById(issuerId.bigInt());
             if (!latestStateInfo.state) {
                 throw new Error('state contract returned empty state');
             }
@@ -120,13 +120,6 @@ class OnChainResolver {
         }
         return network;
     }
-    // TODO: is dirty hack for mock in tests.
-    // need to pass to constructor list of state stores not list of network configs
-    _getStateStorageForIssuer(issuerId) {
-        const issuerChainId = (0, js_iden3_core_1.getChainId)(js_iden3_core_1.DID.blockchainFromId(issuerId), js_iden3_core_1.DID.networkIdFromId(issuerId));
-        const ethStorage = new state_1.EthStateStorage(this.networkByChainId(issuerChainId));
-        return ethStorage;
-    }
     _getOnChainRevocationStorageForIssuer(chainId, contractAddress) {
         const networkConfig = this.networkByChainId(chainId);
         const onChainCaller = new onchain_revocation_1.OnChainRevocationStorage(networkConfig, contractAddress);

package/dist/node/cjs/identity/identity-wallet.js

@@ -272,18 +272,23 @@ class IdentityWallet {
         return { nonce: profile.nonce, genesisDID: js_iden3_core_1.DID.parse(profile.genesisIdentifier) };
     }
     /** {@inheritDoc IIdentityWallet.createProfile} */
-    async createProfile(did, nonce, verifier) {
+    async createProfile(did, nonce, verifier, tags) {
         const profileDID = (0, common_1.generateProfileDID)(did, nonce);
         const identityProfiles = await this._storage.identity.getProfilesByGenesisIdentifier(did.string());
-        const existingProfile = identityProfiles.find((p) => p.nonce == nonce || p.verifier == verifier);
-        if (existingProfile) {
+        const profilesForTagAndVerifier = await this._storage.identity.getProfilesByVerifier(verifier, tags);
+        if (profilesForTagAndVerifier.length) {
+            throw new Error(verifiable_1.VerifiableConstants.ERRORS.ID_WALLET_PROFILE_ALREADY_EXISTS_VERIFIER_TAGS);
+        }
+        const existingProfileWithNonce = identityProfiles.find((p) => p.nonce == nonce);
+        if (existingProfileWithNonce) {
             throw new Error(verifiable_1.VerifiableConstants.ERRORS.ID_WALLET_PROFILE_ALREADY_EXISTS);
         }
         await this._storage.identity.saveProfile({
             id: profileDID.string(),
             nonce,
             genesisIdentifier: did.string(),
-            verifier
+            verifier,
+            tags
         });
         return profileDID;
     }
@@ -302,9 +307,17 @@ class IdentityWallet {
         const key = await this._kms.createKeyFromSeed(keyType, (0, js_crypto_1.getRandomBytes)(32));
         return key;
     }
+    /**
+     * @deprecated The method should not be used. It returns only one profile per verifier, which can potentially restrict business use cases
+     * {@inheritDoc IIdentityWallet.getProfileByVerifier}
+     */
     async getProfileByVerifier(verifier) {
         return this._storage.identity.getProfileByVerifier(verifier);
     }
+    /** {@inheritDoc IIdentityWallet.getProfilesByVerifier} */
+    async getProfilesByVerifier(verifier, tags) {
+        return this._storage.identity.getProfilesByVerifier(verifier, tags);
+    }
     /** {@inheritDoc IIdentityWallet.getDIDTreeModel} */
     async getDIDTreeModel(did) {
         const didStr = did.string();

package/dist/node/cjs/storage/blockchain/onchain-zkp-verifier.js

@@ -7,7 +7,6 @@ exports.packEthIdentityProof = exports.OnChainZKPVerifier = exports.toTxDataArgs
 const ethers_1 = require("ethers");
 const iden3comm_1 = require("../../iden3comm");
 const ZkpVerifier_json_1 = __importDefault(require("./abi/ZkpVerifier.json"));
-//import { UniversalVerifier } from '@iden3/universal-verifier-v2-abi';
 const universal_verifier_v2_abi_1 = require("@iden3/universal-verifier-v2-abi");
 const blockchain_1 = require("../../blockchain");
 const js_iden3_core_1 = require("@iden3/js-iden3-core");

package/dist/node/cjs/storage/blockchain/state.js

@@ -11,6 +11,9 @@ const State_json_1 = __importDefault(require("./abi/State.json"));
 const js_iden3_core_1 = require("@iden3/js-iden3-core");
 const blockchain_1 = require("../../blockchain");
 const common_1 = require("./common");
+const memory_1 = require("../memory");
+const iden3comm_1 = require("../../iden3comm");
+const verifiable_1 = require("../../verifiable");
 exports.defaultEthConnectionConfig = {
     url: 'http://localhost:8545',
     defaultGasLimit: 600000,
@@ -36,15 +39,71 @@ class EthStateStorage {
      * Creates an instance of EthStateStorage.
      * @param {EthConnectionConfig} [ethConfig=defaultEthConnectionConfig]
      */
-    constructor(ethConfig) {
+    constructor(ethConfig, options) {
         this.ethConfig = ethConfig;
+        this._disableCache = false;
         const config = Array.isArray(ethConfig) ? ethConfig[0] : ethConfig;
         this.provider = new ethers_1.JsonRpcProvider(config.url);
         this.stateContract = new ethers_1.Contract(config.contractAddress, State_json_1.default, this.provider);
         this._transactionService = new blockchain_1.TransactionService(this.getRpcProvider());
+        // Store cache options for later use
+        this._latestStateCacheOptions = {
+            ttl: options?.latestStateCacheOptions?.ttl ?? iden3comm_1.PROTOCOL_CONSTANTS.DEFAULT_PROOF_VERIFY_DELAY / 2,
+            maxSize: options?.latestStateCacheOptions?.maxSize ?? verifiable_1.DEFAULT_CACHE_MAX_SIZE
+        };
+        this._stateCacheOptions = {
+            notReplacedTtl: options?.stateCacheOptions?.notReplacedTtl ??
+                iden3comm_1.PROTOCOL_CONSTANTS.DEFAULT_PROOF_VERIFY_DELAY / 2,
+            replacedTtl: options?.stateCacheOptions?.replacedTtl ?? iden3comm_1.PROTOCOL_CONSTANTS.DEFAULT_PROOF_VERIFY_DELAY,
+            maxSize: options?.stateCacheOptions?.maxSize ?? verifiable_1.DEFAULT_CACHE_MAX_SIZE
+        };
+        this._rootCacheOptions = {
+            replacedTtl: options?.rootCacheOptions?.replacedTtl ?? iden3comm_1.PROTOCOL_CONSTANTS.DEFAULT_AUTH_VERIFY_DELAY,
+            notReplacedTtl: options?.rootCacheOptions?.notReplacedTtl ??
+                iden3comm_1.PROTOCOL_CONSTANTS.DEFAULT_AUTH_VERIFY_DELAY / 2,
+            maxSize: options?.rootCacheOptions?.maxSize ?? verifiable_1.DEFAULT_CACHE_MAX_SIZE
+        };
+        this._gistProofCacheOptions = {
+            ttl: iden3comm_1.PROTOCOL_CONSTANTS.DEFAULT_AUTH_VERIFY_DELAY / 2,
+            maxSize: options?.gistProofCacheOptions?.maxSize ?? verifiable_1.DEFAULT_CACHE_MAX_SIZE
+        };
+        // Initialize cache instances
+        this._latestStateResolveCache =
+            options?.latestStateCacheOptions?.cache ??
+                (0, memory_1.createInMemoryCache)({
+                    maxSize: this._latestStateCacheOptions.maxSize,
+                    ttl: this._latestStateCacheOptions.ttl
+                });
+        this._stateResolveCache =
+            options?.stateCacheOptions?.cache ??
+                (0, memory_1.createInMemoryCache)({
+                    maxSize: this._stateCacheOptions.maxSize,
+                    ttl: this._stateCacheOptions.replacedTtl
+                });
+        this._rootResolveCache =
+            options?.rootCacheOptions?.cache ??
+                (0, memory_1.createInMemoryCache)({
+                    maxSize: this._rootCacheOptions.maxSize,
+                    ttl: this._rootCacheOptions.replacedTtl
+                });
+        this._gistProofResolveCache =
+            options?.gistProofCacheOptions?.cache ??
+                (0, memory_1.createInMemoryCache)({
+                    maxSize: this._gistProofCacheOptions.maxSize,
+                    ttl: this._gistProofCacheOptions.ttl
+                });
+        this._disableCache = options?.disableCache ?? false;
     }
     /** {@inheritdoc IStateStorage.getLatestStateById} */
     async getLatestStateById(id) {
+        const cacheKey = this.getLatestStateCacheKey(id);
+        if (!this._disableCache) {
+            // Check cache first
+            const cachedResult = await this._latestStateResolveCache?.get(cacheKey);
+            if (cachedResult) {
+                return cachedResult;
+            }
+        }
         const { stateContract } = this.getStateContractAndProviderForId(id);
         const rawData = await stateContract.getStateInfoById(id);
         const stateInfo = {
@@ -56,10 +115,20 @@ class EthStateStorage {
             createdAtBlock: BigInt(rawData[5]),
             replacedAtBlock: BigInt(rawData[6])
         };
+        !this._disableCache &&
+            (await this._latestStateResolveCache?.set(cacheKey, stateInfo, this._latestStateCacheOptions.ttl));
         return stateInfo;
     }
     /** {@inheritdoc IStateStorage.getStateInfoByIdAndState} */
     async getStateInfoByIdAndState(id, state) {
+        const cacheKey = this.getStateCacheKey(id, state);
+        if (!this._disableCache) {
+            // Check cache first
+            const cachedResult = await this._stateResolveCache?.get(cacheKey);
+            if (cachedResult) {
+                return cachedResult;
+            }
+        }
         const { stateContract } = this.getStateContractAndProviderForId(id);
         const rawData = await stateContract.getStateInfoByIdAndState(id, state);
         const stateInfo = {
@@ -71,6 +140,10 @@ class EthStateStorage {
             createdAtBlock: BigInt(rawData[5]),
             replacedAtBlock: BigInt(rawData[6])
         };
+        const ttl = stateInfo.replacedAtTimestamp === 0n
+            ? this._stateCacheOptions.notReplacedTtl
+            : this._stateCacheOptions.replacedTtl;
+        !this._disableCache && (await this._stateResolveCache?.set(cacheKey, stateInfo, ttl));
         return stateInfo;
     }
     /** {@inheritdoc IStateStorage.publishState} */
@@ -143,9 +216,17 @@ class EthStateStorage {
     }
     /** {@inheritdoc IStateStorage.getGISTProof} */
     async getGISTProof(id) {
+        const cacheKey = this.getGistProofCacheKey(id);
+        if (!this._disableCache) {
+            // Check cache first
+            const cachedResult = await this._gistProofResolveCache?.get(cacheKey);
+            if (cachedResult) {
+                return cachedResult;
+            }
+        }
         const { stateContract } = this.getStateContractAndProviderForId(id);
         const data = await stateContract.getGISTProof(id);
-        return {
+        const stateProof = {
             root: BigInt(data.root.toString()),
             existence: data.existence,
             siblings: data.siblings?.map((sibling) => BigInt(sibling.toString())),
@@ -155,12 +236,23 @@ class EthStateStorage {
             auxIndex: BigInt(data.auxIndex.toString()),
             auxValue: BigInt(data.auxValue.toString())
         };
+        !this._disableCache &&
+            (await this._gistProofResolveCache?.set(cacheKey, stateProof, this._gistProofCacheOptions.ttl));
+        return stateProof;
     }
     /** {@inheritdoc IStateStorage.getGISTRootInfo} */
     async getGISTRootInfo(root, id) {
+        const cacheKey = this.getRootCacheKey(root);
+        if (!this._disableCache) {
+            // Check cache first
+            const cachedResult = await this._rootResolveCache?.get(cacheKey);
+            if (cachedResult) {
+                return cachedResult;
+            }
+        }
         const { stateContract } = this.getStateContractAndProviderForId(id);
         const data = await stateContract.getGISTRootInfo(root);
-        return {
+        const rootInfo = {
             root: BigInt(data.root.toString()),
             replacedByRoot: BigInt(data.replacedByRoot.toString()),
             createdAtTimestamp: BigInt(data.createdAtTimestamp.toString()),
@@ -168,11 +260,24 @@ class EthStateStorage {
             createdAtBlock: BigInt(data.createdAtBlock.toString()),
             replacedAtBlock: BigInt(data.replacedAtBlock.toString())
         };
+        const ttl = rootInfo.replacedAtTimestamp == 0n
+            ? this._rootCacheOptions.notReplacedTtl
+            : this._rootCacheOptions.replacedTtl;
+        !this._disableCache && (await this._rootResolveCache?.set(cacheKey, rootInfo, ttl));
+        return rootInfo;
     }
     /** {@inheritdoc IStateStorage.getRpcProvider} */
     getRpcProvider() {
         return this.provider;
     }
+    /** enable caching */
+    enableCache() {
+        this._disableCache = false;
+    }
+    /** disable caching */
+    disableCache() {
+        this._disableCache = true;
+    }
     getStateContractAndProviderForId(id) {
         const idTyped = js_iden3_core_1.Id.fromBigInt(id);
         const chainId = (0, js_iden3_core_1.getChainId)(js_iden3_core_1.DID.blockchainFromId(idTyped), js_iden3_core_1.DID.networkIdFromId(idTyped));
@@ -189,5 +294,17 @@ class EthStateStorage {
         }
         return network;
     }
+    getGistProofCacheKey(id) {
+        return `gist-${id.toString()}`;
+    }
+    getLatestStateCacheKey(id) {
+        return `latest-${id.toString()}`;
+    }
+    getStateCacheKey(id, state) {
+        return `${id.toString()}-${state.toString()}`;
+    }
+    getRootCacheKey(root) {
+        return root.toString();
+    }
 }
 exports.EthStateStorage = EthStateStorage;

package/dist/node/cjs/storage/memory/cache-lru.js

@@ -0,0 +1,25 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createInMemoryCache = void 0;
+const quick_lru_1 = __importDefault(require("quick-lru"));
+function createInMemoryCache(params) {
+    const cache = new quick_lru_1.default({ maxSize: params.maxSize, maxAge: params.ttl });
+    return {
+        get: async (key) => {
+            return cache.get(key);
+        },
+        set: async (key, value, ttl) => {
+            cache.set(key, value, { maxAge: ttl ?? params.ttl });
+        },
+        clear: async () => {
+            cache.clear();
+        },
+        delete: async (key) => {
+            cache.delete(key);
+        }
+    };
+}
+exports.createInMemoryCache = createInMemoryCache;

package/dist/node/cjs/storage/memory/index.js

@@ -16,3 +16,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./merkletree"), exports);
 __exportStar(require("./data-source"), exports);
+__exportStar(require("./cache-lru"), exports);

package/dist/node/cjs/storage/shared/identity-storage.js

@@ -27,9 +27,16 @@ class IdentityStorage {
             await this._profileDataSource.save(element.id, element);
         }
     }
+    /**
+     *  @deprecated The method should not be used. It returns only one profile per verifier, which can potentially restrict business use cases
+     *   Use getProfilesByVerifier instead.
+     */
     async getProfileByVerifier(verifier) {
         return this._profileDataSource.get(verifier, 'verifier');
     }
+    async getProfilesByVerifier(verifier, tags) {
+        return (await this._profileDataSource.load()).filter((p) => p.verifier === verifier && (!tags || tags.every((tag) => p.tags?.includes(tag))));
+    }
     async getProfileById(profileId) {
         return this._profileDataSource.get(profileId);
     }

package/dist/node/cjs/verifiable/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DisplayMethodType = exports.PaymentFeatures = exports.SupportedCurrencies = exports.SupportedPaymentProofType = exports.PaymentType = exports.PaymentRequestDataType = exports.RefreshServiceType = exports.SubjectPosition = exports.MerklizedRootPosition = exports.ProofPurpose = exports.CredentialStatusType = exports.ProofType = exports.VerifiableConstants = void 0;
+exports.DEFAULT_CACHE_MAX_SIZE = exports.DisplayMethodType = exports.PaymentFeatures = exports.SupportedCurrencies = exports.SupportedPaymentProofType = exports.PaymentType = exports.PaymentRequestDataType = exports.RefreshServiceType = exports.SubjectPosition = exports.MerklizedRootPosition = exports.ProofPurpose = exports.CredentialStatusType = exports.ProofType = exports.VerifiableConstants = void 0;
 /** Verifiable constants */
 exports.VerifiableConstants = Object.freeze({
     ERRORS: {
@@ -19,6 +19,7 @@ exports.VerifiableConstants = Object.freeze({
         ID_WALLET_CORE_CLAIM_IS_NOT_SET: 'core claim is not set in credential proofs',
         ID_WALLET_PROFILE_OR_IDENTITY_NOT_FOUND: 'profile or identity not found',
         ID_WALLET_PROFILE_ALREADY_EXISTS: 'profile with given nonce or verifier already exists',
+        ID_WALLET_PROFILE_ALREADY_EXISTS_VERIFIER_TAGS: 'profile with given verifier and tags already exists',
         ID_WALLET_ISSUER_AUTH_BJJ_CRED_MUST_HAVE_ANY_PROOF: 'issuer auth credential must have proof',
         ID_WALLET_ISSUER_AUTH_BJJ_CRED_MUST_HAVE_MTP_PROOF: 'mtp is required for auth bjj key to issue new credentials',
         // proof service
@@ -200,3 +201,7 @@ var DisplayMethodType;
 (function (DisplayMethodType) {
     DisplayMethodType["Iden3BasicDisplayMethodV1"] = "Iden3BasicDisplayMethodV1";
 })(DisplayMethodType = exports.DisplayMethodType || (exports.DisplayMethodType = {}));
+/**
+ * Default cache max size for in-memory cache
+ */
+exports.DEFAULT_CACHE_MAX_SIZE = 10000;

package/dist/node/esm/credentials/status/on-chain-revocation.js

@@ -1,5 +1,5 @@
 import { OnChainRevocationStorage } from '../../storage/blockchain/onchain-revocation';
-import { DID, getChainId } from '@iden3/js-iden3-core';
+import { DID } from '@iden3/js-iden3-core';
 import { VerifiableConstants } from '../../verifiable/constants';
 import { isGenesisState } from '../../utils';
 import { EthStateStorage } from '../../storage/blockchain/state';
@@ -18,8 +18,9 @@ export class OnChainResolver {
      * @public
      * @param {Array<EthConnectionConfig>} _configs - list of ethereum network connections
      */
-    constructor(_configs) {
+    constructor(_configs, _opts) {
         this._configs = _configs;
+        this._stateStorage = new EthStateStorage(_configs, _opts?.stateStorageOptions);
     }
     /**
      * resolve is a method to resolve a credential status from the blockchain.
@@ -50,8 +51,7 @@ export class OnChainResolver {
         const issuerId = DID.idFromDID(issuer);
         let latestIssuerState;
         try {
-            const ethStorage = this._getStateStorageForIssuer(issuerId);
-            const latestStateInfo = await ethStorage.getLatestStateById(issuerId.bigInt());
+            const latestStateInfo = await this._stateStorage.getLatestStateById(issuerId.bigInt());
             if (!latestStateInfo.state) {
                 throw new Error('state contract returned empty state');
             }
@@ -117,13 +117,6 @@ export class OnChainResolver {
         }
         return network;
     }
-    // TODO: is dirty hack for mock in tests.
-    // need to pass to constructor list of state stores not list of network configs
-    _getStateStorageForIssuer(issuerId) {
-        const issuerChainId = getChainId(DID.blockchainFromId(issuerId), DID.networkIdFromId(issuerId));
-        const ethStorage = new EthStateStorage(this.networkByChainId(issuerChainId));
-        return ethStorage;
-    }
     _getOnChainRevocationStorageForIssuer(chainId, contractAddress) {
         const networkConfig = this.networkByChainId(chainId);
         const onChainCaller = new OnChainRevocationStorage(networkConfig, contractAddress);

package/dist/node/esm/identity/identity-wallet.js

@@ -246,18 +246,23 @@ export class IdentityWallet {
         return { nonce: profile.nonce, genesisDID: DID.parse(profile.genesisIdentifier) };
     }
     /** {@inheritDoc IIdentityWallet.createProfile} */
-    async createProfile(did, nonce, verifier) {
+    async createProfile(did, nonce, verifier, tags) {
         const profileDID = generateProfileDID(did, nonce);
         const identityProfiles = await this._storage.identity.getProfilesByGenesisIdentifier(did.string());
-        const existingProfile = identityProfiles.find((p) => p.nonce == nonce || p.verifier == verifier);
-        if (existingProfile) {
+        const profilesForTagAndVerifier = await this._storage.identity.getProfilesByVerifier(verifier, tags);
+        if (profilesForTagAndVerifier.length) {
+            throw new Error(VerifiableConstants.ERRORS.ID_WALLET_PROFILE_ALREADY_EXISTS_VERIFIER_TAGS);
+        }
+        const existingProfileWithNonce = identityProfiles.find((p) => p.nonce == nonce);
+        if (existingProfileWithNonce) {
             throw new Error(VerifiableConstants.ERRORS.ID_WALLET_PROFILE_ALREADY_EXISTS);
         }
         await this._storage.identity.saveProfile({
             id: profileDID.string(),
             nonce,
             genesisIdentifier: did.string(),
-            verifier
+            verifier,
+            tags
         });
         return profileDID;
     }
@@ -276,9 +281,17 @@ export class IdentityWallet {
         const key = await this._kms.createKeyFromSeed(keyType, getRandomBytes(32));
         return key;
     }
+    /**
+     * @deprecated The method should not be used. It returns only one profile per verifier, which can potentially restrict business use cases
+     * {@inheritDoc IIdentityWallet.getProfileByVerifier}
+     */
     async getProfileByVerifier(verifier) {
         return this._storage.identity.getProfileByVerifier(verifier);
     }
+    /** {@inheritDoc IIdentityWallet.getProfilesByVerifier} */
+    async getProfilesByVerifier(verifier, tags) {
+        return this._storage.identity.getProfilesByVerifier(verifier, tags);
+    }
     /** {@inheritDoc IIdentityWallet.getDIDTreeModel} */
     async getDIDTreeModel(did) {
         const didStr = did.string();

package/dist/node/esm/storage/blockchain/onchain-zkp-verifier.js

@@ -1,7 +1,6 @@
 import { JsonRpcProvider, Contract, ethers } from 'ethers';
 import { AuthMethod, processProofResponse } from '../../iden3comm';
 import abi from './abi/ZkpVerifier.json';
-//import { UniversalVerifier } from '@iden3/universal-verifier-v2-abi';
 import { IVerifierABI } from '@iden3/universal-verifier-v2-abi';
 import { TransactionService } from '../../blockchain';
 import { BytesHelper, chainIDfromDID, DID, Id } from '@iden3/js-iden3-core';

package/dist/node/esm/storage/blockchain/state.js

@@ -5,6 +5,9 @@ import abi from './abi/State.json';
 import { DID, getChainId, Id } from '@iden3/js-iden3-core';
 import { TransactionService } from '../../blockchain';
 import { prepareZkpProof } from './common';
+import { createInMemoryCache } from '../memory';
+import { PROTOCOL_CONSTANTS } from '../../iden3comm';
+import { DEFAULT_CACHE_MAX_SIZE } from '../../verifiable';
 export /** @type {EthConnectionConfig} - default configuration for EthConnectionConfig */ const defaultEthConnectionConfig = {
     url: 'http://localhost:8545',
     defaultGasLimit: 600000,
@@ -30,15 +33,71 @@ export class EthStateStorage {
      * Creates an instance of EthStateStorage.
      * @param {EthConnectionConfig} [ethConfig=defaultEthConnectionConfig]
      */
-    constructor(ethConfig) {
+    constructor(ethConfig, options) {
         this.ethConfig = ethConfig;
+        this._disableCache = false;
         const config = Array.isArray(ethConfig) ? ethConfig[0] : ethConfig;
         this.provider = new JsonRpcProvider(config.url);
         this.stateContract = new Contract(config.contractAddress, abi, this.provider);
         this._transactionService = new TransactionService(this.getRpcProvider());
+        // Store cache options for later use
+        this._latestStateCacheOptions = {
+            ttl: options?.latestStateCacheOptions?.ttl ?? PROTOCOL_CONSTANTS.DEFAULT_PROOF_VERIFY_DELAY / 2,
+            maxSize: options?.latestStateCacheOptions?.maxSize ?? DEFAULT_CACHE_MAX_SIZE
+        };
+        this._stateCacheOptions = {
+            notReplacedTtl: options?.stateCacheOptions?.notReplacedTtl ??
+                PROTOCOL_CONSTANTS.DEFAULT_PROOF_VERIFY_DELAY / 2,
+            replacedTtl: options?.stateCacheOptions?.replacedTtl ?? PROTOCOL_CONSTANTS.DEFAULT_PROOF_VERIFY_DELAY,
+            maxSize: options?.stateCacheOptions?.maxSize ?? DEFAULT_CACHE_MAX_SIZE
+        };
+        this._rootCacheOptions = {
+            replacedTtl: options?.rootCacheOptions?.replacedTtl ?? PROTOCOL_CONSTANTS.DEFAULT_AUTH_VERIFY_DELAY,
+            notReplacedTtl: options?.rootCacheOptions?.notReplacedTtl ??
+                PROTOCOL_CONSTANTS.DEFAULT_AUTH_VERIFY_DELAY / 2,
+            maxSize: options?.rootCacheOptions?.maxSize ?? DEFAULT_CACHE_MAX_SIZE
+        };
+        this._gistProofCacheOptions = {
+            ttl: PROTOCOL_CONSTANTS.DEFAULT_AUTH_VERIFY_DELAY / 2,
+            maxSize: options?.gistProofCacheOptions?.maxSize ?? DEFAULT_CACHE_MAX_SIZE
+        };
+        // Initialize cache instances
+        this._latestStateResolveCache =
+            options?.latestStateCacheOptions?.cache ??
+                createInMemoryCache({
+                    maxSize: this._latestStateCacheOptions.maxSize,
+                    ttl: this._latestStateCacheOptions.ttl
+                });
+        this._stateResolveCache =
+            options?.stateCacheOptions?.cache ??
+                createInMemoryCache({
+                    maxSize: this._stateCacheOptions.maxSize,
+                    ttl: this._stateCacheOptions.replacedTtl
+                });
+        this._rootResolveCache =
+            options?.rootCacheOptions?.cache ??
+                createInMemoryCache({
+                    maxSize: this._rootCacheOptions.maxSize,
+                    ttl: this._rootCacheOptions.replacedTtl
+                });
+        this._gistProofResolveCache =
+            options?.gistProofCacheOptions?.cache ??
+                createInMemoryCache({
+                    maxSize: this._gistProofCacheOptions.maxSize,
+                    ttl: this._gistProofCacheOptions.ttl
+                });
+        this._disableCache = options?.disableCache ?? false;
     }
     /** {@inheritdoc IStateStorage.getLatestStateById} */
     async getLatestStateById(id) {
+        const cacheKey = this.getLatestStateCacheKey(id);
+        if (!this._disableCache) {
+            // Check cache first
+            const cachedResult = await this._latestStateResolveCache?.get(cacheKey);
+            if (cachedResult) {
+                return cachedResult;
+            }
+        }
         const { stateContract } = this.getStateContractAndProviderForId(id);
         const rawData = await stateContract.getStateInfoById(id);
         const stateInfo = {
@@ -50,10 +109,20 @@ export class EthStateStorage {
             createdAtBlock: BigInt(rawData[5]),
             replacedAtBlock: BigInt(rawData[6])
         };
+        !this._disableCache &&
+            (await this._latestStateResolveCache?.set(cacheKey, stateInfo, this._latestStateCacheOptions.ttl));
         return stateInfo;
     }
     /** {@inheritdoc IStateStorage.getStateInfoByIdAndState} */
     async getStateInfoByIdAndState(id, state) {
+        const cacheKey = this.getStateCacheKey(id, state);
+        if (!this._disableCache) {
+            // Check cache first
+            const cachedResult = await this._stateResolveCache?.get(cacheKey);
+            if (cachedResult) {
+                return cachedResult;
+            }
+        }
         const { stateContract } = this.getStateContractAndProviderForId(id);
         const rawData = await stateContract.getStateInfoByIdAndState(id, state);
         const stateInfo = {
@@ -65,6 +134,10 @@ export class EthStateStorage {
             createdAtBlock: BigInt(rawData[5]),
             replacedAtBlock: BigInt(rawData[6])
         };
+        const ttl = stateInfo.replacedAtTimestamp === 0n
+            ? this._stateCacheOptions.notReplacedTtl
+            : this._stateCacheOptions.replacedTtl;
+        !this._disableCache && (await this._stateResolveCache?.set(cacheKey, stateInfo, ttl));
         return stateInfo;
     }
     /** {@inheritdoc IStateStorage.publishState} */
@@ -137,9 +210,17 @@ export class EthStateStorage {
     }
     /** {@inheritdoc IStateStorage.getGISTProof} */
     async getGISTProof(id) {
+        const cacheKey = this.getGistProofCacheKey(id);
+        if (!this._disableCache) {
+            // Check cache first
+            const cachedResult = await this._gistProofResolveCache?.get(cacheKey);
+            if (cachedResult) {
+                return cachedResult;
+            }
+        }
         const { stateContract } = this.getStateContractAndProviderForId(id);
         const data = await stateContract.getGISTProof(id);
-        return {
+        const stateProof = {
             root: BigInt(data.root.toString()),
             existence: data.existence,
             siblings: data.siblings?.map((sibling) => BigInt(sibling.toString())),
@@ -149,12 +230,23 @@ export class EthStateStorage {
             auxIndex: BigInt(data.auxIndex.toString()),
             auxValue: BigInt(data.auxValue.toString())
         };
+        !this._disableCache &&
+            (await this._gistProofResolveCache?.set(cacheKey, stateProof, this._gistProofCacheOptions.ttl));
+        return stateProof;
     }
     /** {@inheritdoc IStateStorage.getGISTRootInfo} */
     async getGISTRootInfo(root, id) {
+        const cacheKey = this.getRootCacheKey(root);
+        if (!this._disableCache) {
+            // Check cache first
+            const cachedResult = await this._rootResolveCache?.get(cacheKey);
+            if (cachedResult) {
+                return cachedResult;
+            }
+        }
         const { stateContract } = this.getStateContractAndProviderForId(id);
         const data = await stateContract.getGISTRootInfo(root);
-        return {
+        const rootInfo = {
             root: BigInt(data.root.toString()),
             replacedByRoot: BigInt(data.replacedByRoot.toString()),
             createdAtTimestamp: BigInt(data.createdAtTimestamp.toString()),
@@ -162,11 +254,24 @@ export class EthStateStorage {
             createdAtBlock: BigInt(data.createdAtBlock.toString()),
             replacedAtBlock: BigInt(data.replacedAtBlock.toString())
         };
+        const ttl = rootInfo.replacedAtTimestamp == 0n
+            ? this._rootCacheOptions.notReplacedTtl
+            : this._rootCacheOptions.replacedTtl;
+        !this._disableCache && (await this._rootResolveCache?.set(cacheKey, rootInfo, ttl));
+        return rootInfo;
     }
     /** {@inheritdoc IStateStorage.getRpcProvider} */
     getRpcProvider() {
         return this.provider;
     }
+    /** enable caching */
+    enableCache() {
+        this._disableCache = false;
+    }
+    /** disable caching */
+    disableCache() {
+        this._disableCache = true;
+    }
     getStateContractAndProviderForId(id) {
         const idTyped = Id.fromBigInt(id);
         const chainId = getChainId(DID.blockchainFromId(idTyped), DID.networkIdFromId(idTyped));
@@ -183,4 +288,16 @@ export class EthStateStorage {
         }
         return network;
     }
+    getGistProofCacheKey(id) {
+        return `gist-${id.toString()}`;
+    }
+    getLatestStateCacheKey(id) {
+        return `latest-${id.toString()}`;
+    }
+    getStateCacheKey(id, state) {
+        return `${id.toString()}-${state.toString()}`;
+    }
+    getRootCacheKey(root) {
+        return root.toString();
+    }
 }