What Is It?

Tableland developers can now build on Filecoin! We actually added Filecoin FEVM support a couple of months ago, but we wanted to dive into this in a bit more detail since it opens up a ton of new possibilities that weren’t available before. One demonstrated example is the Rigs NFT with Filecoin deals for its assets, which it described in more detail below.

If you’re currently building with or interested in exploring a Filecoin + Tableland integration, apply to the Pilot Program for microgrant funding, support, and access to our team’s network.

Why Did We Do It?

Tableland is a decentralized database network. Filecoin is a decentralized storage network. The two work quite well together, especially, in the context of what traditional databases can support. Plus, Filecoin adds verifiable, persisted storage, which isn’t a feature with IPFS alone.

For context, Filecoin launched their virtual runtime called the FVM to bring programmability to its network. The FVM also contains an Ethereum Virtual Machine (EVM) runtime, called the FEVM. The FEVM lets you use familiar languages like Solidity to write smart contracts (also called “actors” on the FVM), which makes building on top of Filecoin easier for existing web3 developers.

Tableland focuses on EVM-compatible chains, so when the FEVM launched, we were very excited to support it as soon as possible! But unlike the other blockchains (Ethereum, L2s), Filecoin offers novel features like storing large files and using actors/smart contracts to orchestrate storage deals for persistence. There are tons of use cases for using Tableland as well as Filecoin that, quite simply, aren’t possible on other blockchains, so it was an easy decision to bring Tableland to the Filecoin ecosystem!

Fun fact: Textile, the team ushering forward Tableland, spent a number of years building Filecoin tooling and other infrastructure for the Protocol Labs ecosystem, prior to launching Tableland.

What Does it Do & How Does It Work?

You can think of Tableland as an additional database layer on top of Filecoin. This enables web3-native mutability and queries to data written by FEVM smart contracts, such as deal data or file metadata. Recall that Tableland works in two parts:

• Onchain: a registry smart contract that mints SQL tables, allows you to write SQL statements against them, and use additional access control checks for shared table mutations.

• Offchain: a network of validator nodes that materialize onchain SQL events and materialize them in a per-validator SQLite database, allowing for read queries to be made at a gateway.

By supporting the FEVM, developers can build applications on Filecoin. Existing Tableland tooling—like smart contracts, SDK, and CLI—fully support Filecoin without requiring any changes for builders…aside from pointing to a new chain! There are some architectural and naming convention differences (transactions, address format, etc.), but these shouldn’t impact the developer experience (e.g., you can still use an EVM account/wallet).

How Can Someone Use It?

Tableland Tooling

You can set the chain name to filecoin (mainnet) or filecoin-calibration (testnet) and leverage Tableland tooling as you would on any other chain. For example, the SDK or CLI:

// SDK
const db = new Database({
  signer,
  chain: "filecoin", // or `filecoin-calibration`
});

// CLI
tableland read "SELECT ..." --chain filecoin --providerUrl ...

If you’re using the Hardhat framework to deploy smart contracts, the hardhat.config.js file should include Filecoin networks. There are a number of RPC providers you can choose from, but we recommend Ankr or Glif. When you run a script, pass the --network flag with one of the following:

const config: HardhatUserConfig = {
  // ...
  networks: {
    filecoin: {
      url: `https://rpc.ankr.com/filecoin/your_api_key`,
      accounts: YOUR_PRIVATE_KEY,
    },
    "filecoin-calibration": {
      url: `https://api.calibration.node.glif.io/rpc/v1/`,
      accounts: YOUR_PRIVATE_KEY,
    },
  },
  // ...
};

One callout—Filecoin block times average ~30 seconds, so keep that in mind since it’s a little different than other EVM chains’ shorter inclusion periods. For the SQL to materialize in the Tableland network, there’s also a bit of latency due to how Filecoin operates; you can expect up to a 4 minute wait until the data is reflected and queryable.

Lastly, let’s review what a Tableland validator node operator can do to add Filecoin support. In your source code, navigate to docker/deployed/mainnet/api/config.json and/or docker/deployed/testnet/api/config.json; this is where the configuration files are located. Under the "Chains" array, you can add an entry for these networks. For demonstration purposes, Filecoin mainnet and testnet settings are shown below, but keep in mind these would be in the proper mainnet or testnet config file, not in the same one. Also note Glif doesn’t require authentication, so you won’t need to set up an API key in your .env_... files but should still keep the variable in there.

