_ Git - ldk-java/blob - README.md

   1 LDK Java and TypeScript Bindings
   2 ================================
   3
   4 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.
   5
   6 The auto-generated code contains copies of the Rust documentation, which can also be viewed at
   7 [docs.rs/lightning](https://docs.rs/lightning). High-level documentation of the API can be found at
   8 [lightningdevkit.org](https://lightningdevkit.org).
   9
  10 Building
  11 ========
  12
  13 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.
  14
  15 To build the bindings locally, the bindings require some additional work which is still making its
  16 way upstream, for now it should be built against the
  17 [rust-lightning 2021-03-java-bindings-base branch on git.bitcoin.ninja](https://git.bitcoin.ninja/?p=rust-lightning;a=shortlog;h=refs/heads/2021-03-java-bindings-base).
  18 Check that branch out locally as well as [ldk-c-bindings](https://github.com/lightningdevkit/ldk-c-bindings)
  19 and run the `genbindings.sh` script in ldk-c-bindings to build the required binaries. Thereafter,
  20 in this repo, run the `genbindings.sh` script with the first argument pointing to the ldk-c-bindings
  21 directory, the second the relevant JNI CFLAGS, the third argument set to `true` or `false` to
  22 indicate whether building in debug mode, and the third set to true or false to indicate if the
  23 bindings should be built with workarounds required for Android. JNI CFLAGS on debian are likely
  24 "-I/usr/lib/jvm/java-11-openjdk-amd64/include/ -I/usr/lib/jvm/java-11-openjdk-amd64/include/linux/".
  25 When running a program linking against the library in debug mode, LD_PRELOAD should likely include
  26 the relevant `libclang_rt.asan-platform.so` path.
  27
  28 Status
  29 ======
  30
  31 The TypeScript Bindings are still in early development and generated code contains syntax errors.
  32
  33 While the underlying library and C bindings are relatively mature, the Java bindings should be
  34 considered alpha quality and some memory management issues may still appear. Specifically, because
  35 the Java bindings map between two very different memory models - Rust's strict ownership model and
  36 Java's reference cloning and garbage collection - a lot of work occurs in the background to keep
  37 the Java GC informed of Rust ownership semantics.
  38
  39 There are some known memory leaks, which are relatively modest in the existing test suite (around
  40 1MB for 128 node constructions and 64 full channel constructions and payments sent), but which may
  41 be less moderate in certain usages. The debug-mode build includes memory leak tracking and will
  42 print all loose objects when the program exists, though without calls to
  43 `System.gc(); System.runFinalization();` immediately before exit there will likely be many false
  44 positives. While it will require some complicated usage, there are likely some use-after-free or
  45 unkonwn-free bugs remaining. The debug-mode build links LLVM address sanitizer and will print
  46 diagnostic information in case of such issues.
  47
  48 The only known issue resulting in a use-after-free bug requires custom a custom ChannelKeys instance
  49 created as a part of a new channel. After the channel is created, the ChannelKeys object will not
  50 be freed while the parent ChannelManager exists, however if the ChannelManager is garbage collected
  51 while a ChannelMonitor object which is associated with the same channel exists, a use-after-free bug
  52 may occur. This issue should be relatively rare as uses where a ChannelManager is removed while
  53 associated ChannelMonitors exist is not anticipated.