From 8bb2b239abbaf93e31a783a6ff48655cf7c14f1e Mon Sep 17 00:00:00 2001
From: Marcin Rataj <lidel@lidel.org>
Date: Tue, 6 Jun 2023 19:04:44 +0200
Subject: [PATCH] ipip-402: clarify CarV1Header.roots

Rationale:
https://github.com/ipfs/specs/pull/402#discussion_r1219974718
---
 src/http-gateways/trustless-gateway.md | 47 ++++----------------------
 1 file changed, 7 insertions(+), 40 deletions(-)

diff --git a/src/http-gateways/trustless-gateway.md b/src/http-gateways/trustless-gateway.md
index 5611df53..46b572dc 100644
--- a/src/http-gateways/trustless-gateway.md
+++ b/src/http-gateways/trustless-gateway.md
@@ -136,13 +136,13 @@ When present, returned `Etag` must include unique prefix based on the passed ran
 
 Below MUST be implemented **in addition** to "HTTP Response" of :cite[path-gateway].
 
-## HTTP Response Headers
+## Response Headers
 
 ### `Content-Disposition` (response header)
 
 MUST be returned and set to `attachment` to ensure requested bytes are not rendered by a web browser.
 
-## HTTP Response Payload
+## Response Payload
 
 ### Block Response
 
@@ -168,46 +168,13 @@ responses MAY be introduced in a future, see [IPIP-412](https://github.com/ipfs/
 
 #### CAR version
 
-Value returned in `CarV1Header.version` struct  MUST match the `version`
-parameter returned in `Content-Type` header
+Value returned in
+[`CarV1Header.version`](https://ipld.io/specs/transport/car/carv1/#header)
+field MUST match the `version` parameter returned in `Content-Type` header.
 
 #### CAR roots
 
-:::issue
-
-TODO: we need to specify expectations about what should be returned in
-[`CarV1Header.roots`](https://ipld.io/specs/transport/car/carv1/#header).
-
-##### Option A: always empty
-
-If the response uses version 1 or 2 of the CAR spec, the
-[`CarV1Header.roots`](https://ipld.io/specs/transport/car/carv1/#header) struct
-MUST be empty.
-
-##### Option B: only CID of the terminating element
-
 If the response uses version 1 or 2 of the CAR spec, the
-[`CarV1Header.roots`](https://ipld.io/specs/transport/car/carv1/#header) struct
-MUST contain CID of the terminating entity.
+[`CarV1Header.roots`](https://ipld.io/specs/transport/car/carv1/#header) field
+MUST contain the CID of the terminating entity.
 
-##### Option C: only CIDs of fully returned DAGs
-
-If the response uses version 1 or 2 of the CAR spec, the
-[`CarV1Header.roots`](https://ipld.io/specs/transport/car/carv1/#header) struct
-MUST be either empty, or only contain CIDs of complete DAGs present in the response.
-
-CIDs from partial DAGs, such as parent nodes on the path, or terminating
-element returned with `dag-scope=block`, or UnixFS directory returned with
-`dag-scope=entity` MUST never be returned in the `CarV1Header.roots` list, as
-they may cause overfetching on systems that perform recursive pinning of DAGs
-listed in `CarV1Header.roots`.
-
-##### Option D: CIDs for all logical path segments (same as X-Ipfs-Roots)
-
-If the response uses version 1 or 2 of the CAR spec, the
-[`CarV1Header.roots`](https://ipld.io/specs/transport/car/carv1/#header) struct
-MUST contain all the logical roots related to the requested content path.
-
-The CIDs here MUST be the same as ones in `X-Ipfs-Roots` header.
-
-:::