Skip to main content

Configure caching

Learn how to configure system caching.

The Core uses a caching layer to hold certain entities in temporary storage. This optimizes the system to reduce the volume of HTTP calls and enables mobile devices, both wallets and mobile verifiers, to use stored entities where internet connections are intermittent.

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
ParameterTypeDescription
cacheTypeDB | IN_MEMORYDB: Stores cached entities in the configured database for persistence.
IN_MEMORY: Stores cached entities in RAM for faster access.
refreshAfternumberTime, in seconds, after which the cache provider automatically refreshes an entry when it's retrieved.
cacheRefreshTimeoutnumberMaximum time, in seconds, the system will wait when refreshing an entry before returning an error.
cacheSizenumberMaximum 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 the DELETE method on the /api/cache/v1 endpoint, 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 a held credential and that credential uses a list-based revocation method, the system normally calls into the cache to retrieve both the signed list containing the credential's status and the DID document containing the public key used to sign the list.

In order to get fresh credential validity information, use the forceRefresh parameter during revocation check. The system will then attempt to fetch the resources externally, returning success: false in the response if unsuccessful. If the resources are successfully fetched externally, they are inserted into the cache.

This applies to the following revocation methods:

  • BITSTRINGSTATUSLIST
  • TOKENSTATUSLIST

The Procivis One Wallet can also receive credentials that use the "Verifiable Credentials Status List 2021" revocation method. The credential validity information for these credentials is not handled by the cache.

Cached Entities​

The following entities are handled by the cache provider:

STATUS_LIST_CREDENTIAL​

For credentials issued with a status list type of revocation method, wallets and verifiers use the cache layer to manage credential status.

This includes the following revocation methods:

  • BITSTRINGSTATUSLIST
  • TOKENSTATUSLIST

When the signed list is accessed from the list URL, it is saved in the cache. The cache entry can be configured to reduce calls to the issuer's status list within a defined tolerance for the freshness of status information.

For wallets, force a refresh to force external retrieval.

DID_DOCUMENT​

For DIDs that must be resolved with web calls (did:web, for example), the cache layer is used to store DID documents. This provides public keys for verifying signed tokens. The cache entry can be configured to reduce calls to the web for public key retrieval within a defined tolerance for the freshness of public keys.

For wallets, force a refresh to force external retrieval.

JSON_LD_CONTEXT​

For W3C VCs, the context describes the structure and fields expected of credentials of that type and is used in calculating proofs. The cache entry can be configured to reduce calls to the web within a defined tolerance for the freshness of JSON-LD contexts, documents that are not expected to change.

VCT_METADATA​

SD-JWT VCs carry Type Metadata in the vct claim which can include human-readable information about the type of credential, a schema defining the structure of the credential and information on how to display the credential in the holder's wallet. This metadata is stored in the cache layer.

For vcts not retrievable via the HTTP GET method, type metadata can be saved as a static resource. Add a vct to the /resource/sd_jwt_vc_vcts.json file in the system repository. When the Core is initialized, the types in the file are loaded into the cache as persistent entities.

JSON_SCHEMA​

SD-JWT VCs carry schema information, used for data validation, in schema or retrievable via the resource in schema_uri. These schemas are stored in the cache layer.

JSON schemas can be saved as a static resource. Add schemas to the /resource/sd_jwt_vc_schemas.json file in the system repository. When the Core is initialized, the types in the file are loaded into the cache as persistent entities.

TRUST_LIST​

For the Procivis One Trust Registry, subscribed trust anchors are cached and incoming issuer and verifier DIDs are checked against this list to determine whether they are trusted.