Bringing CKB Light Client to Mobile devices(Android and IOS): Current Limitations, Findings, and a Path Toward a Mobile Ready P2P Standard

[Jnr6]

Hi everyone,
I’m Jr, currently part of the CKBuilders cohort, working on integrating a CKB Light Client into an Android application. I wanted to share my progress, the challenges I’ve encountered, and get community input on whether now is the right time to deliberately move toward a mobile-ready P2P standard for CKB.

What I’ve Accomplished So Far

Over the last few months, I’ve been working on:

• Experimenting with both the Rust-native and WASM/browser light client implementations.

• Attempting to compile and run the Rust light client directly on Android through the NDK.

• Attempting to embed the browser WASM version inside an Android environment (Web View [i haven’t tried WebKit yet ]).

• Building a practical mobile wallet flow: account generation, script tracking, balance queries, and transaction building/signing.

Where Things Started Breaking Down.

Through this process, I hit multiple structural blockers:

1. Tentacle’s P2P layer currently doesn’t work on Android

While the Rust light client builds successfully, the P2P layer fails at runtime. Tentacle/ckb-network relies on behaviors and APIs that are not compatible with Android’s networking stack. This prevents the node from fully starting or maintaining peer sessions.

2. The browser WASM light client cannot run in Android WebView

The browser implementation requires:

• SharedArrayBuffer

• Atomics.wait

• Worker-based IndexedDB storage

• COOP + COEP headers for cross-origin isolation

Android Web View cannot supply this environment. So the browser light client cannot be embedded into a mobile wallet.

3. Neither current implementation is designed with mobile constraints in mind

Mobile has strict limitations around:

• Background execution

• Long-lived TCP

• Resource usage (battery, disk, IO)

• Sandboxed file systems

Even if Tentacle ran, RocksDB + full P2P gossip would be a heavy burden for typical mobile users.

My Conclusion So Far

The existing light client implementations both Rust and WASM are excellent for desktop/browser, but they cannot currently serve as a foundation for a production mobile light client.

A mobile client probably needs:

• A different networking strategy (QUIC / WebSocket / mobile-safe P2P)

• A lighter storage backend (SQLite instead of RocksDB / IndexedDB)

• A redesigned sync model that respects Android/iOS lifecycle

• A modular core that can target Rust/WASM/Android/iOS from the same codebase

This is not a small patch; what we need is architectural chnage.

Why I’m Bringing This Up Now

Recently Jan commented on a thread imagining HashLottery running as a fully client-side Android P2P application.
This is exactly the kind of experience we want long-term, but based on my work the last few months, I believe:

CKB needs a new or adapted P2P standard and a mobile-first architecture to make on-device light clients realistic.

Right now, the path is blocked at a fundamental level.

My Proposal

I’d like to:

1. Start a collaborative discussion on what a mobile-capable light client should look like.

2. Contribute my findings to help define the requirements.

I believe this kind of project would significantly grow the CKB ecosystem, enabling:

• Serverless mobile apps,

• Wallets with true on-chain verification (not relying on RPC services),

• Better decentralization,

• New P2P use cases like HashLottery.

Looking for Feedback

• Does the community agree that mobile support requires a dedicated effort?

• Are other builders or core team members interested in collaborating?

• Are there existing discussions or research efforts I should be aware of?

• Would this be an appropriate target for a Nervos grant?

Excited to hear everyone’s thoughts.
If we can solve this, CKB mobile experiences could reach a whole new level.

Jr.
CKBuilders Cohort

[neon.bit]

Thank you @Jnr6 for your diligence and perseverance in working on this. Bringing CKB to mobile in this way could significantly broaden the possibilities for mobile applications and, at the very least, makes it easier to grow the network of nodes.

I look forward to seeing the feedback to your ideas as a springboard for further progress

[Jnr6]

Thank you @neon.bit for your guidance

[chenyukang]

@Jnr6

A member from the CKB team here.

Thanks for your work on this part, it’s meaningful to explore CKB on the mobile platform!

Can you share with us more details on these parts:

1. What’s the specific error for using p2p layer on Android, is there any error code or message? we need to understand better to this part: Tentacle/ckb-network relies on behaviors and APIs that are not compatible with Android’s networking stack.Have you tried to use ws? To keep task running in background without be killed, it seems we need to investigate the solution such as Foreground Service, whether it’s TCP or UDP network layer, both need to follow the working style of mobile platform, or adapt a workaround for the background task interruption, which involves reconnecting after re-entering.
2. For RocksDB, with the scenario without too much data writing such as CKB light client, why is it still too heavy for mobile, What specific obstacles did you encounter?

There is an early proposal within our team to investigate QUIC(or other UDP) as network layer, but it’s still in a very early stage.

[Jnr6]

Hi @chenyukang,

Thanks so much for the response and for taking the time to help investigate this! I really appreciate the CKB team’s engagement. Let me provide more specific details about what I’ve encountered.

1. Specific Error with Tentacle P2P Layer on Android

The tricky part here is that there’s no traditional error message or exception. Instead, what I’m seeing is a silent failure where Tentacle appears to initialize successfully but never actually establishes peer connections.

What works:

• The Rust light client compiles successfully for all Android architectures (ARM64, ARMv7, x86_64, x86)

• NetworkService::start() returns successfully without errors

• NetworkController reports is_active() = true

• No crashes or panics occur

What fails (silently):

• Zero peer connections after 2+ minutes of monitoring

• No dial attempts appear to happen (no tentacle service logs appear)

• connected_peers() returns empty indefinitely

• Both outbound and inbound connection counts stay at 0

