Various doc improvements

README.md

@@ -1,7 +1,9 @@
 # Moonbeam
 
-Moonbeam is a protocol built on top of Bitcoin that allows for instant
-off-chain payments between untrusted parties using payment channels.
+Moonbeam is a protocol that uses Bitcoin payment channels to facilitate instant off-chain payments between multi-user platforms.
+
+Moonbeam doesn't require segwit or larger blocks, and can be deployed on the
+Bitcoin network today.
 
 This repository contains the protocol specification, documentation and
 reference implementation.
@@ -19,9 +21,9 @@ in a decentralized way. An address in Moonbeam looks like this:
 `[email protected]`
 
 The @example.com piece means that this address is handled by the example.com
-domain. Platforms can use the domain name to automatically open Moonbeam
+domain. Platforms can use these domain names to automatically open Moonbeam
 channels and send payments without any prior arrangements or agreements, as
-long as they both implement the Moonbeam protocol.
+long as they implement the Moonbeam protocol.
 
 Moonbeam is designed to be easily adopted by users. Moonbeam addresses contain
 standard Bitcoin addresses so that they can be trivially used with existing
@@ -31,15 +33,15 @@ selectively per-payment).
 
 ## Documentation
 
-[Overview](docs/overview.md)
+[Overview](docs/overview.md) - High-level overview of the system
 
-[Quickstart](docs/quickstart.md)
+[Quickstart](docs/quickstart.md) - Send your first Moonbeam payment on testnet in minutes
 
-[Specification](docs/spec.md)
+[Specification](docs/spec.md) - The full protocol specification
 
