Welcome to the Filecoin box. The goal of this box is to both get you hands-on with all the official Filecoin support available within Truffle and Ganache, and to kick-start your journey into the Filecoin ecosystem and the benefits that robust decentralized storage can bring to your DApps.

The context of the box is that of a decentralized art gallery. It comprises both Lotus and IPFS nodes (simulating the process of creating a storage deal), an Ethereum node (for the deployment of the ERC-721 based NFT contracts) and a front-end for viewing the gallery and the assets decentrally stored within.

The Filecoin box has the following requirements:

• Node.js 12.x or later
• NPM version 5.2 or later
• Windows, Linux or MacOS

$ truffle unbox filecoin
$ npm install

Once installed, you can run Filecoin Ganache with the following command:

$ npx ganache filecoin

This creates 10 accounts, each loaded with 100 FIL, and displays both their account addresses and associated private keys.

Available Accounts
==================
(0) t3rvcqmc5otc3sh3cngqg2ttzcu7ezpco466lbafzaoygxvnzsw7e7n2zbjwhiv5fdzhs6uxm2qckwt6lp5wga (100 FIL)
(1) t3s3la37547tijmoeiep7ktogws3tep2eqrralh7rhi2mpe46q574gceyy467356onblzvwf7ejlelo2rdsg4q (100 FIL)
(2) t3wk7a46e2dcqb7qxeuz2zq7wodwycdgtbgdpr37hhvelfilf5yvssg5xbsolgusqsumomtmtqhnobh4carhyq (100 FIL)
...

It also starts the Lotus and IPFS daemons running over http and ws respectively:

Lotus RPC listening on 127.0.0.1:7777
IPFS  RPC listening on 127.0.0.1:5001

An alternative to running Filecoin Ganache via the CLI is to use Filecoin Ganche UI. As per the screenshot below, this exposes all the core Filecoin protocol elements as tabs which is particularly useful if you're just starting out.

Filecoin Ganche UI can be installed and run via the following...

$ git clone https://github.com/trufflesuite/ganache
$ git checkout feat/filecoin-files
$ npm install
$ npm run start

Note that these steps will be changing (merging branch into master / main, webpack, truffle plugin, etc).

$ git clone https://github.com/trufflesuite/filecoin-network-inspector
$ npm install
$ git checkout ganache-changes
$ npm run start

Assuming it's running correctly, you can open the Filecoin Network Explorer at the following: http://localhost:3000

$ npx ganache ethereum

RPC Listening on 127.0.0.1:8545

A storage deal is an agreement between a client and a storage miner to store some data in the network for a given duration. Note that while in the case of Filecoin's mainnet, a deal must be secured with a miner before data is stored, in Filecoin Ganache a deal is reached automatically.

The simplest way to store data, open the Filecoin Network Explorer and navigate to the "Market" tab. From here you can select a file by clicking "Choose File" followed by "Upload to the Filecoin Network".

Truffle now has a preserve command which allows for the 'preservation' of files directly from the Truffle CLI. This is currently experimental and thus on specific branch; installation details available at here.

Once installed, you'll be able to preserve your assets via the following command. Note that you'll need to include the environments object in your truffle-config.js to point at the respective node (although these are already preconfigured in the box).

$ truffle preserve --environment development ./assets/ --filecoin

For broader help with this command run truffle help preserve.

Lastly, you can send the following curl request directly to the Lotus RPC. Note that the you'll need to update both the wallet address (t3s3la3754...) and CID (QmZTR5bcpQ...).

curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{"jsonrpc":"2.0","id":0,"method":"Filecoin.ClientStartDeal","params":[{"Data":{"TransferType":"graphsync","Root":{"/":"QmZTR5bcpQD7cFgTorqxZDYaew1Wqgfbd2ud9QqGPAkK2V"},"PieceCid":null,"PieceSize":0},"Wallet":"t3s3la37547tijmoeiep7ktogws3tep2eqrralh7rhi2mpe46q574gceyy467356onblzvwf7ejlelo2rdsg4q","Miner":"t01000","EpochPrice":"2500","MinBlocksDuration":300}]}' \
     http://localhost:7777/rpc/v0

In the example below, we've already created a deal for the 3 assets (metadata, thumbnail, and the original asset respectively) that comprise our NFT. These are as follows, with their corresponding CIDs.

• metadata (QmS4t7rFPxaaNriXvCmALr5GYRAtya5urrDaZgkfHutdCG)
• thumbnail - (QmbAAMaGWpiSgmMWYTRtGsru382j6qTVQ4FDKX2cRTRso6)
• asset - (QmUWFZQrJHfCVNHXVjjb2zeowVvH7dC6rKpbdHsTdnAgvP)

Assuming the local Ethereum Ganache node is running, you'll be able to open a console and mint a new NFT with the following steps. As the base URL is set to that of an IPFS gateway, we'll just need to pass in the CID to the asset metadata.

$ truffle console
truffle(development)> const gallery = await MyGallery.deployed()
truffle(development)> gallery.mint(accounts[0], "QmS4t7rFPxaaNriXvCmALr5GYRAtya5urrDaZgkfHutdCG")

In the above example the owner of the NFT is set (via accounts[0]) to that of the first account generated by the mnemonic. If we want to transfer it to a new owner, we'll be able to do so with the following.

$ truffle console
truffle(development)> gallery.transferFrom(accounts[0], accounts[1], 1)

A sample gallery interface is available here.

You can use the following steps to run this locally...

$ cd ui
$ npm install
$ npm run start

Support for this box is available via the Truffle community available here. In addition, Filecoin support is available here.