Eth & Polygon Storage

The @textile/eth-storage library provides zero-config Typescript/Javascript SDKs that make it easy to store data on the Filecoin network from any EVM-compatible dApp. @textile/eth-storage should feel comfortable to developers already familiar with Ethers Javascript libraries. This chain-specific SDK provides a small but powerful API surfaces that integrates nicely with existing ETH/Polygon development best practices. Simply import the library, deposit some funds, and you are ready to start submitting data to be stored on the Filecoin network.

For a great overview of the Filecoin Bridge system, check out this introductory video.

Install

npm i @textile/eth-storage

Usage

import { providers } from "ethers";
import { init } from "@textile/eth-storage";

await window.ethereum.enable();
const provider = new providers.Web3Provider(window.ethereum);
const wallet = provider.getSigner();

const storage = await init(wallet);

const blob = new Blob(["Hello, world!"], { type: "text/plain" });
const file = new File([blob], "welcome.txt", {
  type: "text/plain",
  lastModified: new Date().getTime()
});

await storage.addDeposit();

const { id, cid } = await storage.store(file);

const { request, deals } = await storage.status(id);
console.log(request.status_code);
console.log([...deals]);

API

Full library documentation (TypeDocs), available on GitHub Pages!

The main @textile/eth-storage entry point exposes an initialization function that takes an ETH Signer object, and returns a Storage object with a minimal CoreAPI interface. The initialization function can optionally take information about a known Filecoin storage provider, otherwise, a provider is automatically selected:

import { providers } from "ethers";
import { init } from "@textile/eth-storage";

// See https://github.com/textileio/storage-js-dapp-demo for a basic demo
await window.ethereum.enable();
const provider = new providers.Web3Provider(window.ethereum);
const wallet = provider.getSigner();

const storage = await init(wallet);

Create session

The core storage API revolves around two key concepts: deposits and storage. Leaving a deposit provides a degree of Sybil resistance, such that users looking to store data on Filecoin via the provider must first deposit funds proportional to the length of time they'd like to continue storing data (the default timeout is ~1 hour). To store data, a minimum (default) deposit must be left with a provider:

const deposit = await storage.addDeposit();
console.log(deposit);

A deposit is generally valid for ~1 hour on ETH/Polygon (to avoid frequent signing). The session duration is a function of the amount of funds deposited. Currently on ETH, this is 100 GWEI per second, or about 0.00036 ETH per hour. After funds expire, they can be released by the user or any other party interacting with the SDK's smart contract (such as the provider itself). This provides a means to release funds after a storage session has completed, without locking funds in the contract during the Filecoin proof process.

Store data

Once a valid deposit is available, the app/user can push data to the provider using the store endpoint. This simply takes a File (or FormData) object, and send the bytes to the provider for preparation and Filecoin storage. In NodeJS, callers can also provide a Readable stream object that contains the FormData bytes (see tests for examples).

const blob = new Blob(["Hello, world!"], { type: "text/plain" });
const file = new File([blob], "welcome.txt", {
  type: "text/plain",
  lastModified: new Date().getTime()
});

// The store API also takes optional configuration parameters
const { id, cid } = await storage.store(file);

The response from the store method includes the storage request id, and the data content id (or cid).The app should keep track of at least one of these values for later retrieval. For example, the app might be configured to store a mapping of address to cid, to allow users to retrieve their data at a later date. Additionally, the cid can be used to fetch the data over IPFS via any public IPFS gateway, or IPFS node, including browser-based nodes. This makes it really easy to reference the data in NFT assets or any other on-chain reference to off-chain data!

Check status

The status of the file can be queried using its id. The storage process ranges from "batching" files together, to "preparing" the storage deal, to "auctioning" the set of storage deals, to the actual "deal making" and "success" of the final storage deal on Filecoin. Along the way, clients may query the status in order to provide feedback to users.

const { request, deals } = await storage.status(id);
console.log(request.status_code);
console.log(deals); // Array, empty if no deals on chain yet

It is now safe to release the deposit:

await storage.releaseDeposit();

Other APIs

The @textile/eth-storage SDK provides a few other endpoints for developers to use, including a JSON Web Signature (JWS) signing utility that let's you create a (modified) JWS token.

Here's an example using the createToken API from a browser script (assumes you have Metamask installed):

import { providers } from "ethers";
import { createToken } from "@textile/eth-storage";

await window.ethereum.enable();
const provider = new providers.Web3Provider(window.ethereum);
const signer = provider.getSigner();
const aud = "0xaddress"; // Intended audience

const token = await createToken(signer, { aud });

Read the full API documentation here.

Examples

Metrics

Review all storage requests and Filecoin deals here: https://textileio.retool.com/embedded/public/146224ec-962b-42eb-b567-c89c546845ee