diff --git a/README.md b/README.md index a617d88..f73442c 100644 --- a/README.md +++ b/README.md @@ -2,19 +2,20 @@ 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. +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. ## How to Use -There are two primary ways of interacting with GOFS and paying to pin a file. +There are two primary functions that you'll use when interacting with GOFS: adding a file and paying for storage. -#### 1. Add: Upload a file +### 1. Add: Upload a file Add a new file to IPFS by uploading it to GOFS. This can be done through the [web interface](https://gofs.io) or the [JSON API](#Add). New files are -initially pinned for a grace period of one hour, during which the expiration +initially pinned for a grace period of one hour. -#### 2. Pin: Pay to pin a file +### 2. Pin: Pay to extend the life of a file 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](https://gofs.io/) @@ -34,18 +35,18 @@ GOFS contract. This removes barriers for users created by complex smart contract while still utilizing the same underlying mechanisms, so the same kind of `Pinned` events are emitted when payments come through a wallet. -### Limitations +## Limitations - 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. -### Web +## Web Interface The [web interface](https://gofs.io) is the most user friendly way to use GOFS, and supports MetaMask integration. -### CLI +## CLI The `gofs` [command line interface](./cmd/gofs) provides access to both the contract and the web api. @@ -55,36 +56,6 @@ File size: 6B Expires in 58m1s at 2019-09-04 15:37:42 -0500 CDT. ``` -## Contract ABI - -The GOFS contract is at 0xTODO, and implements the `contracts/IGOFS.abi` interface: - -```solidity -// 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 must be greater than 0. CID must not be version 0. - // Emits Pinned events. - function pin(bytes calldata cid) external payable; - - // Get the address of the deposit wallet for a cid. Returns 0x0 if none exists. - function wallet(bytes calldata cid) external view returns (address); - - // Create a deposit 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 a cid is pinned. - 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); - ... -} -``` - ## JSON API The JSON API used by the web interface is available at: `https://api.gofs.io/v0/` @@ -146,3 +117,34 @@ Response: "version": 1 } ``` + + +## Contract ABI + +If you want to interact with the contract directly, you can do that too. The GOFS contract is at 0xTODO, and implements the [contracts/IGOFS.abi](contracts/IGOFS.abi) interface: + +```solidity +// 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 must be greater than 0. CID must not be version 0. + // Emits Pinned events. + function pin(bytes calldata cid) external payable; + + // Get the address of the deposit wallet for a cid. Returns 0x0 if none exists. + function wallet(bytes calldata cid) external view returns (address); + + // Create a deposit 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 a cid is pinned. + 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); + ... +} +```