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.
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.
An object with the following fields:
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.
The rate in attoGo per byte-hour as a JSON number.
Example:
2837942Get the current maximum file size.
The maximum file size allowed in bytes as a JSON number.
Example:
1000000000Get the status for a file by IPFS CID hash.
HTTP 404, if never added to GoFS. Otherwise, an object with the following fields:
Example:
{
"expiration": 1567619841,
"size": 6737
}curl https://api.gofs.io/v0/status/bafybeida2gv6hnykvwadda6zjcxuo5yrxzb6z7j7fhi2mz7o55carn6jlaAdd 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:
Example:
{
"cid": "bafkreic62jyg5yvckkumrnsqo43wfltlao4khbbf4mtj3if7hrbxbmikya",
"expiration": 1567619841,
"size": 6737
}curl -X PUT -T myfile.png https://api.gofs.io/v0/addConvert an IPFS CID hash to various standard forms: binary, default base, and event topic hash.
An object with the following fields:
Pinned with this)Pinned event topics with this)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.
CumulativeSize will be used)1000000, 1KB, 1.01MB) An object with the following fields:
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/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);
...
}