https://github.com/joakimofv/lntransport
Dial and listen for Bitcoin Lightning Network (LN) connections. Context aware send and receive.
https://github.com/joakimofv/lntransport
bitcoin encryption-decryption go golang library lightning-network networking
Last synced: 6 months ago
JSON representation
Dial and listen for Bitcoin Lightning Network (LN) connections. Context aware send and receive.
- Host: GitHub
- URL: https://github.com/joakimofv/lntransport
- Owner: joakimofv
- License: mit
- Created: 2022-06-08T11:28:30.000Z (about 4 years ago)
- Default Branch: master
- Last Pushed: 2022-08-08T09:25:22.000Z (almost 4 years ago)
- Last Synced: 2023-07-27T22:15:35.432Z (almost 3 years ago)
- Topics: bitcoin, encryption-decryption, go, golang, library, lightning-network, networking
- Language: Go
- Homepage:
- Size: 64.5 KB
- Stars: 2
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://pkg.go.dev/github.com/joakimofv/lntransport)
lntransport
===========
An object that can dial and listen for Bitcoin Lightning Network (LN) connections.
The connection objects send/receive messages with a simple API that uses context.Context.
All is safe for concurrent use.
# Import
```go
lntransport "github.com/joakimofv/lntransport"
```
# Usage
### [New](https://pkg.go.dev/github.com/joakimofv/lntransport#New)
```go
cfg := lntransport.Config{}
copy(cfg.Privkey[:], privkeyByteSlice)
lt, err := lntransport.New(cfg)
if err != nil {
// Handle err.
}
defer lt.Close()
```
Privkey is a `[32]byte` array that needs to be a valid cryptographic key.
See [`Config`](https://pkg.go.dev/github.com/joakimofv/lntransport#Config).
### [Listen](https://pkg.go.dev/github.com/joakimofv/lntransport#LnTransport.Listen)
```go
ch, addr, err := lt.Listen(ctx, "127.0.0.1:12345")
```
Cancelling the `ctx` will abort the background listening process.
Incoming connections will be passed on the `ch` channel.
The channel will be closed when the listener is done so you can drain it like this:
```go
var conn *Conn
for conn = range ch {
defer conn.Close()
// ...
}
```
### [Dial](https://pkg.go.dev/github.com/joakimofv/lntransport#LnTransport.Dial)
```go
conn, err := lt.Dial(ctx, "1.2.3.4:12345", remotePubkey)
if err != nil {
// Handle err.
}
defer conn.Close()
```
The `remotePubkey` refers to the pubkey of the remote side, a byte slice, which you have to learn somehow before dialing.
For your own side you can get it with `lt.Pubkey()`.
### [Send](https://pkg.go.dev/github.com/joakimofv/lntransport#Conn.Send)
```go
err := conn.Send(ctx, []byte("abcd..."))
if err != nil {
if conn.IsClosed() {
// conn has become defunct.
}
// Handle err.
}
```
### [Receive](https://pkg.go.dev/github.com/joakimofv/lntransport#Conn.Receive)
```go
msg, err := conn.Receive(ctx)
if err != nil {
if conn.IsClosed() {
// conn has become defunct.
}
// Handle err.
}
```
# Error Handling
## Defunct Connection
Various network problems, counterparty problems, or bungled sends/receives may cause a connection object to become defunct.
Then it will close itself. Check if it has happened with [`conn.IsClosed()`](https://pkg.go.dev/github.com/joakimofv/lntransport#Conn.IsClosed).
A closed connection can not be recovered. Be ready to dial again to make a new connection, or handle the situation in some other way.
## Failed Incoming Connection Attempts
Incoming connection attempts to a listener may fail. By default, when it happens a line will be printed with stdlib `log`.
Adjust what is done with these errors through fields in the [`Config`](https://pkg.go.dev/github.com/joakimofv/lntransport#Config).
## Limit On Number Of Connections
Having more than 30 000 connection object active from a single LnTransport can cause it to malfunction. Avoid that.