powergate

README

Powergate

Textile's Filecoin swiss army knife for developers

Join us on our public Slack channel for news, discussions, and status updates. Check out our blog for the latest posts and announcements.

Table of Contents

• Usage
• Contributing
• Changelog
• License

Usage

Warning This project is still pre-release and is only meant for testing.

Lotus (lotus)

Powergate communicates with a Lotus node to interact with the filecoin network. If you want to run Powergate targeting the current testnet, you should be running a fully-synced Lotus node in the same host as Powergate. For steps to install Lotus, refer to https://lotu.sh/ taking special attention to its dependencies.

Since bootstrapping a Lotus node from scratch and getting it synced may take too long, Powergate allows an --embedded flag, which auto-creates a fake local testnet with a single miner, and auto-connects to it. This means, only running the Powergate server with the flag enabled, allows to use it in some reasonable context with almost no extra setup.

For both building the CLI and the Server, run:

make build

This will create powd (server) and pow (CLI) of Powergate.

Client (pow)

To build the CLI, run:

make build-cli

Try pow --help.

Server

To build the Server, run:

make build-server

The server connects to Lotus and enables multiple modules, such as:

• Reputations module:
  • Miners index: with on-chain and metadata information.
  • Ask index: with an up-to-date information about available Storage Ask in the network.
  • Slashing index: contains a history of all miner-slashes.
• Deals Module:
  • Contain helper features for making and watching deals.
• FFS:
  • A powerful level of abstraction to pin Cids in Hot and Cold storages, more details soon!

Run in Embedded mode

The server can run in Embedded mode which auto-creates a fake devnet with a single miner and connects to it. The simplest way to run it is:

cd docker
make embed

This creates an ephemeral server with all working for CLI interaction.

Here is a full example of using the embedded network:

Terminal 1:

cd docker
make embed

Wait for seeing logs about the height of the chain increase in a regular cadence.

Terminal 2:

make build
❯ head -c 700 </dev/urandom > myfile
❯ ./pow ffs create
> Instance created with id 0ac0fb4d-581c-4276-bd90-a9aa30dd4cb4 and token 883f57b1-4e66-47f8-b291-7cf8b10f6370
❯ ./pow ffs addToHot -t 883f57b1-4e66-47f8-b291-7cf8b10f6370 myfile
> Success! Added file to FFS hot storage with cid: QmYaAK8SSsKJsJdtahCbUe7MZzQdkPBybFCcQJJ3dKZpfm
❯ ./pow ffs push -w -t 883f57b1-4e66-47f8-b291-7cf8b10f6370 QmYaAK8SSsKJsJdtahCbUe7MZzQdkPBybFCcQJJ3dKZpfm
> Success! Pushed cid config for QmYaAK8SSsKJsJdtahCbUe7MZzQdkPBybFCcQJJ3dKZpfm to FFS with job id: 966dcb44-9ef4-4d2a-9c90-a8103c77c354
               JOB ID                   STATUS
966dcb44-9ef4-4d2a-9c90-a8103c77c354    Success
❯ ./pow ffs get  -t 883f57b1-4e66-47f8-b291-7cf8b10f6370 QmYaAK8SSsKJsJdtahCbUe7MZzQdkPBybFCcQJJ3dKZpfm myfile2
> Success! Data written to myfile2

Notes:

• A random myfile is a small random file since the devnet is running with a constrained sectorbuilder mock and sector size. Sizes close to ~700 bytes should be fine.
• The devnet might run correctly for 150 epochs before it can become unstable.

Run in full mode

Running the full mode can be done by:

cd docker
make up

This will spinup and auto-wire:

• Prometheus ,endpoint for metrics
• Grafana, for metrics dashboard
• cAdvisor, for container metrics
• Lotus node configured for testnet.
• Powergate, wired with all of above components.

Recall that you should wait for Lotus to be fully-synced which might take a long time now. If you're running the Lotus node in the host and want to leverage its fully synced, you could:

• Bind the .lotus folder to the Lotus node in the docker-compose file.
• Or, just docker cp it. In any option, you should stop the original Lotus node.

If you don't have a fully-synced Lotus node and don't want to wait, consider using our archives.

Test

For running tests: make test

Benchmark

There's a dedicated binary to run benchmarks against a Powergate server. For more information see the specific README.

Docker

A powd Docker image is available at textile/powergate on DockerHub.

Contributing

This project is a work in progress. As such, there's a few things you can do right now to help out:

• Ask questions! We'll try to help. Be sure to drop a note (on the above issue) if there is anything you'd like to work on and we'll update the issue to let others know. Also get in touch on Slack.
• Open issues, file issues, submit pull requests!
• Perform code reviews. More eyes will help a) speed the project along b) ensure quality and c) reduce possible future bugs.
• Take a look at the code. Contributions here that would be most helpful are top-level comments about how it should look based on your understanding. Again, the more eyes the better.
• Add tests. There can never be enough tests.

Before you get started, be sure to read our contributors guide and our contributor covenant code of conduct.

Changelog

Changelog is published to Releases.

License

MIT