Stellar comes equipped with a cache system, which is allowed to use numbers, strings, arrays and objects. This is a key-value distributed system which makes use of a Redis server and can use any object that is supported by the JSON.stringify function.


In the cache system there are three basic methods to manage the cached objects. These are the methods save, load and destroy.

Add a New Entry

To add a new entry to the cache, you need to use, value, msToExpire); this method also allows you to update an existing entry. The msToExpire can be null if you don’t want the object to expire. As return this method give us a Promise with the newly created object in the cache. If you are updating an existing object, the value will assume the true value.

// create a new cache entry
await'websiteTitle', 'XPTO Website')

Warning: Once msToExpire is reached the entry will be removed from the system, but possibly not at that exact moment.

Get an Entry

To retrieve an entry which is cached, use the method api.cache.load(cache) or api.cache.load(cache, options); options must be an object which can contain the property expireTimeMS which will reset the expiration time of the cached value when it is read.

// try get the `webSiteTitle` entry from the cache.
const data = await api.cache.load('webSiteTitle')

When the Promise is resolved it give an object with the following parameters:

Remove an Entry

To remove a cache entry is as easy as calling the api.cache.destroy(key) method.

await api.cache.destroy('webSiteTitle')


Cache lists have a similar behavior to a queue, the elements are inserted into the tail and removed from the head of the structure. These lists are a great way to store objects that need to be processed in order.


To insert a new element in the list we use the api.cache.push(key, item) method. If the list already exists the new element will be inserted at the end of the list, otherwise a new list will be created.

// add a new element on the `commands` list
await api.cache.push('commands', {player: 'xpto', command: 'exec:abc:param1'})

Warning: you can only save objects which are supported by the JSON.stringify function.


To retrieve an element from the list, you can use the api.cache.pop(key) method. If the list you are looking for does not exist, it returns the null value, otherwise will get the element present at the head of the list.

The following example shows how to pop a element from a list. When the Promise resolves it give us the item present at the head of the list or null if the list does not exist.

// pop an element from the list and save it on the `item` const
const item = await api.cache.pop('commands')


Stellar also allows you to get the size of a list that is cached. If the list does not exist, the value returned is 0. For the size you use the api.cache.listLength(key) function.

// get the `commands` list size and store it on a constant
const size = await api.cache.listLength('commands')

Locking Methods

It is possible, optionally, to use methods to lock editing of objects that are in the cache. These methods are interesting for scenarios where Stellar is running on a cluster, correcting possible concurrency problems.


The api.cache.lock(key, expireTimeMS) method allows you to lock an existing cached object. The list below describes the parameters of the lock method:

The returned promise after resolved give us a boolean value informing whether the lock was obtained.

const lockOk = await api.cache.lock('inTransaction')

if (!lockOk) {
// it was impossible to obtain the lock!

// do something after getting the lock!


To unlock an object you just need use the api.cache.unlock(key) method. The list below describes the parameters of the unlock method:

The returned promise after be resolved give us a boolean value, true if the lock has been removed, false otherwise.

const lockOk = await api.cache.unlock('inTransaction')

if (!lockOk) {
// it was impossible to remove the lock!

// the lock has been removed!

Check Lock

There is also a method to obtain the lock status of a particular object, api.cache.checkLock(key, retry). The list below shows the description of the method parameters:

The returned promise after be resolved give us a boolean value, true or false depending on the lock status.

const lockOk = await api.cache.checkLock('inTransaction')

if (!lockOk) {
// the object does not contain a lock!

// the object is locked!

List of Locks

The api.cache.locks() method allows you get all active locks.

// with this lock we can obtain the list of all locks currently in the system
const locks = await api.cache.locks()