From 9f5e28515a2947b043a75f249ca7bbc9bd21de74 Mon Sep 17 00:00:00 2001 From: Henoch Argaw Date: Tue, 9 May 2017 17:32:13 -0400 Subject: [PATCH] Md edits (README, CONTRIBUTING, WALKTHROUGH) (#62) * expanded readme.md, tightened up language in contributing.md * Walkthrough edits * formatting fixes --- CONTRIBUTING.md | 14 ++++++-- README.md | 95 +++++++++++++++++++++++++++++++++++++++++++------ WALKTHROUGH.md | 57 ++++++++++++++--------------- 3 files changed, 124 insertions(+), 42 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dbf7b336b..26ecb6924 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,11 +1,19 @@ Contributing to Lit ============================ -There are not too many contributors / users yet, so things can be pretty chill. +Thank you for deciding you want to contribute! -Currently adiabat is the maintainer / lead dev and has full access to the repo. +### Who is working on this? -File issues, make pull requests (squash them if more than a few commits). If it's a big change, discuss with people beforehand. adiabat is on IRC in the various bitcoin-related channels. +As of this writing there are not many contributors yet, so things can be pretty chill regarding rules of contributions. + +However, currently adiabat is the maintainer / lead dev and has full access to the repo. If you want to make a pull request, he'll have to approve it. + +### What can I do? + +- File issues you see that haven't been reported in the issues tab +- Make pull requests to fix these issues +- Add features (squash them if more than a few commits). If it's a big change, discuss with people beforehand. adiabat is on IRC in the various bitcoin-related channels. ### Code practices / philosopy diff --git a/README.md b/README.md index 697ca8b93..a915e1d15 100644 --- a/README.md +++ b/README.md @@ -3,20 +3,74 @@ Under development, not for use with real money. -## Installing on Linux +## Setup + +### Prerequisites +- [Git](https://git-scm.com/) + +### Installing 1. Start by installing Go - * Check this tutorial out: + - [Go Installation](https://golang.org/doc/install) + +2. Set your Go variables to match your installed paths are set correctly: +- `.../go/bin` (your install location) is in `$PATH` (Windows: Add the install location into your `PATH` System Variable) +- `$GOPATH` is set the location of where you want lit (and other projects) to be +- optional: If you want to have packages download in a separate location than your installation add `$GOROOT` set to another location (Windows: Add ) -2. Make sure your Go paths are set correctly: the `.../go/bin` path is in `$PATH`, `$GOROOT` is set to `.../go/`, and `$GOPATH` is the location of where you want lit to be. +3. Download the lit project with `go get github.com/mit-dci/lit` -3. Download the lit project: `go get github.com/mit-dci/lit` +### Building -4. Run lit: +1. Go to the location of your lit installation with your defined gopath variable (`$GOPATH` on Linux and `%GOPATH%` Windows) to the lit location ``` -user@host:~/go/src/github.com/mit-dci/lit$ ./lit -tn3 my.testnet3.node.tld +cd [gopath]/src/github.com/mit-dci/lit ``` +2. If you try to build now with `go build` you will receive several errors such as +``` +cannot find package "golang.org/x/crypto/nacl/secretbox" +... +cannot find package "golang.org/x/crypto/scrypt" +... +cannot find package [packageName] +... +``` + +3. For each unfound package, you will need to use go to download these libraries into your GOPATH. For each outer package use `go get` to download the repositories. + +i.e. +``` +go get golang.org/x/crypto +``` + +4. Go back to location of the lit foler if you are not already there ([Step 1](#building)) and try to rebuild the project. + +5. You may now want to build `lit-af`, the text based client which controls the lit node using +``` +cd cmd/lit-af +go build +``` + +6. If you run into anymore dependency errors, repeat Step 3 by using `go get` for all of the missing packages. + +7. To run lit use: +(Note : Windows users can take off ./ but may need to chagne lit to lit.exe in the second line.) +``` +cd GOPATH/src/github.com/mit-dci/lit +./lit -spv my.testnet.node.tld +``` + +## Using Lightning + +Great! Now that you are all done setting up Lit, you can +- read about the arguments for starting Lit [here](#command-line-arguments) +- read about the folders for the code and what does what [here](#folders) +- head over to the [Walkthrough](./WALKTHROUGH.md) to create some lit nodes or +- check out how to [Contribute](./CONTRIBUTING.md). + + + ## Command line arguments (a lit.conf file is not yet implemented but is on the TODO list) @@ -63,7 +117,7 @@ start synchronization of the blockchain from . (probably doesn't work r try to re-sync to the blockchain from the height give in -tip -## Folders: +## Folders ### cmd has some rpc client code to interact with the lit node. Not much there yet @@ -71,6 +125,12 @@ has some rpc client code to interact with the lit node. Not much there yet ### elkrem a hash-tree for storing log(n) items instead of n +### litbamf +Lightning Network Browser Actuated Multi-Functionality -- web gui for lit + +### litrpc +websocket based RPC connection + ### lndc lightning network data connection -- send encrypted / authenticated messages between nodes @@ -80,17 +140,28 @@ some widely used utility functions ### portxo portable utxo format, exchangable between node and base wallet (or between wallets). Should make this into a BIP once it's more stable. +### powless +Introduces a web API chainhook in addition to the uspv one + ### qln A quick, channel implementation with databases. Doesn't do multihop yet. ### sig64 Library to make signatures 64 bytes instead of 71 or 72 or something +### test +integration tests + +### uspv +deals with the network layer, sending network messages and filtering what to hand over to wallit + +### wallit +deals with storing and retreiving utxos, creating and signing transactions + ### watchtower Unlinkable outsourcing of channel monitoring -### uspv -An spv wallet library + ### Heirarchy of packages @@ -99,12 +170,14 @@ One instance of lit has one litNode (package qln). LitNodes manage lndc connections to other litnodes, manage all channels, rpc listener, and the ln.db. Litnodes then initialize and contol wallits. -wallit A litNode can have multiple wallits; each must have different params. For example, there can be a testnet3 wallit, and a regtest wallit. Eventually it might make sense to support a root key per wallit, but right now the litNode gives a rootPrivkey to each wallet on startup. Wallits each have a db file which tracks utxos, addresses, and outpoints to watch for the upper litNode. Wallits do not directly do any network communication. Instead, wallits have one or more chainhooks; a chainhook is an interface that talks to the blockchain. -uspv One package that implements the chainhook interface is uspv. Uspv deals with headers, wire messages to fullnodes, filters, and all the other mess that is contemporary SPV. (in theory it shouldn't be too hard to write a package that implements the chainhook interface and talks to some block explorer. Maybe if you ran your own explorer and authed and stuff that'd be OK.) + + +## License +[MIT](https://github.com/mit-dci/lit/blob/master/LICENSE) diff --git a/WALKTHROUGH.md b/WALKTHROUGH.md index 429a918ed..27e0e24a6 100644 --- a/WALKTHROUGH.md +++ b/WALKTHROUGH.md @@ -1,12 +1,12 @@ -## Lit 0.0 Walkthrough - 2017-01-09 Lit sortof works on testnet. There are known bugs / omissions / errors, and also unknown ones! Reporting bugs / crashes is helpful, and fixing them is even more helpful. -This walkthrough is to set people up who want send payments over channels on a test network. +## Lit 0.0 Walkthrough +This walkthrough is to set people up who want to send payments over channels on a test network. If you haven't already, make sure to go to the [README](./README.md) for setup instructions. + ### Step 1: Files in place -Look at README.md to get set up with goalng, the dependencies and the code. Build the binary, lit. Also, co into cmd/lit-af and build the lit-af binary there. lit-af is the text based client which controls the lit node. +Make sure you have built both the `lit` and `lit-af` (in `cmd/lit-af`) packages with `go build` If you have a full node, like bitcoind or btcd, start running that as well, either on testnet3 or regtest mode. @@ -14,9 +14,11 @@ For this walkthrough, you will run 2 lit nodes and have them make channels. It' In this example, there are 2 computers. Most things should work the same with 1 computer; just make sure to have 2 different folders for the lit nodes. -Set up two folders: +Set up two folders (i.e. anode and bnode) and copy both the `lit` and `lit-af` executables you built into both folders. -Alice's setup +Here is a sample for Linux users who have not already built the packages + +#### Alice's setup ``` alice@pi2:~$ mkdir anode @@ -30,22 +32,9 @@ alice@pi2:~/gofolder/src/github.com/mit-dci/lit/cmd/lit-af$ cd ~/anode/ alice@pi2:~/anode$ ``` -Bob's setup -``` -bob@pi3:~$ mkdir bnode -bob@pi3:~$ cd gofolder/src/github.com/mit-dci/lit -bob@pi3:~/gofolder/src/github.com/mit-dci/lit$ go build -bob@pi3:~/gofolder/src/github.com/mit-dci/lit$ cp lit ~/bnode/ -bob@pi3:~/gofolder/src/github.com/mit-dci/lit$ cd cmd/lit-af -bob@pi3:~/gofolder/src/github.com/mit-dci/lit/cmd/lit-af$ go build -bob@pi3:~/gofolder/src/github.com/mit-dci/lit/cmd/lit-af$ cp lit-af ~/bnode/ -bob@pi3:~/gofolder/src/github.com/mit-dci/lit/cmd/lit-af$ cd ~/bnode/ -bob@pi3:~/bnode$ -``` - ### Step 2: Run lit and sync up -Alice starts running lit and syncs up to the blockchain. The lit node will print lots of stuff on the screen, but can't be controlled from here. +Alice starts running lit (with `./lit -spv fullnode.net`) and syncs up to the blockchain. The lit node will print lots of stuff on the screen, but can't be controlled from here. Alice connects to her full node, fullnode.net. By default this is on testnet3, using port 18333. @@ -62,7 +51,7 @@ WARNING!! Key file not encrypted!! Here Alice can type a passphrase to secure the wallet the newborn lit node is generating. But she just pressed enter twice, because this is testnet. Even though it's testnet, lit will show warnings about not using a passphrase. -Now in another window, alice connects to the lit node over RPC. +Now in another window, alice connects to the lit node over RPC using `./lit-af` ``` alice@pi2:~/anode$ ./lit-af @@ -76,9 +65,9 @@ Sync Height 1060000 ``` -ls shows how much money Alice has, which is none. She can get some from a faucet. +ls shows how much money Alice has, which is none. She can get some from a faucet. One such faucet you can find [here](https://testnet.manu.backend.hamburg/faucet). -Bob can start a wallet in the same way; if bob's node is running on the same computer, he'll have to run lit with -rpcport to listen on a different port, and start lit-af with -p to connect to that port. Once Alice and Bob are both set up, they can connect to each other. +Bob can start a wallet in the same way; if Bob's node is running on the same computer, he'll have to run lit with -rpcport to listen on a different port, and start lit-af with -p to connect to that port. Once Alice and Bob are both set up, they can connect to each other. ### Step 3: Connect @@ -93,7 +82,7 @@ listening on :2448 with key n1ozwFWDbZXKYjqwySv3VaTxNZvdVmQcam n1ozwFWDbZXKYjqwySv3VaTxNZvdVmQcam is Alice's node-ID (This format will change soon). She's listening on port 2448, but any port can be specified with the `lis` command. -Bob can connect to Alice: +Bob can connect to Alice using her node-ID: ``` lit-af# con n1ozwFWDbZXKYjqwySv3VaTxNZvdVmQcam@pi2 @@ -106,9 +95,21 @@ entered command: say 1 Hi Alice! Bob puts the pubkey@hostname for Alice and connects. Then he says hi to Alice. -### Step 4: Open a channel +### Step 4: Sweep Funds + +Before Bob can make a channel, he needs to sweep his coins to make sure they are in his segwit address. + +``` +lit-af# sweep H5qcg9CudN1KyHKx5h1R87tspxmZ4rPSypQ6w 50000000 +entered command: sweep H5qcg9CudN1KyHKx5h1R87tspxmZ4rPSypQ6w 50000000 +Swept +0 acd0bf89ee6902f6c66cd831fe332f6f89eab2d613de4120dc3791df44885bb1 +1 f28aae0860cefadc921a661bf77f5ab80f7a0d7a64c5269093219a99e345dac7 +``` + +### Step 5: Open a channel -Bob is connected to Alice and wants to open a payment channel. Bob has already made sure he has channel-ready coins by sweeping some to himself using the sweep command to his segwit address. If he has enough money and is connected to Alice, he can open a channel. +Bob is connected to Alice and wants to open a payment channel. If he has enough (segwit) money and is connected to Alice, he can open a channel. ``` lit-af# fund 1 50000000 0 @@ -116,7 +117,7 @@ lit-af# fund 1 50000000 0 This opens a channel with peer 1 (Alice) with a channel capacity of 50,000,000 satoshis (half a coin), and sends 0 satoshis over in the creation process. Bob starts out with all 50,000,000 satoshis in the channel, so only he can send to Alice. -### Step 5: Send micro-payments +### Step 6: Send micro-payments (Do they count as micro-payments if testnet coins have zero value?) @@ -128,7 +129,7 @@ lit-af# push 1 200000 This pushes 200,000 satoshis to the other side of the channel. You can do this 200 trillion times before the channel needs to be closed. (Actually, since I don't think you can send that many payments, the software will probably crash if you do manage to exceed 2^48) -### Step 6: Close/Break the channel +### Step 7: Close/Break the channel You can close the channel cooperatively using: