Basic retrieval

There are multiple ways to fetch data from a storage provider. This pages covers some of the most popular methods.

Lassie

Lassie is a simple retrieval client for Filecoin. It finds and fetches your data over the best retrieval protocols available.

Prerequisites

Make sure that you have Go installed and that your GOPATH is set up. By default, your GOPATH will be set to ~/go.

Install Lassie

  1. Download and install Lassie using the Go package manager:

    go install github.com/filecoin-project/lassie/cmd/lassie@latest
    
    go: downloading github.com/filecoin-project/lassie v0.3.1
    go: downloading github.com/libp2p/go-libp2p v0.23.2
    go: downloading github.com/filecoin-project/go-state-types v0.9.9
    
    ...
    
  2. Install the go-car package using the Go package manager:

    go install github.com/ipld/go-car/cmd/car@latest
    
    go: downloading github.com/ipld/go-car v0.6.0
    go: downloading github.com/ipld/go-car/cmd v0.0.0-20230215023242-a2a8d2f9f60f
    go: downloading github.com/ipld/go-codec-dagpb v1.6.0 
    
    ...
    

    The go-car package makes it easier to work with content-addressed archive (CAR) files.

You now have everything you need to retrieve a file with Lassie and extract the contents with Go-car.

Retrieve

To retrieve data from Filecoin using Lassie, all you need is the CID of the content you want to download. You can use the following CIDs to test the process:

  1. The format for retrieving data using Lassie is:

    lassie fetch -o <OUTFILE_FILE_NAME> -p <CID>
    

    For example:

    lassie fetch -o output.car -p bafykbzaceatihez66rzmzuvfx5nqqik73hlphem3dvagmixmay3arvqd66ng6
    
    Fetching bafykbzaceatihez66rzmzuvfx5nqqik73hlphem3dvagmixmay3arvqd66ng6
    Querying indexer for bafykbzaceatihez66rzmzuvfx5nqqik73hlphem3dvagmixmay3arvqd66ng6...
    Found 4 storage providers candidates from the indexer, querying all of them:
            12D3KooWPNbkEgjdBNeaCGpsgCrPRETe4uBZf1ShFXStobdN18ys
            12D3KooWNHwmwNRkMEP6VqDCpjSZkqripoJgN7eWruvXXqC2kG9f
            12D3KooWKGCcFVSAUXxe7YP62wiwsBvpCmMomnNauJCA67XbmHYj
            12D3KooWLDf6KCzeMv16qPRaJsTLKJ5fR523h65iaYSRNfrQy7eU
    Querying [12D3KooWLDf6KCzeMv16qPRaJsTLKJ5fR523h65iaYSRNfrQy7eU] (started)...
    Querying [12D3KooWKGCcFVSAUXxe7YP62wiwsBvpCmMomnNauJCA67XbmHYj] (started)...
    
    ...
    
  2. This will create an output.car file within your current directory:

    ls -l
    
    total 143M
    -rw-rw-r-- 1 user user 143M Feb 16 11:21 output.car
    

Extract data

Now that we’ve downloaded a CAR file, we need to find out what’s inside it.

  1. The format for extracting a .car file using Go-car is:

    car extract --file <INPUT_FILE>
    
  2. Extract the output.car file we just downloaded using Lassie:

    car extract --file output.car
    

    This command does not output anything on success.

  3. You can list the output of the car command with ls:

    ls -lh
    
    -rw-rw-r-- 1 user user 143M Feb 16 11:21 output.car
    -rw-rw-r-- 1 user user 143M Feb 16 11:36 moon-data.tar.gz
    
  4. You can then manage the data as you need.

And there we have it! Downloading and managing data from Filecoin is super simple when you use Lassie and Go-car!