update readme

filswan · Jan 24, 2023 · b5989af · b5989af
1 parent f983e97
commit b5989af
Show file tree

Hide file tree

Showing 2 changed files with 186 additions and 196 deletions.
diff --git a/README.md b/README.md
@@ -1,58 +1,30 @@
-# js-mcs-sdk
+# Multichain Storage SDK - Javascript
 
 [![Made by FilSwan](https://img.shields.io/badge/made%20by-FilSwan-green.svg)](https://www.filswan.com/)
 [![Chat on discord](https://img.shields.io/badge/join%20-discord-brightgreen.svg)](https://discord.com/invite/KKGhy8ZqzK)
 
+A javascript software development kit for the Multi-Chain Storage (MCS) https://www.multichain.storage/ service. It provides a convenient interface for working with the MCS API from a web browser or Node.js. This SDK has the following functionalities:
+
 # Table of Contents <!-- omit in toc -->
 
-- [Introduction](#introduction)
-  - [For Onchain Storage](#for-onchain-storage)
-  - [For Buckets Storage](#for-buckets-storage)
 - [Getting Started](#getting-started)
-  - [Prerequisites](#prerequisites)
   - [Installation](#installation)
-  - [Examples](#examples)
+- [Examples](#examples)
+  - [For Onchain Storage](#for-onchain-storage)
+  - [For Buckets Storage](#for-buckets-storage)
+- [Functions](#functions)
 - [Contributing](#contributing)
 
-<a name="introduction"></a>
-
-# ℹ️ Introduction
-
-A javascript software development kit for the Multi-Chain Storage (MCS) https://www.multichain.storage/ service. It provides a convenient interface for working with the MCS API from a web browser or Node.js. This SDK has the following functionalities:
-
-## For Onchain Storage
-
-- **POST** Upload file to Filswan IPFS gateway
-- **GET** List of files uploaded
-- **GET** Files by cid
-- **GET** Status from filecoin
-- **CONTRACT** Make payment to swan filecoin storage gateway
-- **CONTRACT** Mint asset as NFT
-
-## For Buckets Storage
-
-- **POST** Create a bucket
-- **POST** Create a folder
-- **POST** Upload File to the bucket
-- **POST** Rename bucket
-- **GET** Delete bucket
-- **GET** Bucket List
-- **GET** File List
-- **GET** File information
-- **GET** Delete File
-
 <a name="getting-started"></a>
 
-# 🆕 Getting Started
+## 🆕 Getting Started
 
-## Prerequisites
+### Prerequisites
 
-- [Node.js](https://nodejs.org/en/) - v16.13.0 (npm v8.1.0) \
-- Polygon Wallet - [Metamask Tutorial](https://docs.filswan.com/getting-started/beginner-walkthrough/public-testnet/setup-metamask) \
-- Polygon Mainnet RPC endpoint - https://polygon-rpc.com (USDC and Matic are required if you want to make payment.)
-- API Key and Access Token - Obtained via https://multichain.storage
+- [Node.js](https://nodejs.org/en/) - v16.13.0 (npm v8.1.0)
+- API Key and Access Token - Generated via https://multichain.storage
 
-## Installation
+### Installation
 
 In a new working directory, use `npm init -y` to initialize a Node.js project.
 Install the package using npm
@@ -62,99 +34,122 @@ npm init -y
 npm install js-mcs-sdk
 ```
 
-<a name="examples"></a>
+### Setup Credentials
 
-# 👨‍💻 Examples
+Create a .env file that includes the following content. Optionally include your wallet's private key and RPC-url.
 
-Here is the demo to get you started; you can get more information in the [SDK documentation.](https://docs.filswan.com/multi-chain-storage/developer-quickstart/sdk)
+```bash
+API_KEY='<API_KEY>'
+ACCESS_TOKEN='<ACCESS_TOKEN>'
 
-1. Set Up Environment Variables
+# for onchain storage only
+PRIVATE_KEY='<PRIVATE_KEY>'
+RPC_URL='<RPC_URL>'
+```
 
-   Create a .env file that includes the following content. Optionally include your wallet's private key and RPC-url.
+### Initialize SDK
 
-   ```bash
-   API_KEY='<API_KEY>'
-   ACCESS_TOKEN='<ACCESS_TOKEN>'
+```js
+require('dotenv').config()
+const { mcsSDK } = require('js-mcs-sdk')
 
-   # optional
-   PRIVATE_KEY='<PRIVATE_KEY>'
-   RPC_URL='<RPC_URL>'
-   ```
+async function main() {
+  // initialize js-mcs-sdk
+  const mcs = await mcsSDK.initialize({
+    apiKey: process.env.API_KEY,
+    accessToken: process.env.ACCESS_TOKEN,
+    chainName: 'polygon.mainnet',
+  })
+}
 
-   1. **_The `RPC_URL` is the one mentioned above_**
-   2. **_`PRIVATE_KEY` will be obtained from the wallet_**
-   3. **_The `API_KEY` and `ACCESS_TOKEN` can be generated from the Settings page on [multichain.storage](#https://www.multichain.storage/)_**
+main()
+```
 
-2) Initalize SDK
+<a name="examples"></a>
 
-   To begin using the SDK, we first need to require the package at the top of the script and call the `initialize` function
+## 👨‍💻 Examples
 
-   ```js
-   require('dotenv').config()
-   const { mcsSDK } = require('js-mcs-sdk')
+### Onchain Storage
 
-   async function main() {
-     // initialize js-mcs-sdk
-     const mcs = await mcsSDK.initialize({
-       apiKey: process.env.API_KEY,
-       accessToken: process.env.ACCESS_TOKEN,
-       chainName: 'polygon.mainnet',
-     })
-   }
+Onchain storage is designed for storing file information in the smart contract. It requires payment for each file.
 
-   main()
-   ```
+To use certain Onchain Storage features (upload, payment, minting), you will need to set up the web3 environment first.
 
-   Optionally, you can pass `privateKey` to use the onChain Storage upload and payment functions and pass `rpcUrl` if you wish to use your own RPC URL (this SDK uses https://polygon-rpc.com/ by default).
+- Setup Web3
 
-   This SDK is also compatiable with our calibration environment on the Mumbai testnet. Use `chainName: 'polygon.mumbai'` and generate a new API KEY from [calibration-mcs.filswan.com/](https://calibration-mcs.filswan.com/)
+  ```js
+  await mcs.setupWeb3(process.env.PRIVATE_KEY, process.env.RPC_URL)
+  console.log(mcs.web3Initialized) // true
+  ```
 
-   ### For Onchain Storage
+- Upload File to Onchain storage
 
-   To use certain Onchain Storage features (upload, payment, minting), you will need to set up the web3 environment first.
+  ```js
+  let uploadResponse = await mcs.upload([{ fileName: <FILE_NAME>, file: fs.createReadStream(<FILE_PATH>) }])
+  console.log(uploadResponse)
+  ```
 
-   - Setup Web3
+- Pay for file storage
+  after uploading, the response should return the `source_file_upload_id` and the file size.
+  ```js
+  let tx = await mcs.makePayment(<SOURCE_FILE_UPLOAD_ID>, <FILE_SIZE>)
+  console.log(transaction hash: ' + tx.transactionHash)
+  ```
 
-   ```js
-   await mcs.setupWeb3(<PRIVATE_KEY>, <RPC_URL>)
-   console.log(mcs.web3Initialized) // true
-   ```
+### Bucket Storage
 
-   - Upload File to Onchain storage
+- Create a bucket
 
-   ```js
-   console.log(await mcs.upload([{ fileName: <FILE_NAME>, file: fs.createReadStream(<FILE_PATH>) }]))
-   ```
+  ```js
+  let bucketData = await mcs.createBucket(<BUCKET_NAME>)
+  console.log(bucketData)
+  ```
 
-   ### For Bucket Storage
+- Upload a file to the bucket
 
-   - Create a bucket
+  ```js
+  let fileData = mcs.uploadToBucket(<FILE_PATH>, <BUCKET_UID>, prefix="")
+  console.log(fileData)
+  ```
 
-   ```js
-   console.log(await mcs.createBucket(<BUCKET_NAME>))
-   ```
+For more examples, please see the [SDK documentation.](https://docs.filswan.com/multi-chain-storage/developer-quickstart/sdk)
+
+<a name="functions"></a>
+
+## ℹ️ Functions
 
-   - Upload a file to the bucket
+### For Onchain Storage
 
-   ```js
-   console.log(mcs.uploadToBucket(<FILE_PATH>,<BUCKET_UID>,prefix=''))
-   ```
+---
 
-   _The prefix field defines the file-folder relationship, leaving it blank if the file exists directly in the Bucket or the folder name if the file exists in a folder that already exists in the Bucket._
+- **POST** Upload file to Filswan IPFS gateway
+- **GET** List of files uploaded
+- **GET** Files by cid
+- **GET** Status from filecoin
+- **CONTRACT** Make payment to swan filecoin storage gateway
+- **CONTRACT** Mint asset as NFT
 
-   **_You have to create a bucket before you upload a file._**
+### For Buckets Storage
 
-   **_Note that if you upload a file with the prefix field defined in a folder that has not yet been created, you will not be able to see the file until you create a folder with the same name._**
+---
 
-For more examples, please see the [SDK documentation.](https://docs.filswan.com/multi-chain-storage/developer-quickstart/sdk)
+- **POST** Create a bucket
+- **POST** Create a folder
+- **POST** Upload File to the bucket
+- **POST** Rename bucket
+- **GET** Delete bucket
+- **GET** Bucket List
+- **GET** File List
+- **GET** File information
+- **GET** Delete File
 
 <a name="contributing"></a>
 
-# 🌐 Contributing
+## 🌐 Contributing
 
 Feel free to join in and discuss. Suggestions are welcome! [Open an issue](https://github.com/filswan/js-mcs-sdk/issues) or [Join the Discord](https://discord.com/invite/KKGhy8ZqzK)!
 
-## Sponsors
+### Sponsors
 
 Filecoin Foundation sponsors this project