Trustless Gateway Specification

2.1.1 Accept (request header)

A Client SHOULD send this HTTP header to leverage content type negotiation based on section 12.5.1 of [rfc9110].

Below response types MUST be supported:

• application/vnd.ipld.raw
  • A single, verifiable raw block to be returned.

Below response types SHOULD be supported:

• application/vnd.ipld.car

  • Disables IPLD/IPFS deserialization, requests a verifiable CAR stream to be returned, implementations MAY support optional CAR content type parameters ([ipip-0412]) and the explicit CAR format signaling in HTTP Request.

• application/vnd.ipfs.ipns-record

  • A verifiable [ipns-record] (multicodec 0x0300).

A Gateway SHOULD return HTTP 400 Bad Request when running in strict trustless mode (no deserialized responses) and Accept header is missing.

2.2.1 format (request query parameter)

Same as format in [path-gateway], but with limited number of supported response types:

• format=raw → application/vnd.ipld.raw
• format=car → application/vnd.ipld.car
• format=ipns-record → application/vnd.ipfs.ipns-record

A Client SHOULD include the format query parameter in the request URL, in addition to the Accept header. This provides the best interoperability and ensures consistent HTTP cache behavior across various gateway implementations.

2.2.2 dag-scope (request query parameter)

Optional, dag-scope=(block|entity|all) with default value all, only available for CAR requests.

Describes the shape of the DAG fetched the terminus of the specified path whose blocks are included in the returned CAR file after the blocks required to traverse path segments.

• block - Only the root block at the end of the path is returned after blocks required to verify the specified path segments.

• entity - For queries that traverse UnixFS data, entity roughly means return blocks needed to verify the terminating element of the requested content path. For UnixFS, all the blocks needed to read an entire UnixFS file, or enumerate a UnixFS directory. For all queries that reference non-UnixFS data, entity is equivalent to block

• all - Transmit the entire contiguous DAG that begins at the end of the path query, after blocks required to verify path segments

When present, returned Etag must include unique prefix based on the passed scope type.

2.2.3 entity-bytes (request query parameter)

The optional entity-bytes=from:to parameter is available only for CAR requests.

It implies dag-scope=entity and serves as a trustless equivalent of an HTTP Range Request.

When the terminating entity at the end of the specified content path:

• can be interpreted as a continuous array of bytes (such as a UnixFS file), a Gateway MUST return only the minimal set of blocks necessary to verify the specified byte range of that entity.

  • When dealing with a sharded UnixFS file (dag-pb, 0x70) and a non-zero from value, the UnixFS data and blocksizes determine the corresponding starting block for a given from offset.

• cannot be interpreted as a continuous array of bytes (such as a DAG-CBOR/JSON map or UnixFS directory), the parameter MUST be ignored, and the request is equivalent to dag-scope=entity.

Allowed values for from and to follow a subset of section 14.1.2 from [rfc9110], where they are defined as offset integers that limit the returned blocks to only those necessary to satisfy the range [from,to]:

• from value gives the byte-offset of the first byte in a range.
• to value gives the byte-offset of the last byte in the range; that is, the byte positions specified are inclusive.

The following additional values are supported:

• * can be substituted for end-of-file
  • entity-bytes=0:* is the entire file (a verifiable version of HTTP request for Range: 0-)
• Negative numbers can be used for referring to bytes from the end of a file
  • entity-bytes=-1024:* is the last 1024 bytes of a file (verifiable version of HTTP request for Range: -1024)
  • It is also permissible (unlike with HTTP Range Requests) to ask for the range of 500 bytes from the beginning of the file to 1000 bytes from the end: entity-bytes=499:-1000

A Gateway MUST augment the returned Etag based on the passed entity-bytes.

A Gateway SHOULD return an HTTP 400 Bad Request error when the requested range cannot be parsed as valid offset positions.

