Merge pull request #10 from callebtc/api/1ml

javascript and api

README.md

@@ -1,7 +1,9 @@
 # ⚡️🛡 electronwall
-A tiny firewall for LND that can filter Lightning **channel opening requests** and **HTLC forwards** on your node based on set rules. 
+A tiny firewall for LND that can filter Lightning **channel opening requests** and **HTLC forwards** based on your custom rules. 
 
-Currently, electronwall uses filter lists that either allow (allowlist) or reject (denylist) events from a list of node public keys for channel openings, or channel IDs and channel pairs for payment routings.
+electronwall uses filter lists that either allow (allowlist) or reject (denylist) events from a list of node public keys for channel openings, or channel IDs and channel pairs for payment routings.
+
+You can also write [custom rules](#programmable-rules) using a builtin Javascript engine. 
 
 ![electronwall0 3 2](https://user-images.githubusercontent.com/93376500/178162791-e6ba90c1-2798-471d-b7aa-0b12eae8bf2e.png)
 
@@ -21,10 +23,192 @@ go build .
 You can download a binary for your system [here](https://github.com/callebtc/electronwall/releases). You'll still need a [config file](https://github.com/callebtc/electronwall/blob/main/config.yaml.example).
 
 ## Config
-Edit `config.yaml.example` and rename to `config.yaml`.
+Edit `config.yaml.example` and rename to `config.yaml`. 
 
 ## Run
 
 ```bash
 ./electronwall
 ```
+
+--------------- 
+# Rules
+
+## Allowlist and denylist
+
+Allowlist and denylist rules are set in `config.yaml` under the appropriate keys. See the [example](config.yaml.example) config. 
+
+## Programmable rules
+
+electronwall has a Javascript engine called [goja](https://github.com/dop251/goja) that allows you to set custom rules. Note that you can only use pure Javascript (ECMAScript), you can't import a ton of other dependcies like with web applications.
+
+Rules are saved in the `rules/` directory. There are two files, one for channel open requests `ChannelAccept.js` and one for HTLC forwards `HtlcForward.js`.
+
+electronwall passes [contextual information](#contextual-information) to the Javascript engine that you can use to create rich rules. See below for a list of objects that are currently supported.
+
+ Here is one rather complex rule for channel accept decisions in `ChannelAccept.js` for demonstration purposes:
+
+ ```javascript
+ // only channels > 0.75 Msat
+ChannelAccept.Event.FundingAmt >= 750000 && 
+// nodes with high 1ML availability score
+ChannelAccept.OneMl.Noderank.Availability > 100 &&
+// nodes with a low enough 1ML age rank
+ChannelAccept.OneMl.Noderank.Age < 10000 &&
+( 
+    // only nodes with Amboss contact data
+    ChannelAccept.Amboss.Socials.Info.Email ||
+    ChannelAccept.Amboss.Socials.Info.Twitter ||
+    ChannelAccept.Amboss.Socials.Info.Telegram 
+) &&
+(
+    // elitist: either nodes with amboss prime
+    ChannelAccept.Amboss.Amboss.IsPrime ||
+    // or nodes with high-ranking capacity
+    ChannelAccept.Amboss.GraphInfo.Metrics.CapacityRank < 1000 ||
+    // or nodes with high-ranking channel count
+    ChannelAccept.Amboss.GraphInfo.Metrics.ChannelsRank < 1000
+)
+ ```
+
+ Here is an example `HtlcForward.js`
+ ```javascript
+ if (
+    // only forward amounts larger than 100 sat
+    HtlcForward.Event.OutgoingAmountMsat >= 100000
+) { true } else { false }
+ ```
+
+### Contextual information
+Here is a list of all objects that are passed to the Javascript engine. You need to look at the structure of these objects in order to use them in a custom rule like the example above. 
+
+#### LND: ChannelAcceptRequest `*.Event`
+```go
+type ChannelAcceptRequest struct {
+	state         protoimpl.MessageState
+	sizeCache     protoimpl.SizeCache
+	unknownFields protoimpl.UnknownFields
+
+	// The pubkey of the node that wishes to open an inbound channel.
+	NodePubkey []byte `protobuf:"bytes,1,opt,name=node_pubkey,json=nodePubkey,proto3" json:"node_pubkey,omitempty"`
+	// The hash of the genesis block that the proposed channel resides in.
+	ChainHash []byte `protobuf:"bytes,2,opt,name=chain_hash,json=chainHash,proto3" json:"chain_hash,omitempty"`
+	// The pending channel id.
+	PendingChanId []byte `protobuf:"bytes,3,opt,name=pending_chan_id,json=pendingChanId,proto3" json:"pending_chan_id,omitempty"`
+	// The funding amount in satoshis that initiator wishes to use in the
+	// channel.
+	FundingAmt uint64 `protobuf:"varint,4,opt,name=funding_amt,json=fundingAmt,proto3" json:"funding_amt,omitempty"`
+	// The push amount of the proposed channel in millisatoshis.
+	PushAmt uint64 `protobuf:"varint,5,opt,name=push_amt,json=pushAmt,proto3" json:"push_amt,omitempty"`
+	// The dust limit of the initiator's commitment tx.
+	DustLimit uint64 `protobuf:"varint,6,opt,name=dust_limit,json=dustLimit,proto3" json:"dust_limit,omitempty"`
+	// The maximum amount of coins in millisatoshis that can be pending in this
+	// channel.
+	MaxValueInFlight uint64 `protobuf:"varint,7,opt,name=max_value_in_flight,json=maxValueInFlight,proto3" json:"max_value_in_flight,omitempty"`
+	// The minimum amount of satoshis the initiator requires us to have at all
+	// times.
+	ChannelReserve uint64 `protobuf:"varint,8,opt,name=channel_reserve,json=channelReserve,proto3" json:"channel_reserve,omitempty"`
+	// The smallest HTLC in millisatoshis that the initiator will accept.
+	MinHtlc uint64 `protobuf:"varint,9,opt,name=min_htlc,json=minHtlc,proto3" json:"min_htlc,omitempty"`
+	// The initial fee rate that the initiator suggests for both commitment
+	// transactions.
+	FeePerKw uint64 `protobuf:"varint,10,opt,name=fee_per_kw,json=feePerKw,proto3" json:"fee_per_kw,omitempty"`
+	//
+	//The number of blocks to use for the relative time lock in the pay-to-self
+	//output of both commitment transactions.
+	CsvDelay uint32 `protobuf:"varint,11,opt,name=csv_delay,json=csvDelay,proto3" json:"csv_delay,omitempty"`
+	// The total number of incoming HTLC's that the initiator will accept.
+	MaxAcceptedHtlcs uint32 `protobuf:"varint,12,opt,name=max_accepted_htlcs,json=maxAcceptedHtlcs,proto3" json:"max_accepted_htlcs,omitempty"`
+	// A bit-field which the initiator uses to specify proposed channel
+	// behavior.
+	ChannelFlags uint32 `protobuf:"varint,13,opt,name=channel_flags,json=channelFlags,proto3" json:"channel_flags,omitempty"`
+	// The commitment type the initiator wishes to use for the proposed channel.
+	CommitmentType CommitmentType `protobuf:"varint,14,opt,name=commitment_type,json=commitmentType,proto3,enum=lnrpc.CommitmentType" json:"commitment_type,omitempty"`
+}
+
+```
+
+#### 1ML node information `*.OneMl`
+```go
+type OneML_NodeInfoResponse struct {
+	LastUpdate int    `json:"last_update"`
+	PubKey     string `json:"pub_key"`
+	Alias      string `json:"alias"`
+	Addresses  []struct {
+		Network string `json:"network"`
+		Addr    string `json:"addr"`
+	} `json:"addresses"`
+	Color        string `json:"color"`
+	Capacity     int    `json:"capacity"`
+	Channelcount int    `json:"channelcount"`
+	Noderank     struct {
+		Capacity     int `json:"capacity"`
+		Channelcount int `json:"channelcount"`
+		Age          int `json:"age"`
+		Growth       int `json:"growth"`
+		Availability int `json:"availability"`
+	} `json:"noderank"`
+}
+```
+#### Amboss node information `*.Amboss`
+```go
+type Amboss_NodeInfoResponse struct {
+	Socials struct {
+		Info struct {
+			Email            string      `json:"email"`
+			Telegram         string      `json:"telegram"`
+			Twitter          string      `json:"twitter"`
+			LightningAddress string      `json:"lightning_address"`
+			Website          string      `json:"website"`
+			Pubkey           string      `json:"pubkey"`
+			MinChannelSize   interface{} `json:"minChannelSize"`
+			Message          string      `json:"message"`
+			TwitterVerified  bool        `json:"twitter_verified"`
+			Updated          time.Time   `json:"updated"`
+		} `json:"info"`
+	} `json:"socials"`
+	GraphInfo struct {
+		LastUpdate time.Time `json:"last_update"`
+		Metrics    struct {
+			Capacity     string `json:"capacity"`
+			CapacityRank int    `json:"capacity_rank"`
+			Channels     int    `json:"channels"`
+			ChannelsRank int    `json:"channels_rank"`
+		} `json:"metrics"`
+		Node struct {
+			Addresses []struct {
+				Addr   string `json:"addr"`
+				IPInfo struct {
+					City        string `json:"city"`
+					Country     string `json:"country"`
+					CountryCode string `json:"country_code"`
+				} `json:"ip_info"`
+				Network string `json:"network"`
+			} `json:"addresses"`
+			LastUpdate int    `json:"last_update"`
+			Color      string `json:"color"`
+			Features   []struct {
+				FeatureID  string `json:"feature_id"`
+				IsKnown    bool   `json:"is_known"`
+				IsRequired bool   `json:"is_required"`
+				Name       string `json:"name"`
+			} `json:"features"`
+		} `json:"node"`
+	} `json:"graph_info"`
+	Amboss struct {
+		IsFavorite            bool `json:"is_favorite"`
+		IsPrime               bool `json:"is_prime"`
+		NumberFavorites       int  `json:"number_favorites"`
+		NewChannelGossipDelta struct {
+			Mean string `json:"mean"`
+			Sd   string `json:"sd"`
+		} `json:"new_channel_gossip_delta"`
+		Notifications struct {
+			NumberSubscribers int `json:"number_subscribers"`
+		} `json:"notifications"`
+	} `json:"amboss"`
+}
+```
+
+#### Network information `*.Network`
+*TBD*

api/1ml.go

@@ -0,0 +1,77 @@
+package api
+
+import (
+	"encoding/json"
+	"fmt"
+	"io/ioutil"
+	"net/http"
+	"time"
+
+	"github.com/callebtc/electronwall/config"
+	log "github.com/sirupsen/logrus"
+)
+
+type OneML_NodeInfoResponse struct {
+	LastUpdate int    `json:"last_update"`
+	PubKey     string `json:"pub_key"`
+	Alias      string `json:"alias"`
+	Addresses  []struct {
+		Network string `json:"network"`
+		Addr    string `json:"addr"`
+	} `json:"addresses"`
+	Color        string `json:"color"`
+	Capacity     int    `json:"capacity"`
+	Channelcount int    `json:"channelcount"`
+	Noderank     struct {
+		Capacity     int `json:"capacity"`
+		Channelcount int `json:"channelcount"`
+		Age          int `json:"age"`
+		Growth       int `json:"growth"`
+		Availability int `json:"availability"`
+	} `json:"noderank"`
+}
+
+type OneMlClient struct {
+}
+
+func GetOneMlClient() OneMlClient {
+	return OneMlClient{}
+}
+
+func (c *OneMlClient) GetNodeInfo(pubkey string) (OneML_NodeInfoResponse, error) {
+
+	url := fmt.Sprintf("https://1ml.com/node/%s/json", pubkey)
+
+	log.Infof("Getting info from 1ml.com for %s", pubkey)
+
+	client := http.Client{
+		Timeout: time.Second * time.Duration(config.Configuration.ApiRules.OneMl.Timeout),
+	}
+
+	req, err := http.NewRequest(http.MethodGet, url, nil)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	res, getErr := client.Do(req)
+	if getErr != nil {
+		log.Fatal(getErr)
+	}
+
+	if res.Body != nil {
+		defer res.Body.Close()
+	}
+
+	body, readErr := ioutil.ReadAll(res.Body)
+	if readErr != nil {
+		log.Fatal(readErr)
+	}
+
+	r := OneML_NodeInfoResponse{}
+	jsonErr := json.Unmarshal(body, &r)
+	if jsonErr != nil {
+		log.Errorf("[1ml] api error: %v", jsonErr)
+	}
+
+	return r, nil
+}