Powergate
Powergate exposes higher-level APIs for developers that facilitate interaction with IPFS and Filecoin nodes. It also handles wallet management, long-term deal management, and provides many features that improve the overall experience of being a storage client on Filecoin. You can read more about Powergate in the Textile docs.
Powergate is the recommended solution for developers who want an easier interface and better performance from Filecoin, but who prefer to manage their nodes, and also gain access to rich and flexible storage configurations. For examples:
- Replication factor
- Miner selection
- Deal renewal and Repair
How to use Powergate
There are many ways to interact with the Powergate. These pathways are well-documented on Textile’s Powergate docs. The high-level pathways are summarized here for a quick reference:
- Powergate CLI: You can install, run, and interact directly with the Powergate CLI.
- Powergate JS API client: If you would like to use Powergate in your JS application, you can use the Powergate JS Client.
- Powergate Go API client: If you would like to use Powergate in your Go application, you can use the Powergate Go Client.
Sometimes the best way to learn is through examples.
- See a full production application (Slate) built on the Powergate JS Client.
Getting started with POW CLI
This guide will help you get started with Powergate CLI. We will be using the Powergate CLI to interact with the Powergate API endpoint.
Developers can also start with the localnet as you’ll have access to all the APIs and capabilities without having to sync to the network right away. When you’re ready, you can update your Powergate to connect to the live mainnet.
We will use the Filecoin mainnet as an example here. Learning how to use localnet, see Powergate localnet instruction.
Download and install
pow
CLI:The
pow
CLI tool will help us interact with the Powergate instance. It can be built and installed with:git clone https://github.com/textileio/powergate cd powergate make install-pow
Sync the blocks for Filecoin mainnet:
Before you can start storing and retrieving data from Filecoin, you need to fully sync from Filecoin mainnet which may take over a day.
To speed up the syncing process, you can also choose to sync from the current snapshot provided by Protocol Labs every hour. For all the details, please check Bootstrap a clean Lotus node from a snapshot.
Create a new User instance:
A User instance manages all the necessary state and capabilities to provide multitiered file storage through the Powergate. Each Powergate setup can manage an arbitrary number of User instances. To create a new User:
pow admin user create
This will print an instance ID and a User auth token. Write down the auth token; we will need it for every other user-operation. As an optional convienience (vs. including the User
--token
flag on everypow
command), you can let Powergate know about it with thePOW_TOEKN
environment variable:export POW_TOKEN=<token>
Additional details about User instances can be found in the official documentation.
Stage your data:
Powergate requires stored data to be available over IPFS, you can ensure it’s available by staging it on IPFS using
stage
. If data exists on the IPFS network, you don’t need to runstage
as the Powergate will automatically fetch that data from remote peers.pow data stage [path|url]
Note the CID in the output. This will be used to initiate the Powergate storage.
Initiate data storage:
The following command pushes a new storage configuration for a CID, creates a storage job for it, and watches the progress of the resulting job:
pow config apply [cid] --watch
The configuration used will be based on the default configuration unless a custom configuration is provided (see
pow config apply --help
). Powergate will automatically find storage providers and perform the storage deal.You can watch the job progress anytime with:
pow storage-jobs watch [jobid]
For additional details and up-to-date information on how to use
pow
and perform other operations like retrieval, see the official Textile docs.Retrieve your file
To retrieve the file that you stored through POW CLI, you can run the following command to download it from IPFS:
pow data get <cid> fileName
Interact with the Powergate API:
Once you are familiar with the Powergate workflows, you can start programatically controlling the Powergate instance. Textile provides Go and Javascript API clients for Powergate using the gRPC API endpoint:
Additional Powergate resources
For a more detailed description of how Powergate works, we recommend reading the following docs:
- Filecoin Developer Tools
- Powergate introduction: docs and video
- Using Powergate with LocalNet
- Learn all POW command lines
- FFS Design Overview