Caching

Set which entities are stored and the system cache and how memory is handled with the cacheEntities object.

Cache operations and management

How caching works

For those entities managed through the cache, the cache provider retrieves one of: a cached version of the entity, a new version of the entity, or an error.

When retrieving an entity, the system checks the cache first. If the entity is in the cache and the time since it was created has not exceeded the refreshAfter time, the cache provider retrieves the cached entity.

If the age of the cached entity is greater than the refreshAfter value, the system attempts to refresh the cache entry. If the cache entry is successfully updated, this new entity is retrieved. If the refresh fails, the cache provider returns the existing cached entity unless its age has exceeded the value of cacheRefreshTimeout, in which case it returns an error.

The cache provider maintains a maximum cacheSize by deleting the entry with the fewest retrievals; in cases of entries with an equal number of retrievals, the system deletes the oldest entries.

Cache configuration

The settings of the cache provider determine how these entities are managed. Each entry in the cache provider follows a similar pattern:

cacheEntities:
  ENTITY_TYPE:
    cacheType: DB
    refreshAfter: 86400
    cacheRefreshTimeout: 172800
    cacheSize: 1000

Parameter	Type	Description
cacheType	DB , IN_MEMORY	DB: Stores cached entities in the configured database for persistence. IN_MEMORY: Stores cached entities in RAM for faster access.
refreshAfter	number	Time, in seconds, after which the cache provider automatically refreshes an entry when it's retrieved.
cacheRefreshTimeout	number	Maximum time, in seconds, the system will wait when refreshing an entry before returning an error.
cacheSize	number	Maximum number of entries that can be stored in the cache at one time.

Prune the cache

Cache entries can be deleted to force the system to retrieve external resources during the next retrieval. This can be helpful for testing purposes.

Use DEL /api/cache/v1, specifying in an array which of the cache entities to prune. If no cache entities are passed, the entire cache is pruned.

Force a refresh

When a wallet checks the revocation status of held credentials, the system may retrieve required resources from the cache. To force the system to fetch these resources from their external sources instead, use the forceRefresh parameter during a revocation check. If the external fetch succeeds, the cache is updated with the fresh data. If it fails, the response returns success: false.

• See the API → Check revocation status

This option is available for revocation methods that rely on remotely hosted resources. See the cached entities reference for which entity types support force refresh.

Cached entities

For a reference of all available entity types, see System cache in the Core configuration reference.