{
    // other config info
    "Chains": [
        // in the mainnet config file
        {
            "Name": "Filecoin Mainnet",
            "ChainID": 314,
            "Registry": {
                "EthEndpoint": "https://node.glif.io/fvm-archive/lotus/rpc/v1",
                "ContractAddress": "0x59EF8Bf2d6c102B4c42AEf9189e1a9F0ABfD652d",
                "ProviderAuthToken": "${VALIDATOR_GLIF_FILECOIN_MAINNET_API_KEY}"
            },
            "EventFeed": {
                "ChainAPIBackoff": "15s",
                "NewBlockPollFreq": "15s",
                "MinBlockDepth": 5,
                "PersistEvents": true
            },
            "EventProcessor": {
                "BlockFailedExecutionBackoff": "10s",
                "DedupExecutedTxns": true,
            },
            "HashCalculationStep": 60
        },
        // in the testnet config file
        {
            "Name": "Filecoin Calibration",
            "ChainID": 314159,
            "Registry": {
                "EthEndpoint": "https://api.calibration.node.glif.io/rpc/v1",
                "ContractAddress": "0x030BCf3D50cad04c2e57391B12740982A9308621"
            },
            "EventFeed": {
                "ChainAPIBackoff": "15s",
                "NewBlockPollFreq": "15s",
                "MinBlockDepth": 5,
                "PersistEvents": true
            },
            "EventProcessor": {
                "BlockFailedExecutionBackoff": "10s",
                "DedupExecutedTxns": true
            },
            "HashCalculationStep": 60
        }
    ]
}

Use Cases

A programmable Filecoin opens up quite a broad spectrum of opportunities. One example is automated storage deals: store large media (images, files, etc.) and guarantee it’s persisted with the smart contract managing the negotiation process. You can even build reputation-based services that help track storage provider efficacy.

Data DAOs are another great example. Tableland is designed for storing “small” data in cells, up to 1kb. So, you can use Filecoin to store large datasets and choose where/how that data gets placed, incentivized, and governed. Although the FVM doesn’t directly interact with the data stored, you can add metadata or other access control rules around the orchestration, or even tokenize datasets. Tableland can help with storing dataset metadata, deal data, or other relevant DAO information.

There are plenty of other use cases, but those should help contextualize what you can do!

Example: Rigs, IPFS Retrieval, & Filecoin Storage

The Tableland Rigs NFT is a collection that uses the core Tableland protocol to store its metadata; all of this code is open source. In fact, there are 10 tables across Ethereum, Arbitrum, and Filecoin that are composed into a single metadata object and fully ERC-721 compliant. Rigs images were originally only stored on IPFS, so we wanted to persist these images by creating Filecoin deals but also use IPFS for faster retrieval. Each NFT’s media files are stored in a single folder, packaged as a CAR (Content Addressable aRchives) file. Then, a final CAR file is pushed to w3link that maps out all Rig folders, giving a single CID/path.

Each Rig has a deal made to store its media on Filecoin, and deal information is written back to Tableland metadata. A viewer will fetch a single media file with a CID/folder/path, and if it is not cached, the request will reach the Filecoin Storage Provider to serve the data.

Our table schema is the following, and upon making a deal, each Rig’s metadata is inserted into the table (see here for what this looks like in production):

CREATE TABLE deals(
  rig_id integer not null,
  deal_id integer not null,
  storage_provider text not null,
  data_model_selector text not null,
  deal_number integer not null,
  primary key(rig_id, deal_id)
)

A Rig’s metadata will now include some additional attributes that describe the deal data. If you navigate to one of the deal IDs, you can further inspect the deal information.

{
  "display_type": "string",
  "trait_type": "Filecoin Deal 1",
  "value": "https://filfox.info/deal/36739326"
},
{
  "display_type": "string",
  "trait_type": "Filecoin Deal 2",
  "value": "https://filfox.info/deal/37000535"
},
{
  "display_type": "string",
  "trait_type": "Filecoin Deal 3",
  "value": "https://filfox.info/deal/38987515"
},
{
  "display_type": "string",
  "trait_type": "Filecoin Deal 4",
	"value": "https://filfox.info/deal/39012246"
},

Now, each Rig has a dedicated and verifiably persisted deal for its media!

Get In Touch!

Be sure to give us a follow on Twitter and hop into our Discord if you’d like to discuss this design or the protocol in more detail. And keep an eye out for upcoming hackathons—both Filecoin and Tableland should be at a couple of them!