Overview
Impervious Node API and Architecture
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.
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].
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.
Layers
The Impervious Node offers three web developer friendly interfaces for communications.
- 1.GRPC input
- 2.HTTP RESTful input
- 3.HTTP Websocket output
Message interfaces
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.
Message flow
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.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.
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.
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
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.ymlfile to exist within the working directory - Secondly, it checks for a
config/config.ymlfile 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!"}
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.
Last modified 2yr ago