lnsocket

A minimal C library for connecting to the lightning network
git clone git://jb55.com/lnsocket
Log | Files | Refs | Submodules | README | LICENSE

README.md (2681B)

      1 
      2 # lnsocket
      3 
      4 A simple C, JS and Go library for sending messages over the lightning network.
      5 
      6 Thanks to Rusty and the clightning project for much of this code, I have
      7 adapted it to be more library friendly.
      8 
      9 
     10 ## Motivation
     11 
     12 I wanted a way to send custom messages to my lightning node, such as RPC.
     13 Building this as a simple C library will allow you to speak the lightning
     14 network in native applications, like on mobile.
     15 
     16 
     17 ## Dependencies
     18 
     19 You'll need `libtool`, `autoconf`, and `automake` for the `libsodium` &
     20 `secp256k1` submodules, but otherwise there are no dependencies.
     21 
     22 You'll need `emscripten` for the `wasm` build.
     23 
     24 ## Building
     25 
     26     $ make
     27 
     28 ### iOS
     29 
     30     $ make ios
     31 
     32 This will build `lnsocket.a`, `libsodium.a` and `libsecp256k1.a` under
     33 `target/ios` for `arm64` and `ios-sim-x86`.
     34 
     35 
     36 ### WASM/JS/Web
     37 
     38 Building manually:
     39 
     40     $ make js
     41 
     42 This will build `lnsocket.js` and `lnsocket.wasm` in `target/js` so that you
     43 can connect to the lightning network from your browser via websockets. 
     44 
     45 There are packaged versions of the js build under [dist/js](dist/js)
     46 
     47 If you are in a web environment that supports npm modules, you can import
     48 lnsocket using npm:
     49 
     50 ```js
     51 const LNSocket = require('lnsocket')
     52 
     53 async function makeRequest(method, params, rune) {
     54   const ln = await LNSocket()
     55   ln.genkey()
     56   await ln.connect_and_init(node_id, host)
     57   // ... etc
     58 }
     59 ```
     60 
     61 The plain js file under [dist/js](dist/js) declares an `lnsocket_init()`
     62 function like so:
     63 
     64 ```js
     65 const LNSocket = await lnsocket_init()
     66 const ln = LNSocket()
     67 
     68 ln.genkey()
     69 ```
     70 
     71 See [examples/websockets.js](examples/websockets.js) for a demo.
     72 
     73 ### NodeJS
     74 
     75     $ npm install --save lnsocket
     76 
     77 See [examples/node.js](examples/node.js)
     78 
     79 ### Go
     80 
     81 There is a Go version of lnsocket written using lnd's brontide[^3].
     82 
     83 You can import it via:
     84 
     85     import "github.com/jb55/lnsocket/go"
     86 
     87 It is currently used in fiatjaf's makeinvoice go library[^4] if you want an
     88 example of its usage.
     89 
     90 ### Rust
     91 
     92 There are some initial rust bindings which you can build via: `make rust`
     93 
     94 ## C Examples
     95 
     96 * See [test.c](test.c) for a ping/pong example
     97 
     98 * See [lnrpc.c](lnrpc.c) for an RPC example
     99 
    100 ## Contributing
    101 
    102 Send patches to `jb55@jb55.com`
    103 
    104     $ git config format.subjectPrefix 'PATCH lnsocket'
    105     $ git config sendemail.to 'William Casarin <jb55@jb55.com>'
    106     $ git send-email --annotate HEAD^
    107 
    108 See git-send-email.io[^1] for configuring your mailer
    109 
    110 You can open a PR on github[^2] as well
    111 
    112 [^1]: https://git-send-email.io/
    113 [^2]: https://github.com/jb55/lnsocket
    114 [^3]: https://github.com/lightningnetwork/lnd/tree/master/brontide
    115 [^4]: https://github.com/fiatjaf/makeinvoice/blob/d523b35084af04883f94323dc11a50c2a99d253d/makeinvoice.go#L366