GoFS is a pay-to-pin IPFS service built on GoChain. Payments processed on the blockchain fund the storage of files on GoFS to ensure the files are always available on IPFS. There are three ways to interface with GoFS: the web interface, the CLI and the API. You can find information about all 3 below.

There are two primary functions that you'll use when interacting with GoFS: adding a file and paying for storage.

Add a new file to IPFS by uploading it to GoFS. This can be done through the web interface or the JSON API. New files are initially pinned for a grace period of one hour.

Pay to pin a file on IPFS. Payments are made on the blockchain to the GoFS smart contract. This can be done through the web interface with MetaMask, on the command line with the gofs cli, or programmatically against the contract itself. Each payment purchases storage for a particular CID (measured in byte-hours). The amount of storage credited is calculated based on the contract rate (measured in attoGo/byte-hour) and this value is included on the emitted Pinned event. When GoFS processes these events, the storage amount and the file size determine how much to extend the expiration. The Pinned events emitted by the GoFS contract serve as a public, auditable trail of receipts.

File wallets are addresses which can receive standard txs to extend the life of a particular file. They are mini-contracts which only contain a fallback function to forward payment to the GoFS contract. This removes barriers for users created by complex smart contract interaction, while still utilizing the same underlying mechanisms, so the same kind of Pinned events are emitted when payments come through a wallet.

• Size Limit: 1GB - Larger files will be rejected.
• Minimum Pin Duration: 1 month - Unpinned files will not be fetched, unless 1 month has been funded.
• Recursive Directories: Not yet supported - Coming soon.
• CID: v0 not allowed, v1 required, base32 encoding preferred - Contract will reject v0.

The web interface is the most user friendly way to use GoFS, and supports MetaMask integration.

The gofs command line interface provides access to both the contract and the web api.

> gofs status bafkreicysg23kiwv34eg2d7qweipxwosdo2py4ldv42nbauguluen5v6am
File size: 6B
Expires in 58m1s at 2019-09-04 15:37:42 -0500 CDT.

The JSON API used by the web interface is available at: https://api.gofs.io/v0/

Get general information about GoFS.

GET /info

An object with the following fields:

• rate: current storage rate in attoGo per byte-hour
• contract_address: address of the GoFS contract
• explorer_url: block explorer URL for the GoChain network
• rpc_url: RPC URL for the GoChain network
• max_file_size: maximum supported file size, in bytes

Example:

{
  "rate": 2837942,
  "contract_address": "0xded28050fdbf604e12056e516c05e154cb5dd1bc",
  "explorer_url": "https:\/\/explorer.gochain.io\/",
  "rpc_url": "https:\/\/rpc.gochain.io",
  "max_file_size": 1000000000
}

Get the current rate.

GET /info/rate

The rate in attoGo per byte-hour as a JSON number.

Example:

2837942

Get the current maximum file size.

GET /info/max_file_size

The maximum file size allowed in bytes as a JSON number.

Example:

1000000000

Get the status for a file by IPFS CID hash.

GET /status/{cid}

HTTP 404, if never added to GoFS. Otherwise, an object with the following fields:

• expiration: unix timestamp of file expiration
• size: file size, in bytes

Example:

{
  "expiration": 1567619841,
  "size": 6737
}

curl https://api.gofs.io/v0/status/bafybeida2gv6hnykvwadda6zjcxuo5yrxzb6z7j7fhi2mz7o55carn6jla

Add a file to IPFS by uploading to GoFS. Maximum file size is limited (see max_file_size from /info). Files are initially pinned for a grace period of one hour. This can be extended by calling pin() on the GoFS smart contract. See How to Use for other methods.

PUT /add

Body: File data, or a multi-part form file.

An object with the following fields:

• cid: IPFS CID hash for file
• expiration: unix timestamp of file expiration
• size: file size, in bytes

Example:

{
  "cid": "bafkreic62jyg5yvckkumrnsqo43wfltlao4khbbf4mtj3if7hrbxbmikya",
  "expiration": 1567619841,
  "size": 6737
}

curl -X PUT -T myfile.png https://api.gofs.io/v0/add

Convert an IPFS CID hash to various standard forms: binary, default base, and event topic hash.

GET /convert-cid/{cid}

An object with the following fields:

• binary: hex encoded binary CID hash (call Pinned with this)
• base: default encoded (base32) CID hash
• hash: hex encoded keccak256 of the binary CID (filter Pinned event topics with this)
• version: CID version

Example:

{
  "binary": "0x6F7cbcf57762842a4C66F8e7d6135b2e7bcF7b52",
  "base": "bafkreic62jyg5yvckkumrnsqo43wfltlao4khbbf4mtj3if7hrbxbmikya",
  "hash": "0x60632b18db19d0f6d10a0f7dcf0eea38e8114eb867f34252c1f2c6ff148dc557",
  "version": 1
}

Calculate the cost of storage for a file (or an arbitrary size) over a duration at the current rate.

GET /cost[/{cid}]?[days=][years=][size=]

Either the cid path param or the size query param must be set. Also, one or both of days and years must be set.

• cid: string - encoded IPFS CID for desired file (its CumulativeSize will be used)
• size: integer/string - raw bytes, or formatted string (e.g. 1000000, 1KB, 1.01MB)
• days: integer
• years: integer

An object with the following fields:

• size: file size, in bytes
• duration: duration of storage, in hours
• rate: current rate, in attoGo per byte-hour
• cost: cost of storage, in attoGo

Example:

{
  "size": 1000000000,
  "duration": 720,
  "rate": 2837942,
  "cost": 2043318240000000000
}

curl "localhost:80/v0/cost?size=1GB&days=30"

/cost?size=115MB&years=1&days=100

/cost?size=1MB&years=10

/cost/QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco?days=30

If you want to interact with the contract directly, you can do that too. The GOFS contract is at 0x6F7cbcf57762842a4C66F8e7d6135b2e7bcF7b52, and implements the contracts/IGOFS.abi interface:

// The IGOFS interface defines the public functions for GOFS.
interface IGOFS {
    // Returns the current rate in attoGO per byte-hour.
    function rate() external view returns (uint);

    // Pin a CID. Value (the GO value for your transaction) must be greater than 0. The GO value you pass in
    // here is used to purchase storage for the file at the current rate. The amount of storage purchased
    // determines how long the file will be pinned for. CID must not be version 0.
    // Emits Pinned events.
    function pin(bytes calldata cid) external payable;

    // Get the address of the wallet for a cid. Returns 0x0 if none exists.
    function wallet(bytes calldata cid) external view returns (address);

    // Create a wallet for a cid. Returns false if one already exists. CID must not be version 0.
    // Emits CreatedWallet events.
    // Uses <=300000 gas.
    function newWallet(bytes calldata cid) external;

    // Emitted when storage is purchased for a file. bh is amount of storage purchased in byte-hours.
    event Pinned(address indexed user, bytes indexed cid, uint bh);
    // Emitted when a new wallet is created.
    event CreatedWallet(address indexed user, bytes indexed cid, address wallet);
    ...
}