Progress pill
Rust & Bitcoin

UniFFI, Bridging Rust Libraries to Multiple Languages

Learning Rust with Bitcoin

UniFFI, Bridging Rust Libraries to Multiple Languages

  • Introduction to UniFFI and Cross-Platform Development
  • Understanding the UniFFI Architecture and Workflow
  • Working with UDL: Interface Definition and Type Mapping
  • Error Handling and Advanced Features
  • Real-World Applications and Current Limitations

Introduction to UniFFI and Cross-Platform Development

UniFFI is a tool for making Rust libraries accessible across multiple programming languages and platforms. Developed by Mozilla, this tool addresses a fundamental challenge in modern software development: how to leverage the performance and safety benefits of Rust while maintaining compatibility with diverse development ecosystems. The tool automatically generates language bindings for Rust libraries, eliminating the need for developers to manually create interface code for each target language.
The core problem UniFFI solves stems from Rust's nature as a compiled language. When Rust code is compiled, it produces binary output with a Foreign Function Interface (FFI) that presents a low-level interface that can be challenging to use directly from higher-level languages like Python, Swift, or Kotlin. Traditionally, each library developer would need to write custom binding code for every target language, creating a significant barrier to cross-platform adoption. UniFFI eliminates this redundancy by providing a standardized approach to generating these bindings automatically.
The tool's design philosophy centers on enabling Rust developers to focus on their core business logic while making their libraries accessible to developers working in other languages. An iOS developer using Swift, for instance, can consume a Rust library through UniFFI-generated bindings that present a completely native Swift interface, with no indication that the underlying implementation is written in Rust. This seamless integration allows teams to leverage Rust's performance benefits without requiring all team members to learn Rust.

Understanding the UniFFI Architecture and Workflow

UniFFI operates through a well-defined workflow that transforms Rust libraries into multi-language compatible packages. The process begins with the creation of a Unified Definition Language (UDL) file, which serves as an interface specification that describes what parts of your Rust library should be exposed to other languages. This UDL file acts as a contract between your Rust implementation and the generated language bindings.
The architecture follows a clear separation of concerns. Developers maintain their Rust library with standard Rust idioms and patterns, then create a separate UDL file that maps the public interface to UniFFI's type system. The UniFFI binding generator processes both the Rust library and the UDL specification to produce native language bindings for the requested target platforms. These generated bindings handle all the complex marshaling and unmarshaling of data between the foreign language runtime and the Rust code.
At runtime, the architecture creates a layered approach where application code written in the target language (such as Kotlin for Android) interacts with generated binding code that appears completely native to that language. This binding layer handles the translation between language-specific types and Rust types, manages memory safely across language boundaries, and provides error handling that follows the conventions of the target language. The underlying Rust business logic remains unchanged and unaware of the multiple language interfaces built on top of it.

Working with UDL: Interface Definition and Type Mapping

The Unified Definition Language serves as the cornerstone of UniFFI's functionality, providing a declarative way to specify which parts of a Rust library should be exposed and how they should be presented in target languages. UDL files must contain at least one namespace, which acts as a container for functions that can be called directly without requiring object instantiation. These namespace functions typically handle simple operations that take values as parameters and return results.
UDL supports a comprehensive set of built-in types that map naturally to corresponding Rust types. Basic types include standard primitives like booleans, various integer sizes (u8, u32, etc.), floating-point numbers, and strings. More complex types include vectors, hash maps, and Rust-specific concepts like Option types (represented with a question mark syntax) and Result types for error handling. The type system also supports enumerations, both simple value-based enums and complex enums that contain associated data, allowing for data modeling that translates across language boundaries.
Structs in Rust translate to dictionaries in UDL, maintaining a nearly one-to-one correspondence while adapting to UDL's syntax conventions. When Rust structs have associated methods, they can be exposed as interfaces in UDL, which generate as classes with methods in object-oriented target languages like Kotlin or Swift. This mapping preserves the object-oriented design patterns that developers expect in these languages while maintaining the underlying Rust implementation's structure and behavior.
// Example UDL file for a Bitcoin wallet library (wallet.udl)
namespace wallet {
    // Namespace functions - called directly without object
    string generate_mnemonic();
    Wallet create_wallet(string mnemonic);
};

