Cache management

Erst maintains a local cache of transaction data and simulation results to improve performance and enable offline analysis. This guide covers cache configuration, maintenance, and optimization strategies.

Overview

The cache stores:

Transaction envelopes fetched from RPC
Ledger footprint data (read/write sets)
Simulation results and traces
Contract WASM bytecode
Source maps and debug symbols

Caching provides:

Faster repeated debugging of the same transaction
Offline analysis after initial data fetch
Reduced RPC load and bandwidth usage
Consistent results across debugging sessions

Cache location

Default cache directory:

~/.erst/cache/

Customize with environment variable:

export ERST_CACHE_DIR=/path/to/custom/cache

The cache directory is created automatically on first use.

Cache commands

Check cache status

View cache size and usage statistics:

erst cache status

Example output:

Cache directory: /home/user/.erst/cache
Cache size: 342.58 MB
Files cached: 1,247
Maximum size: 1.00 GB

If cache exceeds the limit:

[!]  Cache size exceeds maximum limit. Run 'erst cache clean' to free space.

Clean old entries

Remove old cached files using LRU (Least Recently Used) strategy:

erst cache clean

What happens:

Identify oldest files

Erst scans the cache and identifies the least recently accessed files.

Prompt for confirmation

You’re asked to confirm before deletion:

Will delete 234 files (156.32 MB)
Continue? (yes/no):

Delete until target reached

Files are deleted until cache size is reduced to 50% of maximum.

Skip confirmation:

erst cache clean --force

Clear all cache

Delete all cached files:

erst cache clear

This action cannot be undone. All cached transaction data will be permanently deleted.

Skip confirmation:

erst cache clear --force

RPC cache management

Erst also maintains a separate SQLite database for RPC fetch results:

~/.erst/cache.db

This cache stores network responses for:

Transaction envelopes
Ledger entries
Contract code
Network metadata

Clean RPC cache by age

Remove entries older than N days:

erst cache clean --older-than 7

Example: Remove all entries older than 7 days.

Clean RPC cache by network

Remove entries for a specific network:

erst cache clean --network testnet

Useful when:

Testnet resets
Switching development focus
Freeing space from old test data

Combine filters

Remove testnet entries older than 30 days:

erst cache clean --older-than 30 --network testnet

Clear all RPC cache

Remove all RPC cache entries:

erst cache clean --all

At least one filter must be specified when cleaning RPC cache: --older-than, --network, or --all.

Cache configuration

Maximum size

Default maximum cache size: 1 GB Configure via code in internal/cache/cache.go:

func DefaultConfig() Config {
    return Config{
        MaxSizeBytes: 1 << 30, // 1 GB
        // ...
    }
}

LRU strategy

When cleaning, Erst:

Lists all cached files with access times
Sorts by least recently used
Deletes files until size drops to 50% of maximum
Preserves recently accessed files

File organization

Cache files are organized by type:

~/.erst/cache/
├── transactions/
│   ├── abc123...def.xdr
│   └── 789def...123.xdr
├── ledgers/
│   ├── 12345.json
│   └── 12346.json
├── contracts/
│   ├── CDLZFC3...wasm
│   └── CAP5UY4...wasm
└── sourcemaps/
    ├── CDLZFC3...map
    └── CAP5UY4...map

Cache behavior

When cache is used

Erst uses cached data when:

Debugging the same transaction multiple times
Working offline (no network access)
RPC endpoints are slow or rate-limited
Session is resumed from saved state

When cache is bypassed

Erst fetches fresh data when:

Cache entry doesn’t exist
Cache entry is corrupted
Explicit cache bypass flag is used
Network status has changed

Cache invalidation

Cache entries never expire automatically during use. They’re only removed:

During manual cleaning (erst cache clean)
When maximum size is exceeded
When manually cleared (erst cache clear)
When LRU cleanup runs

Transaction data on Stellar is immutable, so cached transactions remain valid indefinitely.

Optimization strategies

Regular maintenance

Schedule periodic cache cleaning:

# Weekly cron job
0 0 * * 0 erst cache clean --force --older-than 30

Cleans entries older than 30 days every Sunday.

Network-specific cleanup

After testnet resets:

# Clear all testnet data
erst cache clean --network testnet

# Verify cleanup
erst cache status

Disk space management

If running low on disk space:

Check cache size

erst cache status

Clean aggressively

# Remove entries older than 7 days
erst cache clean --older-than 7 --force

# Or clear everything
erst cache clear --force

Reduce maximum size

Modify DefaultConfig() in source code to lower the limit.

Selective retention

Preserve important cached data:

Backup specific transactions

cp ~/.erst/cache/transactions/abc123...def.xdr ~/backups/

Clean cache

erst cache clean --force

Restore backups

cp ~/backups/abc123...def.xdr ~/.erst/cache/transactions/

Performance impact

Cache hit vs miss

Scenario	Time	Network	Use Case
Cache hit	~50ms	None	Instant debugging
Cache miss	~2-5s	Required	First-time fetch
Slow RPC	~10-30s	Required	Rate-limited endpoints
Offline	Fails	None	No cached data

Storage efficiency

Typical sizes:

