cleanup docs and move migration fns to chain itself

chain/src/chain.rs

@@ -189,7 +189,7 @@ impl Chain {
 		)?;
 		Chain::log_heads(&store)?;
 
-		Ok(Chain {
+		let chain = Chain {
 			db_root,
 			store,
 			adapter,
@@ -201,7 +201,18 @@ impl Chain {
 			verifier_cache,
 			archive_mode,
 			genesis: genesis.header.clone(),
-		})
+		};
+
+		// DB migrations to be run prior to the chain being used.
+		{
+			// Migrate full blocks to protocol version v2.
+			chain.migrate_db_v1_v2()?;
+
+			// Rebuild height_for_pos index.
+			chain.rebuild_height_for_pos()?;
+		}
+
+		Ok(chain)
 	}
 
 	/// Return our shared header MMR handle.
@@ -1245,10 +1256,12 @@ impl Chain {
 		self.header_pmmr.read().get_header_hash_by_height(height)
 	}
 
-	pub fn migrate_db_v1_v2(&self) -> Result<(), Error> {
+	/// Migrate our local db from v1 to v2.
+	/// This covers blocks which themselves contain transactions.
+	/// Transaction kernels changed in v2 due to "variable size kernels".
+	fn migrate_db_v1_v2(&self) -> Result<(), Error> {
 		let store_v1 = self.store.with_version(ProtocolVersion(1));
 		let batch = store_v1.batch()?;
-		// Note: the iterator here returns None
 		for (_, block) in batch.blocks_iter()? {
 			batch.migrate_block(&block, ProtocolVersion(2))?;
 		}
@@ -1258,7 +1271,7 @@ impl Chain {
 
 	/// Migrate the index 'commitment -> output_pos' to index 'commitment -> (output_pos, block_height)'
 	/// Note: should only be called when Node start-up, for database migration from the old version.
-	pub fn rebuild_height_for_pos(&self) -> Result<(), Error> {
+	fn rebuild_height_for_pos(&self) -> Result<(), Error> {
 		let header_pmmr = self.header_pmmr.read();
 		let txhashset = self.txhashset.read();
 		let mut outputs_pos = txhashset.get_all_output_pos()?;

chain/src/store.rs

@@ -51,6 +51,10 @@ impl ChainStore {
 		Ok(ChainStore { db })
 	}
 
+	/// Create a new instance of the chain store based on this instance
+	/// but with the provided protocol version. This is used when migrating
+	/// data in the db to a different protocol version, reading using one version and
+	/// writing back to the db with a different version.
 	pub fn with_version(&self, version: ProtocolVersion) -> ChainStore {
 		let db_with_version = self.db.with_version(version);
 		ChainStore {
@@ -266,6 +270,8 @@ impl<'a> Batch<'a> {
 		Ok(())
 	}
 
+	/// Migrate a block stored in the db by serializing it using the provided protocol version.
+	/// Block may have been read using a previous protocol version but we do not actually care.
 	pub fn migrate_block(&self, b: &Block, version: ProtocolVersion) -> Result<(), Error> {
 		self.db.put_ser_with_version(
 			&to_key(BLOCK_PREFIX, &mut b.hash().to_vec())[..],

servers/src/grin/server.rs

@@ -189,17 +189,6 @@ impl Server {
 			archive_mode,
 		)?);
 
-		// TODO - Move this to Chain::init() I think.
-		//
-		// DB migrations to be run prior to the chain being used.
-		{
-			// migrate full blocks to protocol version v2 as necessary
-			shared_chain.migrate_db_v1_v2()?;
-
-			// rebuild height_for_pos index as necessary
-			shared_chain.rebuild_height_for_pos()?;
-		}
-
 		pool_adapter.set_chain(shared_chain.clone());
 
 		let net_adapter = Arc::new(NetToChainAdapter::new(