_ 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 2022-10-112-java-bindings branch on git.bitcoin.ninja](https://git.bitcoin.ninja/?p=rust-lightning;a=shortlog;h=refs/heads/2022-10-112-java-bindings).
  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 Note that building with address sanitizer is only supported on MacOS with upstream clang (ie where
  29 the LLVM version in use matches the LLVM version against which rustc was built), not with Apple clang.
  30 Builds with Apple clang will work fine, but largely only be useful in a release context.
  31 To build on Mac with address sanitizer, you will need to run `ldk-c-bindings`' `genbindings.sh`
  32 script with upstream clang in your PATH and likely replace your $JAVA_HOME/bin/java with a simple
  33 wrapper which calls java after an export like:
  34 `export DYLD_INSERT_LIBRARIES=/path/to/upstream/llvm/lib/clang/12.0.0/lib/darwin/libclang_rt.asan_osx_dynamic.dylib`
  35
  36 To build for Apple M1 (ie aarch64-apple-darwin), you probably want something like
  37 `CC="clang --target=aarch64-apple-darwin" LDK_TARGET=aarch64-apple-darwin LDK_TARGET_CPU=generic ./genbindings.sh ...`
  38
  39 Status
  40 ======
  41
  42 ## Java
  43
  44 The Java bindings are relatively mature, and should be considered safe for production use. Still,
  45 as they have relatively few users, unexpected issues remain possible, and bug reports are welcome.
  46
  47 ## TypeScript
  48
  49 The TypeScript bindings are functionally complete, but should be considered beta quality. As there
  50 are relatively few users, unexpected issues remain likely, and bug reports are welcome.
  51
  52 The TypeScript bindings require modern web standards, including support for `FinalizationRegistry`
  53 and `WeakRef` (Chrome 84, Firefox 79, Safari 14.1/iOS 14.5 and Node 14.6) and WASM BigInt support
  54 (Chrome 85, Firefox 78, Safari 14.1/iOS 14.5, and Node 15.0).
  55
  56 For users of Node.JS environments you may wish to use the `lightningdevkit-node-net` package as
  57 well to implement the required network handling to bridge the `lightningdevkit` package's
  58 `SocketDescriptor` interface to Node.JS TCP Sockets. For those wishing to run a lightning node in
  59 the browser you will need to provide your own bridge from `SocketDescriptor` to a WebSocket proxy.
  60
  61 # C#
  62
  63 The C# bindings are functionally complete, but should be considered alpha quality. They are brand
  64 new and likely contain bugs or memory leaks.
  65
  66 ## General
  67
  68 The only known issue resulting in a use-after-free bug requires custom a custom ChannelKeys instance
  69 created as a part of a new channel. After the channel is created, the ChannelKeys object will not
  70 be freed while the parent ChannelManager exists, however if the ChannelManager is garbage collected
  71 while a ChannelMonitor object which is associated with the same channel exists, a use-after-free bug
  72 may occur. This issue should be relatively rare as uses where a ChannelManager is removed while
  73 associated ChannelMonitors exist is not anticipated.