Cosmos SDK Integration

This guide covers how to integrate the memlogger-enabled Cosmos SDK into your blockchain project.

Understanding the Integration

The memlogger is integrated directly into the Cosmos SDK as a single, self-contained commit. This approach ensures:

• Minimal changes to the core SDK
• Easy upgrades to newer SDK versions
• Compatibility with existing SDK features
• Production stability with proven performance

Integration Options

Option 1: Use Pre-built Release (Recommended)

BFT Labs maintains pre-built releases of popular Cosmos SDK versions with memlogger already integrated.

Available Releases

• v0.53.4-bft-labs-memlogger
• Check all releases for other versions

Implementation

Add these replace directives to your go.mod:

replace (
    github.com/cosmos/cosmos-sdk => github.com/bft-labs/cosmos-sdk v0.53.4-bft-labs-memlogger
    cosmossdk.io/log => github.com/bft-labs/cosmos-sdk/log v0.0.0-20250101000000-2a53c378ae57
    cosmossdk.io/store => github.com/bft-labs/cosmos-sdk/store v0.0.0-20250101000000-2a53c378ae57
)

Then run:

go mod tidy

Option 2: Cherry-pick Integration Commit

If you need a custom SDK version or maintain your own fork, you can cherry-pick the memlogger integration commit.

Step 1: Add BFT Labs Remote

cd /path/to/your/cosmos-sdk
git remote add bft-labs https://github.com/bft-labs/cosmos-sdk.git
git fetch bft-labs

Step 2: Cherry-pick the Commit

git cherry-pick 2a53c378ae5734c834fa7f7187a6c672d3d79521

Step 3: Resolve Any Conflicts

If there are conflicts (unlikely), resolve them and continue:

# After resolving conflicts
git add .
git cherry-pick --continue

Step 4: Update Your Module

In your chain’s go.mod, add replace directives pointing to your fork:

replace (
    github.com/cosmos/cosmos-sdk => /path/to/your/cosmos-sdk
    // or use your remote fork:
    // github.com/cosmos/cosmos-sdk => github.com/your-org/cosmos-sdk v0.0.0-yourtag
 
    cosmossdk.io/log => github.com/your-org/cosmos-sdk/log v0.0.0-20250101000000-2a53c378ae57
    cosmossdk.io/store => github.com/your-org/cosmos-sdk/store v0.0.0-20250101000000-2a53c378ae57
)

Note: The commit hash 2a53c378ae57 references the memlogger integration commit.

Verify Integration

After integrating, verify the memlogger is available:

# Check if the memlogger package exists
go list github.com/cosmos/cosmos-sdk/log/memlogger

You should see no errors.

What’s Included

The memlogger integration adds:

• memlogger package: Core logging implementation with compression and WAL
• Filter system: Configurable message filtering for consensus-critical events
• Configuration options: Tunable parameters for memory limits and flush intervals
• Performance optimizations: Object pooling and zero-allocation design

Performance Impact

Based on production testing:

• Memory: Slight increase (configurable, typically 10-50MB)
• CPU: Negligible impact (async compression)
• Disk I/O: Minimal (compressed, batched writes)
• Network: None (local processing only)

See benchmark results for detailed metrics.

Next Steps

Now that you have the Cosmos SDK with memlogger integrated, continue to:

1. Application Setup - Add streaming listeners to your app.go
2. Node Configuration - Configure your node’s settings

Reference

• Integration commit: 2a53c378
• BFT Labs Cosmos SDK: github.com/bft-labs/cosmos-sdk
• Performance benchmarks: PR #1 Comment