Fix for issue #318 (#323)

* Rename wallet 'receive' to 'listen'
* Handle use of previous 'receive' command gracefully and clarify docs

config/src/config.rs

@@ -205,7 +205,7 @@ fn test_read_config() {
         #Mining section is optional, if it's not here it will default to not mining
         [mining]
         enable_mining = true
-        wallet_receiver_url = "http://127.0.0.1:13415"
+        wallet_listener_url = "http://127.0.0.1:13415"
         burn_reward = false
         #testing value, optional
         #slow_down_in_millis = 30

doc/build.md

@@ -93,6 +93,31 @@ If no configuration file is found, command line switches must be given to grin i
 
 At present, the relevant modes of operation are 'server' and 'wallet'. When running in server mode, any command line switches provided will override the values found in the configuration file. Running in wallet mode does not currently use any values from the configuration file other than logging output parameters.
 
+# Basic Execution
+
+For a basic example simulating a single node network, create a directory called 'node1' and change your working directory to it. You'll use this directory to run a wallet and create a new blockchain via a server running in mining mode.
+
+You'll need a config file - the easiest is to copy over the grin.toml file from the root grin directory into the node1 directory you just made.
+
+Before running your mining server, a wallet server needs to be set up and listening so that the mining server knows where to send mining rewards. Do this from the first node directory with the following commands:
+
+	node1$ grin wallet init
+	node1$ grin wallet -p "password" listen
+
+See [wallet](wallet.md) for more info on the various Grin wallet commands and options.
+
+This will create a wallet server listening on the default port 13415 with the password "password". Next, in another terminal window in the 'node1' directory, run a full mining node with the following command:
+
+	node1$ grin server -m run
+
+This creates a new .grin database directory in the current directory, and begins mining new blocks (with no transactions, for now). Note this starts two services listening on two default ports,
+port 13414 for the peer-to-peer (P2P) service which keeps all nodes synchronized, and 13413 for the Rest API service used to verify transactions and post new transactions to the pool (for example). These ports can be configured via command line switches, or via a grin.toml file in the working directory.
+
+Let the mining server find a few blocks, then stop (just ctrl-c) the mining server and the wallet server. You'll notice grin has created a database directory (.grin) in which the blockchain and peer data is stored. There should also be a wallet.dat file in the current directory, which contains a few coinbase mining rewards created each time the server mines a new block.
+
+## Advanced Example
+>>>>>>> 8d692d2... Fix for issue #318 (#323)
+
 # Running a Node
 
 The following are minimal instructions to get a testnet1 node up and running.
@@ -117,10 +142,7 @@ Next, in the 'server' directory in another terminal window, copy the grin.toml f
 cp /path/to/project/root/grin.toml .
 ```
 
-Then, to start the server node:
-```
-grin server --mine run
-```
+    node3$ grin wallet -p "password" -a "http://127.0.0.1:30001" -l 35000 listen
 
 The server should start, connect to the seed and any available peers, and place mining rewards into your running wallet listener.
 

doc/wallet.md

@@ -39,7 +39,7 @@ key_id, height, lock_height, status, spendable?, coinbase?, value
 ...
 ```
 
-### grin wallet receive
+### grin wallet listen
 
 (tbd)
 
@@ -47,6 +47,10 @@ key_id, height, lock_height, status, spendable?, coinbase?, value
 
 (tbd)
 
+### grin wallet receive
+
+(tbd)
+
 ### grin wallet burn
 
 [tbd]

grin.toml

@@ -112,7 +112,7 @@ attempt_time_per_block = 90
 
 #the wallet reciever to which coinbase rewards will be sent
 
-wallet_receiver_url = "http://127.0.0.1:13415"
+wallet_listener_url = "http://127.0.0.1:13415"
 
 #whether to ignore the reward (mostly for testing)
 

grin/src/miner.rs

@@ -624,7 +624,7 @@ impl Miner {
 		} else {
 			let url = format!(
 				"{}/v1/receive/coinbase",
-				self.config.wallet_receiver_url.as_str()
+				self.config.wallet_listener_url.as_str()
 			);
 
 			let res = wallet::client::create_coinbase(&url, &block_fees)?;

grin/tests/framework/mod.rs

@@ -230,7 +230,7 @@ impl LocalServerContainer {
 			cuckoo_miner_async_mode: Some(false),
 			cuckoo_miner_plugin_dir: Some(String::from("../target/debug/deps")),
 			cuckoo_miner_plugin_config: Some(plugin_config_vec),
-			wallet_receiver_url: self.config.coinbase_wallet_address.clone(),
+			wallet_listener_url: self.config.coinbase_wallet_address.clone(),
 			slow_down_in_millis: Some(self.config.miner_slowdown_in_millis.clone()),
 			..Default::default()
 		};

pow/src/types.rs

@@ -58,7 +58,7 @@ pub struct MinerConfig {
 	pub attempt_time_per_block: u32,
 
 	/// Base address to the HTTP wallet receiver
-	pub wallet_receiver_url: String,
+	pub wallet_listener_url: String,
 
 	/// Attributes the reward to a random private key instead of contacting the
 	/// wallet receiver. Mostly used for tests.
@@ -77,7 +77,7 @@ impl Default for MinerConfig {
 			cuckoo_miner_async_mode: None,
 			cuckoo_miner_plugin_dir: None,
 			cuckoo_miner_plugin_config: None,
-			wallet_receiver_url: "http://localhost:13415".to_string(),
+			wallet_listener_url: "http://localhost:13415".to_string(),
 			burn_reward: false,
 			slow_down_in_millis: Some(0),
 			attempt_time_per_block: 2,

src/bin/grin.rs

@@ -138,7 +138,7 @@ fn main() {
                 .arg(Arg::with_name("wallet_url")
                      .short("w")
                      .long("wallet_url")
-                     .help("A listening wallet receiver to which mining rewards will be sent")
+                     .help("The wallet listener to which mining rewards will be sent")
                 .takes_value(true))
                 .subcommand(SubCommand::with_name("start")
                             .about("Start the Grin server as a daemon"))
@@ -169,9 +169,9 @@ fn main() {
 			directory)")
 			.takes_value(true))
 		.arg(Arg::with_name("port")
-			.short("r")
+			.short("l")
 			.long("port")
-			.help("Port on which to run the wallet receiver when in receiver mode")
+			.help("Port on which to run the wallet listener when in listen mode")
 			.takes_value(true))
 		.arg(Arg::with_name("external")
 			.short("e")
@@ -189,8 +189,8 @@ fn main() {
 			.help("Api address of running node on which to check inputs and post transactions")
 			.takes_value(true))
 
-		.subcommand(SubCommand::with_name("receive")
-			.about("Run the wallet in receiving mode. If an input file is \
+		.subcommand(SubCommand::with_name("listen")
+			.about("Run the wallet in listening mode. If an input file is \
 				provided, will process it, otherwise runs in server mode waiting \
 				for send requests.")
 			.arg(Arg::with_name("input")
@@ -199,6 +199,9 @@ fn main() {
 				.long("input")
 				.takes_value(true)))
 
+		.subcommand(SubCommand::with_name("receive")
+			.about("Depreciated, use 'listen' instead"))
+
 		.subcommand(SubCommand::with_name("send")
 			.about("Builds a transaction to send someone some coins. By default, \
 				the transaction will just be printed to stdout. If a destination is \
@@ -314,7 +317,7 @@ fn server_command(server_args: &ArgMatches, global_config: GlobalConfig) {
 			.mining_config
 			.as_mut()
 			.unwrap()
-			.wallet_receiver_url = wallet_url.to_string();
+			.wallet_listener_url = wallet_url.to_string();
 	}
 
 	if let Some(seeds) = server_args.values_of("seed") {
@@ -397,7 +400,7 @@ fn wallet_command(wallet_args: &ArgMatches) {
 		.expect("Failed to derive keychain from seed file and passphrase.");
 
 	match wallet_args.subcommand() {
-		("receive", Some(receive_args)) => if let Some(f) = receive_args.value_of("input") {
+		("listen", Some(listen_args)) => if let Some(f) = listen_args.value_of("input") {
 			let mut file = File::open(f).expect("Unable to open transaction file.");
 			let mut contents = String::new();
 			file.read_to_string(&mut contents)
@@ -466,6 +469,9 @@ fn wallet_command(wallet_args: &ArgMatches) {
 		("outputs", Some(_)) => {
 			wallet::show_outputs(&wallet_config, &keychain, show_spent);
 		}
+		("receive", Some(_)) => {
+			panic!("Command 'receive' is depreciated, use 'listen' instead");
+		}
 		_ => panic!("Unknown wallet command, use 'grin help wallet' for details"),
 	}
 }