Author(s):
Maintainer(s):
Under normal operation, Lassie only returns IPLD data in CAR format. Specifically, the CARv1 format. This document describes the nature of the CAR data returned by Lassie and the various options available to the client for varying the data included.
CARv1 allows for multiple roots to be included in a single CAR. Lassie will always return a CAR with a single root CID. This root CID will be the CID of the IPLD block that was requested by the client, even when an additional path is supplied.
Lassie will always return a CAR that is verifiable. This means that the CAR will contain all blocks required to verify the root CID and any additional path traversals to the requested content. It should always be possible to verify the root block content against the requested CID, and every block that is traversed to reach the content as specified by the final path.
Lassie will always return a CAR with a stable block ordering based on the traversal required to (a) navigate from the root CID to the final content where a path is provided, and (b) fetch the required DAG or partial DAG at the termination of that path, or from the root block where no path is provided. Blocks will be provided as they are encountered during a traversal, which works from "leftmost" link within a block/node to the "rightmost". The precise ordering will depend on how the data has been encoded, although this ordering is stable where standard (and properly implemented) codecs were used to generate the data. See https://ipld.io/specs/codecs/ for more information on IPLD codecs and block ordering, specifically see DAG-PB Link Sorting which defines how UnixFS directory listings are ordered.
Where blocks are referenced multiple times within a DAG, it will only be included once, when it is encountered first during the traversal.
Identity CIDs will not be present as separate blocks within a CAR returned by Lassie.
All traversals will include the content at the termination of the path specifier, as well as all blocks from the root CID to the path terminus where a path is provided. At the termination of a provided path, or from the root CID where no path is provided, the depth of the DAG returned may vary depending on the request or available data.
A "shallow" (e.g. when using depthType=shallow with the (HTTP)[HTTP_SPEC.md] server) traversal will include the entire UnixFS entity if the content is found to be UnixFS data. i.e. if the terminus is a sharded UnixFS file, or a sharded UnixFS directory, the blocks required to reconsititute the entire file, or directory will be included. If the termination is a UnixFS sharded directory, only the full directory will be included, not the full DAG of the directory's contents.
A "full" (e.g. when using depthType=full with the (HTTP)[HTTP_SPEC.md] server) traversal will include the entire DAG from the termination of a path, or from the root CID where no path is provided.
Under certain conditions, a complete DAG may not be returned.
- When a Filecoin storage provider chosen to retrieve from does not have the full DAG, only the portion that they do have will be included.
- When a Bitswap session is unable to exhaustively discover all blocks in a DAG, only the portion that was discovered will be included.