From a66cc93c513ddef136297d2759eaa156ec97d226 Mon Sep 17 00:00:00 2001
From: Rod Vagg <rod@vagg.org>
Date: Fri, 29 Sep 2023 12:35:37 +1000
Subject: [PATCH] doc: root CID clarification docs

Closes: https://github.com/filecoin-project/lassie/issues/248
---
 README.md            |  7 +++++++
 pkg/types/request.go | 13 +++++++++----
 pkg/types/types.go   |  9 ++++++---
 3 files changed, 22 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 31331b6a..54641d8a 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,7 @@
 	* [HTTP API](#http-api)
 		* [Daemon Example](#daemon-example)
 	* [Golang Library](#golang-library)
+	* [Roots, pieces and payloads](#roots-pieces-and-payloads)
 * [Contribute](#contribute)
 * [License](#license)
 
@@ -277,6 +278,12 @@ if err != nil {
 
 The `Fetch` function takes a `context.Context`, a `*types.Request`, and a `*types.FetchOptions`. The `context.Context` is used to control the lifecycle of the fetch. The `*types.Request` is the fetch request we made above. The `*types.FetchOptions` is used to control the behavior of the fetch. The function returns a `*types.FetchStats` and an `error`. The `*types.FetchStats` is the fetch stats. The `error` is used to indicate if there was an error fetching the CID.
 
+### Roots, pieces and payloads
+
+Lassie uses the term **Root** to refer to the head block of a potential graph (DAG) of IPLD blocks. This is typically the block you request, using its CID, when you perform a _fetch_ with Lassie. Of course a root could also be a sub-root of a larger graph, but when performing a retrieval with Lassie, you are focusing on the graph underneath the block you are fetching, and considerations of larger DAGs are not relevant.
+
+In the Filecoin ecosystem, there exists terminology related to "pieces" and "payloads" and there may be confusion between the way lassie uses the term "root CID" and some of the language used in Filecoin. A **Piece** is a Filecoin storage deal unit, typically containing user data organized into a CAR; then padded to size to form a portion of a Filecoin sector. Filecoin pieces have their own CIDs, and it is possible to retrieve a whole, raw piece, from Filecoin. This can lead to terminology such as "piece root CID". Lassie currently does not perform whole-piece retrievals, and is not intended to be able to handle piece CIDs. Additionally, in Filecoin the term **Payload** is sometimes used in reference to the IPLD data inside a piece when performing a storage or retrieval deal. This is closer to the way Lassie uses the term **Root** and historical Lassie code contains some references to "payloads" that are actually referring to the root CID of a graph.
+
 ## Contribute
 
 Early days PRs are welcome!
diff --git a/pkg/types/request.go b/pkg/types/request.go
index 0984b548..1a1679c8 100644
--- a/pkg/types/request.go
+++ b/pkg/types/request.go
@@ -84,8 +84,13 @@ type RetrievalRequest struct {
 	FixedPeers []peer.AddrInfo
 }
 
-// NewRequestForPath creates a new RetrievalRequest from the provided parameters
-// and assigns a new RetrievalID to it.
+// NewRequestForPath creates a new RetrievalRequest for the given root CID as
+// the head of the graph to fetch, the path within that graph to fetch, the
+// scope that dictates the depth of fetching withint he graph and the byte
+// range to fetch if intending to fetch part of a large UnixFS file.
+//
+// The byteRange parameter should be left nil if this is not a request for a
+// partial UnixFS file; and if it is set, the dagScope should be DagScopeEntity.
 //
 // The LinkSystem is configured to use the provided store for both reading
 // and writing and it is explicitly set to be trusted (i.e. it will not
@@ -93,7 +98,7 @@ type RetrievalRequest struct {
 // request.LinkSystem.TrustedStore should be set to false after this call.
 func NewRequestForPath(
 	store ipldstorage.WritableStorage,
-	cid cid.Cid,
+	rootCid cid.Cid,
 	path string,
 	dagScope trustlessutils.DagScope,
 	byteRange *trustlessutils.ByteRange,
@@ -114,7 +119,7 @@ func NewRequestForPath(
 
 	return RetrievalRequest{
 		Request: trustlessutils.Request{
-			Root:       cid,
+			Root:       rootCid,
 			Path:       path,
 			Scope:      dagScope,
 			Bytes:      byteRange,
diff --git a/pkg/types/types.go b/pkg/types/types.go
index 1e59739d..fe65ce44 100644
--- a/pkg/types/types.go
+++ b/pkg/types/types.go
@@ -45,9 +45,12 @@ func NewFetchConfig(opts ...FetchOption) FetchConfig {
 }
 
 // RetrievalCandidate describes a peer and CID combination that can be used to
-// retrieve data from the peer. The Metadata field contains information about
-// the protocols supported by the peer that may be used to further refine
-// how the retrieval is performed.
+// retrieve data from the peer. The RootCid describes the head of an IPLD graph
+// that is being retrieved. The MinerPeer is the peer that is (apparently)
+// storing the data.
+//
+// The Metadata field contains information about the protocols supported by the
+// peer that may be used to further refine how the retrieval is performed.
 type RetrievalCandidate struct {
 	MinerPeer peer.AddrInfo
 	RootCid   cid.Cid