Lily Setup

Lily is a Go application which embeds a Lotus node. Therefore, a lot of the setup process (build, init, sync) resembles that of a Lotus node.

Basic help #

The Lily binary is self-documented and should be used to obtain specific help about flags:

lily help overview # A high-level description of how Lily works
lily help # List all available subcommands
lily <subcommand> --help # Show help for subcommand and subcommand flags

Flags usually have an environment variable equivalent.

Dependencies #

You will need the same dependencies as for Lotus. See the Lotus installation instructions for the installation commands for each distribution.

Build #

Once you have all the dependencies, you can checkout the Lily repository and build the binary:

1. Clone the Repo

git clone https://github.com/filecoin-project/lily.git
cd ./lily

2. Checkout a release

git checkout <release_tag>

3. Build Lily

For Mainnet:

export CGO_ENABLED=1
make clean all

For Calibration-Net:

export CGO_ENABLED=1
make clean calibnet

(Check the Makefile for eventual support for additional networks).

4. Install Lily (optional)

cp ./lily /usr/local/bin/lily

M1-based Macs #

Because of the novel architecture of the M1-based Mac computers, some specific environment variables have been pre-set in the Makefile:

export GOARCH=arm64
export CGO_ENABLED=1
export LIBRARY_PATH=/opt/homebrew/lib
export FFI_BUILD_FROM_SOURCE=1

Initialize #

Typical initialization and startup for Lily starts with initialization which establishes the datastore, params, and boilerplate config. This is equivalent to how a Lotus node works. For example, you can run:

lily init --repo=$HOME/.lily --config=$HOME/.lily/config.toml --import-snapshot minimal.car

The --repo and --config flag are optionals for custom repository/config locations. They will need to be passed to daemon command too, when used. The repository folder contains chain/block data, keys, configuration, and other operational data. This folder is portable and can be relocated as needed. Note that it can grow significantly as it contains the Lotus state and the chain.

When using Lily against Filecoin Mainnet, we highly recommend initializing Lily from a chain snapshot, which should be downloaded in advance (same as in Lotus).

Configure #

The configuration file, canonically the config.toml, is the same configuration file as in Lotus. It also contains additional Storage and Queue sections that are specific to Lily.

If you make changes to config.toml, you need to restart your Lily daemon.

Notifier & Worker Queue Definitions #

Lily may be configured to use Redis as a distributed task queue to distribute work across multiple lily instances. When configured this way the system of lily nodes can consist of multiple Workers and a single Notifier :

• The Notifier puts tasks into a queue for execution by a Worker.
• The Workers remove tasks from the queue and execute them.
• Tasks are processed concurrently by multiple workers.

The Notifier and Workers should be enumerated with a unique [Name] which will be used as an argument (via --queue) when starting a [watch|walk|fill] notify or tipset-worker job.

An example of the Queue section:

[Queue]
  [Queue.Notifiers]
    [Queue.Notifiers.Notifier1]
      Network = "tcp"
      Addr = "localhost:6379"
      Username = "default"
      PasswordEnv = "LILY_REDIS_PASSWORD"
      DB = 0
      PoolSize = 0
  [Queue.Workers]
    [Queue.Workers.Worker1]
      [Queue.Workers.Worker1.RedisConfig]
        Network = "tcp"
        Addr = "localhost:6379"
        Username = "default"
        PasswordEnv = "LILY_REDIS_PASSWORD"
        DB = 0
        PoolSize = 0
      [Queue.Workers.Worker1.WorkerConfig]
        Concurrency = 1
        LoggerLevel = "debug"
        WatchQueuePriority = 5
        FillQueuePriority = 3
        IndexQueuePriority = 1
        WalkQueuePriority = 1
        StrictPriority = false
        ShutdownTimeout = 30000000000

This should be modified to meet your needs.

Storage definitions #

Lily can deliver scraped data to multiple PostgreSQL and File destinations on a per-Task basis. Each destination should be enumerated with a unique [Name] which will be used as an argument (via --storage) when starting a Task.

An example of the Storage section:

[Storage]
  [Storage.Postgresql]
    [Storage.Postgresql.Name1]
      URL = "postgres://postgres:password@localhost:5432/primarydatabase"
      ApplicationName = "lily"
      SchemaName = "public"
      PoolSize = 20
      AllowUpsert = false
    [Storage.Postgresql.Name2]
      URL = "postgres://postgres:password@localhost:5432/anotherdatabase"
      ApplicationName = "lily"
      SchemaName = "public"
      PoolSize = 10
      AllowUpsert = false
  [Storage.File]
    [Storage.File.CSV]
      Format = "CSV"
      Path = "/tmp"
      OmitHeader = false
      FilePattern = "{table}.csv"
    [Storage.File.CSV2]
      Format = "CSV"
      Path = "/output"
      OmitHeader = false
      FilePattern = "{table}.csv"

This should be modified to meet your needs.

Database schemas #

Before starting, you need to ensure that the Postgres backend is correctly initialized with the necessary schema at the correct version.

For this you will need to run the lily migrate command with the right options (should match your Storage configuration). For example:

lily migrate --db="postgres://postgres:password@localhost:5432/postgres?sslmode=disable" --latest --schema lily-analysis --name lily

You can additionally verify the version:

lily migrate --db="postgres://postgres:password@localhost:5432/postgres?sslmode=disable"

INFO    lily/commands   commands/setup.go:126   Lily version:demo
INFO    lily/commands   commands/migrate.go:114 current database schema is version 1.3, latest is 1.3
INFO    lily/commands   commands/migrate.go:120 database schema is supported by this version of lily

Start and Sync #

With all the above, the Lily daemon should be ready to launch and start following the chain:

lily daemon

You should wait until Lily is fully synced. As in Lotus, you can track the current status with:

lily sync status

You can interactively wait for the sync to complete with:

lily sync wait

Once Lily is running and fully synced, you can start launching jobs.