Transaction envelope: 1-5 KB
Ledger footprint: 10-100 KB
Contract WASM: 50-500 KB
Source map: 20-200 KB
Simulation results: 5-50 KB

100 cached transactions ≈ 10-100 MB 1000 cached transactions ≈ 100 MB - 1 GB

Monitoring cache health

Check for corruption

If you encounter errors loading cached data:

# Clear cache and refetch
erst cache clear --force
erst debug <tx-hash>  # Refetches from network

Verify file integrity

Manually inspect cache files:

# List cache contents
ls -lh ~/.erst/cache/transactions/

# Check file sizes (should be non-zero)
find ~/.erst/cache -type f -size 0

# Remove zero-byte files
find ~/.erst/cache -type f -size 0 -delete

Track cache growth

Monitor cache size over time:

# Create monitoring script
#!/bin/bash
du -sh ~/.erst/cache >> cache-size.log
date >> cache-size.log

# Run daily
crontab -e
# Add: 0 0 * * * /path/to/monitor-cache.sh

Troubleshooting

Cache not working

Error: failed to write cache file

Solutions:

Check disk space: df -h
Verify permissions: ls -la ~/.erst/cache
Create directory manually: mkdir -p ~/.erst/cache
Check environment variable: echo $ERST_CACHE_DIR

Cache size incorrect

Cache size: -1 B

Solutions:

Clear cache and rebuild: erst cache clear --force
Check for filesystem errors: dmesg | grep -i error
Verify cache directory exists: ls ~/.erst/cache

Permission denied

Error: permission denied: ~/.erst/cache

Solutions:

Fix ownership: sudo chown -R $USER ~/.erst/cache
Fix permissions: chmod -R 755 ~/.erst/cache
Check SELinux/AppArmor: sestatus or aa-status

Database locked

Error: database is locked: cache.db

Solutions:

Close other Erst processes
Remove lock file: rm ~/.erst/cache.db-shm ~/.erst/cache.db-wal
Wait and retry

Advanced usage

Pre-populate cache

Fetch multiple transactions into cache:

#!/bin/bash
# Cache common transactions
for tx in "abc123..." "def456..." "789abc..."; do
    erst debug $tx > /dev/null 2>&1
    echo "Cached: $tx"
done

Export cache data

Create portable cache archive:

# Archive cache
tar -czf erst-cache-backup.tar.gz ~/.erst/cache/

# Restore on another machine
tar -xzf erst-cache-backup.tar.gz -C ~/

Distribute cache for offline work:

# Create shareable cache
erst debug tx1 tx2 tx3  # Populate cache
tar -czf team-cache.tar.gz ~/.erst/cache/

# Team members extract
tar -xzf team-cache.tar.gz -C ~/

Implementation details

Source files

Cache management is implemented in:

internal/cache/cache.go - Core cache logic
internal/cmd/cache.go - CLI commands
internal/rpc/cache.go - RPC-specific caching

Key functions

File cache:

Manager.GetCacheSize() - Calculate total cache size
Manager.ListCachedFiles() - List all cached files
Manager.Clean() - Run LRU cleanup

RPC cache:

CleanByFilter() - Clean with age/network filters
CleanAll() - Clear entire RPC cache

Location: internal/cmd/cache.go:26, internal/cache/cache.go

Next steps

Working with sessions

Sessions complement caching for persistent debugging

Debugging failed transactions

Learn how caching speeds up transaction debugging

Local WASM replay

Test locally without relying on cached network data

Get Started

Core Features

Guides

Configuration

Advanced

​Overview

​Cache location

​Cache commands

​Check cache status

​Clean old entries

​Clear all cache

​RPC cache management

​Clean RPC cache by age

​Clean RPC cache by network

​Combine filters

​Clear all RPC cache

​Cache configuration

​Maximum size

​LRU strategy

​File organization

​Cache behavior

​When cache is used

​When cache is bypassed

​Cache invalidation

​Optimization strategies

​Regular maintenance

​Network-specific cleanup

​Disk space management

​Selective retention

​Performance impact

​Cache hit vs miss

​Storage efficiency

​Monitoring cache health

​Check for corruption

​Verify file integrity

​Track cache growth

​Troubleshooting

​Cache not working

​Cache size incorrect

​Permission denied

​Database locked

​Advanced usage

​Pre-populate cache

​Export cache data

​Share cache with team

​Implementation details

​Source files

​Key functions

​Next steps

Working with sessions

Debugging failed transactions

Local WASM replay

Overview

Cache location

Cache commands

Check cache status

Clean old entries

Clear all cache

RPC cache management

Clean RPC cache by age

Clean RPC cache by network

Combine filters

Clear all RPC cache

Cache configuration

Maximum size

LRU strategy

File organization

Cache behavior

When cache is used

When cache is bypassed

Cache invalidation

Optimization strategies

Regular maintenance

Network-specific cleanup

Disk space management

Selective retention

Performance impact

Cache hit vs miss

Storage efficiency

Monitoring cache health

Check for corruption

Verify file integrity

Track cache growth

Troubleshooting

Cache not working

Cache size incorrect

Permission denied

Database locked

Advanced usage

Pre-populate cache

Export cache data

Share cache with team

Implementation details

Source files

Key functions

Next steps