Skip to content
Snippets Groups Projects
Select Git revision
0 results
Blame Permalink
vd-wallet-sdk-android.md 13.48 KiB 
layout: wip
title: Wallet SDK for Android
author: valldrac
date: May 17, 2023
amount: 295
milestones:
  - name: Development
    funds: 180 XMR
    done: 4 March 2024
    status: finished
  - name: Security Enhancements
    funds: 24 XMR
    done: 12 August 2024
    status: finished
  - name: Continuous Integration & Testing
    funds: 51 XMR
    done:
    status: unfinished
  - name: Maintenance (3 months)
    funds: 20 XMR
    done:
    status: unfinished
  - name: Maintenance (3 months)
    funds: 20 XMR
    done:
    status: unfinished
payouts:
  - date: 21 March 2024
    amount: 180
  - date: 14 August 2024
    amount: 24
  - date:
    amount:
  - date:
    amount:
  - date:
    amount:

Deadline update: July 1, 2025

Prior to the deadline, the proposer MUST provide regular updates on their progress as per the CCS rules.

If the provided updates/progress (or lack thereof) is unsatisfactory, all remaining funds can be relinquished either before or after the deadline.

The community will then seek another person/team to take over. If this cannot be accomplished within a reasonable timeframe, the funds will be repurposed or reallocated to a similar proposal (subject to community consensus).

Summary

We propose supporting the development of the new Monero SDK for Android that the Molly.im team is actively working on.

The goal of this SDK is to provide a solution for developers to integrate Monero into their apps by offering an Android wallet library and a sample app. The library will include advanced features such as support for multiple wallets, sandboxed C++ code, client-side load balancing and asynchronous API. It will be compatible with Android Studio and fully optimized for size and performance. The demo app will feature the capabilities of the library, using the best practices and tools.

The development of this SDK aims to resolve issues found in existing libraries during the integration of Monero into Molly. If you would like to know the rationale behind this SDK, and learn about the Molly project and background, we recommend checking out our CCS titled "Decentralizing Molly.im to support Monero payments" and the latest follow-up at the following links: CCS proposal and update post.

SDK Overview

The Monero SDK consists of two components:

  1. Android Library: A specialized library that allows developers to interact with the Monero network and perform wallet operations. This library is written in Kotlin and offers a reliable asynchronous API.

  2. Sample Wallet App: An example app written in Kotlin that showcases the usage of the library for wallet app development. It serves as an integration guide for developers and facilitates the testing of new functionalities.

Android Library

The Android library is the core component of the SDK. Internally it wraps and extends the wallet2 low-level API.

Key features and design decisions of the Android library include:

  • Kotlin Language: The library is implemented in Kotlin, which is the preferred language for Android development. Kotlin's interoperability with Java ensures compatibility with existing apps.

  • Asynchronous API: It leverages Kotlin's Coroutines support for asynchronous programming, providing a reliable and non-blocking API that seamlessly integrates with Android's event-driven development model.

  • Sandboxed Execution: All non-memory-safe code (C++) runs within an isolated process with zero privileges and restricted access to the host app or system resources. Even if a remote execution exploit affects Monero, it becomes extremely difficult for an attacker to elevate privileges to the system or host app.

  • Modular Architecture: The library is built as an Android service, using Android's AIDL interprocess communication (IPC) to connect the Kotlin layer with the sandboxed native code. This client-server architecture decouples the internal wallet2 implementation from the public API of the SDK, facilitating future swapping of the wallet2 module without major changes to the API. This enables smoother migration to Seraphis for developers using our SDK.

  • Storage Abstraction: The library provides a storage abstraction layer, simplifying wallet persistence for developers. It allows the SDK to be agnostic about the underlying storage mechanism (files, database, cloud, etc.). This flexibility enables developers to improve data-at-rest encryption without modifying the SDK code.

  • Network Client Injection: Instead of relying on the networking code of wallet2, the SDK allows the app to provide its own HTTP client. This gives the app the freedom to support any transport protocol, such as Tor, transparently to the SDK.

  • Custom Logging: The library includes a logging adapter that developers can customize. It enables the host app to determine log storage and location, providing a way to encrypt or remove sensitive information from the logs if needed.

  • Client-side Load Balancing: The library enables the host app to dynamically select the optimal remote node for RPC calls, ensuring efficient synchronization with the Monero blockchain. This can significantly reduce synchronization time by choosing the fastest node.

  • Android Studio Compatibility: The SDK is fully compatible with Android Studio, supporting native debugging, code navigation, and linter capabilities, for both the SDK library and the Monero codebase.

  • Optimized Build System: The library has optimized CMake files that vendor all dependencies of wallet2, and applies Link-time optimizations (LTO) to remove all C++ code that is never called by the SDK. The result is a reproducible and lightweight library size of only 6 MB per arch, that can be built directly from Gradle.

Sample Wallet App

The sample app is a fully functional multi-wallet app that serves as a reference for developers on integrating Monero into their apps. It is also a way to test if the library works well in a real-world application. Key features of the sample wallet app include:

  • Clean Architecture: The sample app uses the latest Android libraries and follows the official architecture guidance.

  • Kotlin and Jetpack Compose: The sample app is entirely written in Kotlin and uses Jetpack Compose for the UI, as well as many architecture components like Room, Lifecycle, and Navigation.

Use Cases

The SDK is primarily designed to support two use cases: (i) local synchronized mobile wallets and (ii) Monero payments, with a focus on security, simplicity and performance. Although we are centered on these specific use cases, it would be beneficial to consider other potential applications where the SDK could be used in the future.

In the first stable release, it is planned to provide the following functionality:

  1. Wallet Management
    1. Create and restore wallet from mnemonic seed (25-words standard) or secret key
    2. Export wallet seed and secret key
    3. Save and load wallet from the storage defined by the app
  2. Account Generation and Subaddresses
    1. Derive account subaddresses and track their usage
    2. Parse base58 public addresses
  3. Balance Inquiry
    1. Query locked/unlocked balance at a specific time
    2. Retrieve transaction history
    3. Listen to balance and transaction (ledger) updates
  4. Transaction Handling
    1. Construct, sign, and broadcast single and multi-recipient TXs
    2. Handle network fee automatically
    3. Create and verify payment proofs
  5. Blockchain Synchronization
    1. Resume scanning or restart it from a specific height
    2. Load balance RPC calls and failover to multiple remote nodes
    3. Monitor remote node status and response time

The following features would be left out of the first release: fine-grained coin control, hardware wallets, manual transaction input, message signing, and multisig. There is no roadmap or timeline yet for when these additional features will be included in future releases.

Code Example

This snippet of code is a basic example to show how to use the API: wallet-sdk-android-example.kt

Limitations and Known Issues

The biggest issue we have come across is how wallet2 trusts the remote nodes for blockchain synchronization. While it is widely known that malicious nodes can manipulate the returned blocks to deceive clients, the current lack of validation in wallet2 makes it too easy to exploit. Unfortunately, wallet2 fails to verify if the returned blocks line up with the previous blocks in the chain. This vulnerability has already been described in a security advisory (link).

To mitigate this problem, we suggest adding basic integrity checks into wallet2, but without validating PoW. These checks will help wallet2 to early detect the attack when connecting to an honest node.

Our plan is to address this issue for the initial release of the SDK, as well as upstream the fixes to wallet2.