-[Go Package Documentation](https://godoc.org/github.com/luno/moonbeam)
+[Go Package Documentation](https://godoc.org/github.com/luno/moonbeam) - Documentation for the reference implementation packages
 
-Demo server (testnet): https://bitcoinmoonbeam.org
+https://bitcoinmoonbeam.org - Demo server on testnet
 
 ## Reference implementation
 

cmd/mbserver/web.go

@@ -41,8 +41,8 @@ const footer = `
 var indexT = template.Must(template.New("index").Parse(header + `
 <h1>Moonbeam</h1>
 
-<p>Moonbeam is a protocol built on top of Bitcoin that allows for instant
-off-chain payments between untrusted parties using payment channels.</p>
+<p>Moonbeam is a protocol that uses Bitcoin payment channels to facilitate
+instant off-chain payments between multi-user platforms.</p>
 
 <p>This is a demo server running on testnet.</p>
 

docs/overview.md

@@ -1,24 +1,36 @@
 # Moonbeam overview
 
-This post attempts to give a high-level overview of Moonbeam.
+This article gives a high-level simplified overview of Moonbeam.
+
+## Table of contents
+
+   * [Moonbeam overview](#moonbeam-overview)
+      * [Introduction](#introduction)
+      * [Basic operation](#basic-operation)
+      * [How a channel works](#how-a-channel-works)
+      * [How domains work](#how-domains-work)
+      * [More information](#more-information)
 
 ## Introduction
 
-Moonbeam is a protocol built on top of Bitcoin that allows for instant off-chain payments between untrusted parties using payment channels.
+Moonbeam is a protocol that uses Bitcoin payment channels to facilitate instant off-chain payments between multi-user platforms.
+
+Moonbeam doesn't require segwit or larger blocks, and can be deployed on the
+Bitcoin network today.
 
 Here is how Moonbeam differs from standard Bitcoin payments:
 
 | Standard Bitcoin payments | Moonbeam payments |
 | --- | --- |
 | On-chain | Off-chain |
 | Requires 30 minute block confirmations | Instant |
-| Requires a fee per transaction | Zero fee per transaction |
+| Requires a fee per transaction | Zero fee per transaction (though platforms may charge) |
 | Don’t require prior setup | Requires prior channel setup |
 | Decentralized | Semi-decentralized |
-| Not suitable for micropayments | Suitable for micropayments |
+| Better for larger payments | Better for smaller payments |
 | Addresses look like: mgzdqkEjYEjR5QNdJxYFnCKZHuNYa5bUZ2 | Addresses look like: [email protected] |
 
-You may have heard of payment channels before in the context of the Lightning Network. Moonbeam and Lightning both use payment channels to process Bitcoin payments off-chain but they solve different problems. While not directly comparable, it’s helpful to contrast them:
+You may have heard of payment channels before in the context of the Lightning Network. Moonbeam and Lightning both use payment channels to process Bitcoin payments off-chain but they have different design goals. While not directly comparable, it’s helpful to contrast them:
 
 | Lightning | Moonbeam |
 | --- | --- |
@@ -28,13 +40,13 @@ You may have heard of payment channels before in the context of the Lightning Ne
 | Uses a peer-to-peer overlay network | Uses standard internet infrastructure |
 | More complicated system | Less complicated system |
 
-Moonbeam is designed especially for use by multi-user platforms such hosted wallets, exchanges and payment processors (e.g. Luno, Coinbase, Bitpay, Bitstamp, etc). We envisage that these platforms will open Moonbeam channels between one another and route their users’ payments through them.
+Moonbeam is designed especially for use by multi-user platforms such hosted wallets, exchanges and payment processors. We envisage that these platforms will open Moonbeam channels between one another and route their users’ payments through them.
 
 Even though Moonbeam is a point-to-point system, it is still designed to work in a decentralized way. An address in Moonbeam looks like this:
 
 `[email protected]`
 
-The @example.com piece means that this address is handled by the example.com domain (or similarly luno.com, coinbase.com, bitpay.com, etc). Platforms can use the domain name to automatically open Moonbeam channels and send payments without any prior arrangements or agreements, as long as they both implement the Moonbeam protocol.
+The @example.com piece means that this address is handled by the example.com domain. Platforms can use these domain names to automatically open Moonbeam channels and send payments without any prior arrangements or agreements, as long as they implement the Moonbeam protocol.
 
 Moonbeam is designed to be easily adopted by users. Moonbeam addresses contain standard Bitcoin addresses so that they can be trivially used with existing Bitcoin software. This also gives platforms flexibility in implementing Moonbeam (e.g. they can implement sending only, receiving only, both, or even selectively per-payment).
 
@@ -66,15 +78,16 @@ transactions.
 ## How a channel works
 
 A payment channel is a simple form of a smart contract.
-The sender committs a certain amount of capital up front into a special multisig
+The sender commits a certain amount of capital upfront into a special multisig
 address. The multisig address requires both the sender and receiver to agree
 on how to split the capital. Initially the entire capital is assigned to the
 sender and none to the receiver. However, whenever a payment is sent over the
 channel, the split is updated to that the receiver is assigned the sum of
-payments.
+payments sent.
 
 The sender and receiver need to agree on the precise rules of the system for
-this to work. The Moonbeam protocol defines these rules.
+this to work. The [Moonbeam protocol specification](spec.md) defines these
+rules.
 
 ## How domains work
 
@@ -84,8 +97,9 @@ coordinate these channels. Instead, we uses the familiar domain name system
 to allow platforms to automatically discover and initiate channels between
 one another.
 
-The Moonbeam protocol defines the procedure to go from a domain name
-(e.g. batwallet.com) to initiating a payment channel.
+The Moonbeam protocol defines the procedure to start from a domain name
+(e.g. batwallet.com), locate the appropriate server, and negotiate and open the
+payment channel.
 
 ## More information
 

docs/quickstart.md

@@ -2,14 +2,17 @@
 
 ## Installation
 
+You must first [download and install Go](https://golang.org/dl/) if you don't
+have it already.
+
 ```bash
 git clone [email protected]:luno/moonbeam.git
 cd moonbeam
 source ./vars.sh
 go get github.com/btcsuite/btcutil
 go get github.com/btcsuite/btcrpcclient
-go install moonbeam/cmd/mbclient
-go install moonbeam/cmd/mbserver
+go install github.com/luno/moonbeam/cmd/mbclient
+go install github.com/luno/moonbeam/cmd/mbserver
 ```
 
 ## Client Guide
@@ -40,14 +43,13 @@ To see the channel info, you can run:
 ./bin/mbclient list -a
 ```
 
-To see the channel info on the server, visit
-https://bitcoinmoonbeam.org/channels
+To see the channel info on the server, visit https://bitcoinmoonbeam.org
 
 ### Fund the channel
 
-Now you need to send some coins to the funding address. You can send any amount.
-This amount will be the maximum channel capacity. You can send it from
-any wallet.
+Now you need to send some coins to the funding address. You can send any amount
+larger than the channel fee. This amount will be the maximum channel capacity.
+You can send it from any wallet.
 
 You must wait for the transaction to confirm before proceeding.
 Once the transaction has confirmed run:
@@ -100,7 +102,7 @@ You can configure the server through flags.
 To start the server:
 
 ```bash
-./bin/mbserver
+./bin/mbserver --destination=<refundaddr> --xprivkey=<your_xprivkey> --auth_token=<random_secret>
 ```
 
 You can then view the server status by visting https://127.0.0.1:3211.