In more nuanced error scenarios, a Gateway MUST return a valid CAR response that includes enough blocks for the client to understand why the requested entity-bytes was incorrect or why only a part of the requested byte range was returned:

• If the requested entity-bytes resolves to a range that partially falls outside the entity's byte range, the response MUST include the subset of blocks within the entity's bytes.

  • This allows clients to request valid ranges of the entity without needing to know its total size beforehand, and it does not require the Gateway to buffer the entire entity before returning the response.

• If the requested entity-bytes resolves to a zero-length range or falls fully outside the entity's bytes, the response is equivalent to dag-scope=block.

  • This allows client to produce a meaningful error (e.g, in case of UnixFS, leverage Data.blocksizes information present in the root dag-pb block).

• In streaming scenarios, if a Gateway is capable of returning the root block but lacks prior knowledge of the final component of the requested content path being invalid or absent in the DAG, a Gateway SHOULD respond with HTTP 200.

  • This behavior is a consequence of HTTP streaming limitations: blocks are not buffered, by the time a related parent block is being parsed and returned to the client, the HTTP status code has already been sent to the client.

2.2.4 car-version (request query parameter)

Optional, only used on CAR requests.

Serves same purpose as CAR version content type parameter.

In case both are present in the request, the value from the Accept HTTP Header has priority and a matching Content-Location SHOULD be returned with the response.

2.2.5 car-order (request query parameter)

Optional, only used on CAR requests.

Serves same purpose as CAR order content type parameter.

In case both are present in the request, the value from the Accept HTTP Header has priority and a matching Content-Location SHOULD be returned with the response.

2.2.6 car-dups (request query parameter)

Optional, only used on CAR requests.

Serves same purpose as CAR dups content type parameter.

In case both are present in the request, the value from the Accept HTTP Header has priority and a matching Content-Location SHOULD be returned with the response.

3.1.1 Content-Type (response header)

MUST be returned and include additional format-specific parameters when possible.

If a CAR stream was requested:

• the response MUST include the parameter specifying CAR version. For example: Content-Type: application/vnd.ipld.car; version=1
• the response SHOULD include additional content type parameters, as noted in CAR format signaling in Response.

3.1.2 Content-Disposition (response header)

MUST be returned and set to attachment to ensure requested bytes are not rendered by a web browser.

3.1.3 Content-Location (response header)

Same as in [path-gateway], SHOULD be returned when Trustless Gateway supports more than a single response format and the format query parameter is missing or does not match well-known format from Accept header.

5.5.1 CAR format signaling in Request

Content type negotiation is based on section 12.5.1 of [rfc9110].

Clients MAY indicate their preferred block order by sending an Accept header in the HTTP request. The Accept header format is as follows:

Accept: application/vnd.ipld.car; version=1; order=dfs; dups=y

In the future, when more orders or parameters exist, clients will be able to specify a list of preferences, for example:

Accept: application/vnd.ipld.car;order=foo, application/vnd.ipld.car;order=dfs;dups=y;q=0.5

The above example is a list of preferences, the client would really like to use the hypothetical order=foo however if this isn't available it would accept order=dfs with dups=y instead (lower priority indicated via q parameter, as noted in [rfc9110]).

5.5.2 CAR format signaling in Response

The Trustless Gateway MUST always respond with a Content-Type header that includes information about all supported and known parameters, even if the client did not specify them in the request.

The Content-Type header format is as follows:

Content-Type: application/vnd.ipld.car;version=1;order=dfs;dups=n

Gateway implementations SHOULD decide on the implicit default ordering or other parameters, and use it in responses when client did not explicitly specify any matching preference.

A Gateway MAY choose to implement only some parameters and return HTTP 400 Bad Request or 406 Not Acceptable when a client requested a response with unsupported content type variant.

A Client MUST verify Content-Type returned with CAR response before processing the payload, as the legacy gateway may not support optional content type parameters like order an dups and return plain application/vnd.ipld.car.