This documentation is intended for developers who wish to build applications using the Impervious Node API. These endpoints allow for a variety of interesting use cases and allow for creative combinations of API calls to build projects.

The goal of the Impervious Node is to enable developers to easily build robust applications which take advantage of the Lightning Network, without having to learn or worry about the deep technicals of Lighting payment systems.

Impervious Node's are a FRAMEWORK, for developers to create their own networks, applications, APIs and other creative architectural structures.

API End User License Agreement ("EULA") & Contest Rules

Please find the Impervious API End User License Agreement ("EULA") in our Github repository. If you are participating in the hackathon, you may find the Contest/Hackathon rules here. If you have any questions or comments regarding these Terms, please contact us at [email protected]

The Impervious Architecture Explained

At layer one, there exists the Bitcoin network - money, deep storage, global root trust.

At layer two, there exists the Lightning Network - cash, fluid payments, peer to peer trust.

At layer three, there exists the Impervious Network - applications, streaming micro payments, and node federation.

The Impervious Node offers three web developer friendly interfaces for communications.

1. GRPC input

2. HTTP RESTful input

3. HTTP Websocket output

Both GRPC/REST interfaces provide an input and a message ID on the response. This message ID allows for a developer to track and coordinate message synchronization.

The websocket output is a stream of messages, with the above message ID, or a far end message ID. The websocket is used for asynchronous/random reception of messages. For some API endpoints, the response is via the websocket because there could be a long wait state for the Lightning Network to forward the messages. In our design, these GRPC/REST interfaces, generate a message ID, fire off the message into the Lightning Network, and then immediately respond to the developer with the message ID. The developer then monitors the websocket for that message ID to return. It is recommended to always monitor the websocket for asynchronous incoming messages. Do not transmit INTO the websocket, it will be ignored.

​

LND Node Configuration

Impervious currently only supports LND lightning nodes, and relies on a running LND node to get started. Additionally, the LND node requires KEYSEND to be enabled via the accept-keysend=true parameter in the lnd.confconfig file.

To run on testnet, get some free testnet Bitcoins here: https://faucet.lightning.community/​

Then go to our website to get a pair of FREE Voltage LND nodes.

Follow the Voltage instructions for starting up a node on testnet. Then open a channel per https://faucet.lightning.community/ which will fund your channel.

Once your node(s) up and running, click on your node then choose CONNECT and then MANUAL. This will provide you with the URL, macaroon, and TLS certificate. Port is default 10009.

Save the macaroon/TLS files in your Impervious Node user's home directory. Configure the Impervious node's config.yaml file for these locations and the node URL:port.

Downloading the Impervious Daemon

The latest version of our Impervious binaries can be found in the Releases section of our public repository. You may also use our Docker image with the binaries built in, follow the setup instructions here for that.

Impervious Node Configuration

The Impervious Node is configured via a simple YAML file. Only a couple sections need to be edited, the rest can safely be ignored. You can grab a template file from our public repository to get started.

Additionally, be sure that your YAML file ends in a .yml extension and NOT .yaml.

Note: Currently the configuration file includes the sqlite3 password, and for this reason it is not recommended to check this file into version control. In a later update, handling of the sqlite3 credentials will be updated.

# Server configurations
server:
  enabled: true # enable the GRPC/HTTP/websocket server 
  grpc_addr: 127.0.0.1:8881 #IP:port for GRPC
  http_addr: 127.0.0.1:8882 #IP:port for HTTP/websocket
# Redis DB configurations
sqlite3:
  username: admin
  password: supersecretpassword # this will get moved to environment variable or generated dynamically
###### DO NOT EDIT THE BELOW SECTION#####
# Services
service_list:
  - service_type: federate
    active: true
    custom_record_number: 100000
    additional_service_data:
  - service_type: vpn
    active: true
    custom_record_number: 200000
    additional_service_data:
  - service_type: websocket
    active: true
    custom_record_number: 300000
    additional_service_data:
  - service_type: message
    active: true
    custom_record_number: 400000
    additional_service_data:
  - service_type: socket
    active: true
    custom_record_number: 500000
    additional_service_data:
  - service_type: sign
    active: true
    custom_record_number: 800000
    additional_service_data:
###### DO NOT EDIT THE ABOVE SECTION#####
    
# Lightning
lightning:
  lnd_node:
    ip: 127.0.0.1 #IP of your LND node
    port: 10001 #GRPC port of your LND node
    pub_key: asdfasdfasdf #get your LND pubkey with "lncli getinfo" 
    tls_cert: /path/to/tls.cert
    admin_macaroon: /path/to/admin.macaroon
federate:
  ttl: 31560000 #Federation auto delete in seconds
  imp_id: YOUR_IMP_ID #plain text string of your IMP node name
vpn:
  price: 100 #per hour
  server_ip: 127.0.0.1 #public IP of your VPN server 
  server_port: 51820 #port you want to listen on
  subnet: 10.0.0.0/24 #subnet you want to give to your clients. .1 == your server IP.
  server_pub_key: asdfasdfasdf #get this from your WG public key file 
  allowed_ips: 0.0.0.0/0 #what subnets clients can reach. Default is entire world.
  binary_path: /usr/bin/wg #where your installed the "wg" command.
  dns: 8.8.8.8 #set your preferred DNS server here.
socket:
  server_ip: 1.1.1.1 #public IP of your socket server  

Starting your IMP Daemon

How exciting! You've got your configuration file setup, Impervious installed, and you are ready to roll! The impervious daemon can be run by simple typing the following.

$ ./impervious --config /path/to/config/file.yml

If you don't want to add the --config flag, note that the Impervious daemon defaults to a series of steps if --config is not present.

• First, it checks for a config/local.config.yml file to exist within the working directory

• Secondly, it checks for a config/config.yml file to exist within the working directory

If the --config file is omitted, the daemon can be run simply using the following command:

$ ./impervious
...output...
{"level":"info" ... "msg":"IMPD started!"}

Connecting with your Impervious Daemon

Good work! Now it's time to connect and take your daemon for a drive! Impervious is intended to be instrumented via API and currently supports REST and gRPC, with event subscription handled via Websocket.

Dive into the specific APIs to get started and learn more about each service! Or click Next for the Quick Start Guide.