Cache management

Optimize cache usage for faster debugging and offline analysis

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:

1. Identify oldest files
2. Erst scans the cache and identifies the least recently accessed files.
3. Prompt for confirmation
4. You’re asked to confirm before deletion:
5. Will delete 234 files (156.32 MB)
   Continue? (yes/no):
   

6. Delete until target reached
7. 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:

1. Lists all cached files with access times
2. Sorts by least recently used
3. Deletes files until size drops to 50% of maximum
4. 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:

1. Check cache size
2. erst cache status
   

3. Clean aggressively
4. # Remove entries older than 7 days
   erst cache clean --older-than 7 --force
   
   # Or clear everything
   erst cache clear --force
   

5. Reduce maximum size
6. Modify DefaultConfig() in source code to lower the limit.

Selective retention

Preserve important cached data:

1. Backup specific transactions
2. cp ~/.erst/cache/transactions/abc123...def.xdr ~/backups/
   

3. Clean cache
4. erst cache clean --force
   

5. Restore backups
6. 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 ~/

Share cache with team

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