Lantern
Runtime Behavior
Startup
During startup, RPC calls are forwarded to FluxRPC to ensure data freshness. Lantern downloads all configured programs before serving from cache.
Runtime Requests
Cached accounts respond instantly. Uncached accounts forward to FluxRPC. Can optionally cache new accounts on request.
Network Failure
On network issues, Lantern restarts and redownloads all programs. Forwards requests during recovery to prevent stale data.
Shutdown & Restart
After shutdown or crash, Lantern must download updates to all cached programs from FluxRPC on the next startup.
Startup
During startup, any RPC calls made to Lantern will not use cached data. The calls will be forwarded on to FluxRPC to ensure the data you receive cannot be out-of-date.
On startup, Lantern will fully update each program that you have defined in the config file. These are often large data calls — FluxRPC is fast, but this can still take a while. Lantern will notify you when startup is complete.
Requesting New Accounts During Runtime
If you request an account being cached by Lantern, it will respond very quickly using cached data. No external RPC call needs to be made.
If Lantern is not caching the account you request, it will forward the request to FluxRPC. You will be billed normally for this request.
Optionally, Lantern can begin caching that account, even if it belongs to a program not defined in the configuration file. This behavior is controlled by the configuration file and can be disabled. It is disabled by default. To enable it, set "cache_requests" to true in your config file.
This is the recommended way to use Lantern to cache data on accounts in very large programs, such as the System Program or either of the Token programs. Note that keeping these accounts up-to-date can cost significant bandwidth. A Scale plan at FluxRPC is recommended.
Dropping Accounts from Local Cache During Runtime
If you have set "cache_requests":true, Lantern will cache and keep up-to-date any accounts you request via getAccountInfo or getMultipleAccounts, even if they are not owned by a program Lantern is set to store.
If you wish to drop an account added this way from cache, you can make a HTTP DELETE request to /api/account/{publicKey}. For example, if you are accessing Lantern on your local computer on port 8080, and wish to stop caching the Sysvar Clock account, you could make the following request with curl:
curl --location --request DELETE 'http://localhost:8080/api/account/SysvarC1ock11111111111111111111111111111111'
Once complete, Lantern will no longer cache that account or receive updates to it (saving bandwidth). If you request the account again via getAccountInfo or getMultipleAccounts, Lantern will begin caching it again. Note that there is a little latency to complete the DELETE request.
When Lantern is configured to store all accounts belonging to one or more programs, this feature cannot be used to remove accounts owned by those programs.
WebSockets
Subscribing to an account or program that Lantern is caching will work normally.
The exact behavior of WebSockets when requesting an account or program Lantern is not caching depends on the cache_requests entry in your Lantern configuration.
cache_requests = True
Subscribing to an uncached account will cause Lantern to fetch and begin caching it. Afterwards, it works as expected. Note: caching System or Token Program accounts can consume significant bandwidth — a Scale plan at FluxRPC is recommended.
Subscribing to an uncached program will fail (returns "not found"). To subscribe to a program, add it to your config file explicitly.
cache_requests = False
Subscribing to an account or program that Lantern is not currently caching will fail (returns "not found").
Regardless of configuration, trying to subscribe to an account or program that does not exist will fail (returns "not found").
Network Failure
If Lantern experiences a network failure where it could have out-of-date data, it goes through the startup sequence again. It will only fetch any accounts updated during the network failure.
Until this is finished, it will forward any requests you make to FluxRPC. This ensures Lantern won't respond with out-of-date data.
Shutdown and Restart
If you shut down Lantern or it crashes, you will need to go through startup again. If you have existing stored data in your data folder, Lantern will only fetch new data that you are missing from disk. If you delete Lantern's data files, it will need to do a complete fetch again.