// Dictionary (struct) - becomes data class in Kotlin, struct in Swift
dictionary Balance {
    u64 confirmed_sats;
    u64 pending_sats;
};

// Interface (class with methods) - becomes class with methods
interface Wallet {
    // Constructor
    constructor(string mnemonic);

    // Methods
    Balance get_balance();
    string get_new_address();
    string send_to_address(string address, u64 amount_sats);
};

// Enum with data - maps to sealed class (Kotlin) or enum with associated values (Swift)
[Enum]
interface TransactionStatus {
    Pending(u32 confirmations_needed);
    Confirmed(u32 block_height);
    Failed(string reason);
};

// Error enum for Result types
[Error]
enum WalletError {
    "InsufficientFunds",
    "InvalidAddress",
    "NetworkError",
};

// Function that can fail - throws in target language
interface Wallet {
    [Throws=WalletError]
    string send_to_address(string address, u64 amount_sats);
};
The corresponding Rust implementation would define these types and implement the uniffi::export attribute to generate bindings for Kotlin, Swift, Python, and other supported languages.

Error Handling and Advanced Features

UniFFI provides error handling that preserves Rust's Result-based error model while translating it appropriately for target languages. Functions that return Result types in Rust can be marked with the "throws" keyword in UDL, specifying which error types they may produce. These errors must be defined as error enums in the UDL file and must implement Rust's standard Error trait in the underlying Rust code. The thiserror crate provides a convenient macro for implementing this trait, reducing boilerplate code significantly.
The error handling translation demonstrates UniFFI's language-aware approach. In Kotlin, functions marked as throwing in UDL generate methods that throw exceptions following Java/Kotlin conventions. Python bindings similarly use Python's exception model. This translation ensures that error handling feels natural and idiomatic in each target language while preserving the semantic meaning of the original Rust error types.
Callback interfaces represent another advanced feature that enables bidirectional communication between Rust libraries and consuming applications. When a Rust library needs to call back into application code, developers can define traits in Rust and mark them as callback interfaces in UDL. The consuming application implements these interfaces in their native language, and UniFFI handles the complex marshaling required to invoke these callbacks from Rust code. This pattern requires careful consideration of thread safety, as callbacks may cross thread boundaries, necessitating Send and Sync bounds on the Rust side.

Real-World Applications and Current Limitations

UniFFI has been adopted in the cryptocurrency and blockchain development community, with major projects like BDK (Bitcoin Development Kit), LDK (Lightning Development Kit), and various wallet implementations using it to provide mobile SDKs. These projects demonstrate UniFFI's use in production environments.
Examining real-world UDL files from these projects reveals patterns and best practices that have emerged from practical usage. BDK's UDL file, for example, shows how complex domain models with multiple enums, structs, and interfaces can be effectively mapped to create comprehensive mobile SDKs. The consistency of UDL syntax across different projects means that developers familiar with one UniFFI-enabled library can quickly understand and work with others, creating a network effect that benefits the entire ecosystem.
However, UniFFI does have notable limitations that developers must consider. The most significant is the lack of support for asynchronous interfaces. All generated bindings are synchronous, requiring developers to handle asynchronous operations within their Rust code and present synchronous interfaces to consuming applications. Additionally, documentation placement presents a challenge: documentation written in Rust code doesn't transfer to generated bindings, while documentation in UDL files isn't available to direct Rust consumers of the library. While there are ongoing efforts to address these limitations through automatic parsing and generation, they remain considerations for current implementations. Finally, UniFFI generates language bindings but doesn't handle the platform-specific packaging and distribution, leaving developers to manage the final steps of creating distributable packages for each target platform.
Quiz
Quiz1/5
What is the primary limitation that developers must work around when using UniFFI for mobile application development that requires responsive user interfaces?