Here’s the log pattern I consistently see:

[INFO] 🚀 Starting network service...
[INFO] 📝 About to call NetworkService::new().start()
[INFO] ✅ NetworkService::start() returned successfully
[INFO] ✅ Tentacle service is now running
[INFO] 📍 Initial Network State:
       Node ID: QmXxxxxx...
       Active: true
       Connected peers: 0

[After 60 seconds]
[ERROR] ❌ CRITICAL: No peers after 60 seconds
[ERROR] This strongly suggests Tentacle is NOT working on Android

My network configuration is straightforward:

NetworkConfig {
    listen_addresses: vec![],  // No listening (mobile-only outbound)
    bootnodes: vec![
        "/ip4/18.217.146.65/tcp/8111/p2p/QmT6DFf...",  
       // 10 CKB testnet bootnodes
        // ... 9 more
    ],
    max_outbound_peers: 8,
    connect_outbound_interval_secs: 15,
    transport: TransportType::Tcp,
}

2. Have I Tried WebSocket (ws)?

No, I haven’t tried WebSocket transport yet. My implementation currently uses standard TCP:

TransportType::Tcp

Questions for you:

1. Does Tentacle support WebSocket transport on mobile platforms?
2. If yes, what’s the correct way to configure it? I see the TransportType enum but I’m not sure if WebSocket is available or how to enable it.
3. Would switching to WebSocket potentially solve these connection issues on Android?

I’m absolutely willing to test WebSocket if that’s a recommended approach for mobile!

3. Why RocksDB is Still Too Heavy for Light Client on Mobile

You asked about RocksDB specifically. Here are the concrete obstacles I’ve hit:

A. Build Complexity

• RocksDB requires compiling 200+ C++ files for each Android architecture
• Build time: ~45-50 minutes for all 4 architectures (ARM64, ARMv7, x86, x86_64)
• Requires NDK r21+ with specific toolchain configurations
• Frequent build cache invalidation causes full rebuilds

B. Binary Size

• RocksDB adds ~8-12 MB per architecture to APK size
• For 4 architectures: 32-48 MB just for the database component
• This is unacceptable for a mobile wallet where users expect <50 MB total app size
• In fact, it is an issue for me to push this to GitHub because it is heavy

C. Runtime Performance

• RocksDB assumes desktop-class I/O (NVMe SSDs)
• Mobile flash storage is significantly slower, especially on budget devices
• Compaction operations can block for seconds, freezing the UI
• Background compaction drains battery rapidly

D. Storage Pattern Mismatch

• Light client writes are infrequent (only during sync)
• RocksDB is optimized for write-heavy workloads (overkill for light client)
• SQLite/Room is better suited for mobile’s read-heavy, low-write pattern

My suggested solution has been to implement a custom Android-native storage layer using Room (which is an abstraction of SQLite) that:

• Compiles in seconds (no C++ dependencies)
• Adds <500 KB to APK
• Integrates natively with Android’s lifecycle
• Works perfectly for light client data (headers, scripts, cells)

However, I want to emphasize that the storage layer is completely irrelevant to the P2P connection issue. Even with RocksDB completely bypassed, Tentacle still fails to establish peer connections on Android.

4. About Background Tasks and Foreground Service

You mentioned Foreground Service for keeping tasks running in the background. I’m definitely aware of this requirement, but I don’t think it’s related to the initial connection failure I’m seeing.

My current testing environment:

• App is actively in the foreground during all tests
• WakeLock is acquired to prevent device sleep
• All network permissions are properly granted:

The connection failure happens immediately, even while I’m actively using the app and staring at the screen, so Android’s background task restrictions aren’t the issue here.
That said, once I get initial connections working, I’ll absolutely need to implement:

• Foreground Service for sync continuation when app is backgrounded

• Reconnection logic after network changes

• Proper handling of device sleep/wake cycles

You’re right that whether it’s TCP or UDP, both need to follow Android’s working style for background execution.

5. What I’ve Tested So Far

To isolate the issue, I built network diagnostics:

Network connectivity tests:

• Raw TCP connection to bootnodes (port 8111): SUCCESS

• Tokio async TCP connection: SUCCESS

• DNS resolution of multiaddrs: SUCCESS

• Tentacle P2P connection: FAILURE (zero peers)

This proves the network path is clear from my Android device to the CKB bootnodes. Standard TCP sockets work fine. But something in Tentacle’s implementation doesn’t translate to the Android environment.

Summary & How I Can Help

What I need help understanding:

1. WebSocket Transport: How do I configure Tentacle to use WebSocket on Android instead of TCP?

2. Tentacle Mobile Debugging: Are there hidden debug logs or trace flags I can enable to see what’s happening inside Tentacle?

I’m fully committed to making CKB light client work on mobile and I’m happy to work closely with the core team on debugging and testing whatever is needed.

Thanks again for your time and support!

Jr
CKBuilders Cohort

[chenyukang]

Thanks @Jnr6 for your detailed and useful information.

We will conduct further investigation into the Tentacle issue.

Let us take some time to try to fix P2P issue, it’s still a better way compared to WebSocket approach.

For the rocksdb, I agree that compiling cost and size is a blocker for the mobile side.

Honestly, we haven’t got lot of experience for the mobile development yet, but yes, it’s important for the light client scenarios. I will reply you later.

[Jnr6]

Thank you @chenyukang, in the meantime I’ll be here, thank you for your response

[chenyukang]

Hi @Jnr6

We have more investigation on LightClient for Android, we have found after disabling the doze for emulator, LightClient can work as normal.
Could you have a try for this solution?