-LDK Java and TypeScript Bindings
-================================
+LDK Java, C#, and TypeScript Bindings
+=====================================
-This repo contains an autogeneration system to generate LDK bindings for garbage-collected languages, currently including Java and TypeScript. See below for the current status of the bindings.
+This repo contains an autogeneration system to generate LDK bindings for garbage-collected languages, currently including Java, C#, and TypeScript. See below for the current status of the bindings.
-The auto-generated code does not yet contain documentation, however the API mirrors rust-lightning exactly, so all documentation at [docs.rs/lightning](https://docs.rs/lightning) is applicable. High-level documentation of the API can be found at [lightningdevkit.org](https://lightningdevkit.org).
+The auto-generated code contains copies of the Rust documentation, which can also be viewed at
+[docs.rs/lightning](https://docs.rs/lightning). High-level documentation of the API can be found at
+[lightningdevkit.org](https://lightningdevkit.org).
Building
========
-A release build of the Java bindings library for Linux is available in git. Thus, the bindings should work as long as the `LD_LIBRARY_PATH` includes the top-level directory of this repository.
+The releases for Java, C#, and TypeScript are all deterministic. You should be able to reproduce
+the release binaries identically by running the scripts run in CI, see
+[.github/workflows/build.yml](.github/workflows/build.yml).
-To build the bindings locally, the bindings require some additional work which is still making its way upstream, for now it should be built against the [rust-lightning 2020-10-java-bindings-base branch on git.bitcoin.ninja](https://git.bitcoin.ninja/?p=rust-lightning;a=shortlog;h=refs/heads/2020-10-java-bindings-base). Check that branch out locally and run the `genbindings.sh` script in it to build the required binaries. Thereafter, in this repo, run the `genbindings.sh` script with the first argument pointing to the rust-lightning directory, the second the relevant JNI CFLAGS, the third argument set to `true` or `false` to indicate whether building in debug mode, and the third set to true or false to indicate if the bindings should be built with workarounds required for Android. JNI CFLAGS on debian are likely "-I/usr/lib/jvm/java-11-openjdk-amd64/include/ -I/usr/lib/jvm/java-11-openjdk-amd64/include/linux/". When running a program linking against the library in debug mode, LD_PRELOAD should likely include the relevant `libclang_rt.asan-platform.so` path.
+Releases for all platforma re built on Linux as that is the easiest way to get things
+deterministic, however building on macOS should also work. Building on Windows is not currently
+supported.
Status
======
-The TypeScript Bindings are still in early development any generated code contains syntax errors.
+## Java
-While the underlying library and C bindings are relatively mature, the Java bindings should be considered alpha quality. Around 98% of the Rust API surface is exposed (with one or two functions around peer feature sets still to be exposed), but some memory management issues may still appear. Specifically, because the Java bindings map between two very different memory models - Rust's strict ownership model and Java's reference cloning and garbage collection - a lot of work occurs in the background to keep the Java GC informed of Rust ownership semantics.
+The Java bindings are relatively mature, and should be considered safe for production use. Still,
+as they have relatively few users, unexpected issues remain possible, and bug reports are welcome.
-There are some known memory leaks, which are relatively modest in the existing test suite, but which may be less moderate in certain usages. The debug-mode build includes memory leak tracking and will print all loose objects when the program exists, though without calls to `System.gc(); System.runFinalization();` immediately before exit there will likely be many false positives. While it will require some complicated usage, there are likely some use-after-free or unkonwn-free bugs remaining. The debug-mode build links LLVM address sanitizer and will print diagnostic information in case of such issues.
+## TypeScript
-The only known issue resulting in a use-after-free bug requires custom a custom ChannelKeys instance created as a part of a new channel. After the channel is created, the ChannelKeys object will not be freed while the parent ChannelManager exists, however if the ChannelManager is garbage collected while a ChannelMonitor object which is associated with the same channel exists, a use-after-free bug may occur. This issue should be relatively rare as uses where a ChannelManager is removed while associated ChannelMonitors exist is not anticipated.
+The TypeScript bindings are functionally complete, but should be considered beta quality. As there
+are relatively few users, unexpected issues remain likely, and bug reports are welcome.
+
+The TypeScript bindings require modern web standards, including support for `FinalizationRegistry`
+and `WeakRef` (Chrome 84, Firefox 79, Safari 14.1/iOS 14.5 and Node 14.6) and WASM BigInt support
+(Chrome 85, Firefox 78, Safari 14.1/iOS 14.5, and Node 15.0).
+
+For users of Node.JS environments you may wish to use the `lightningdevkit-node-net` package as
+well to implement the required network handling to bridge the `lightningdevkit` package's
+`SocketDescriptor` interface to Node.JS TCP Sockets. For those wishing to run a lightning node in
+the browser you will need to provide your own bridge from `SocketDescriptor` to a WebSocket proxy.
+
+# C#
+
+The C# bindings are functionally complete, but should be considered alpha quality. They are brand
+new and likely contain bugs or memory leaks.
+
+## General
+
+The only known issue resulting in a use-after-free bug requires custom a custom ChannelKeys instance
+created as a part of a new channel. After the channel is created, the ChannelKeys object will not
+be freed while the parent ChannelManager exists, however if the ChannelManager is garbage collected
+while a ChannelMonitor object which is associated with the same channel exists, a use-after-free bug
+may occur. This issue should be relatively rare as uses where a ChannelManager is removed while
+associated ChannelMonitors exist is not anticipated.
projects / ldk-java / blobdiff