js-mcs-sdk
Table of Contents
Introduction
A client library for the Multi-Chain Storage (MCS) https://mcs.filswan.com service. It provides a convenient interface for working with the MCS API from a web browser or Node.js. This client has the following functionalities:
- POST upload file to Filswan IPFS gate way
- POST make payment to swan filecoin storage gate way
- GET status from filecoin
- POST mint asset as NFT
- GET list of files uploaded
- GET files by cid
Prerequisites
Node.js - v16.13.0 (npm v8.1.0)
Polygon Mumbai Testnet Wallet - Metamask Tutorial
Polygon Mumbai Testnet RPC - Signup via Alchemy
You will also need Testnet USDC and MATIC balance to use this client. Swan Faucet Tutorial
MCS API
For more information about the API usage, check out the MCS API documentation.
Usage
Instructions for developers working with MCS Client and API.
Installation
Install the package using npm
npm install mcs-client
Getting Started
First you should set your private key and RPC-url as environment variables in a .env file
PRIVATE_KEY=<PRIVATE_KEY>
RPC_URL=https://polygon-mumbai.g.alchemy.com/v2/<API_KEY>
Example of uploading a single file using the MCS Client.
require('dotenv').config()
const { mcsClient } = require('mcs-client')
// set up mcs-client
const client = new mcsClient({
privateKey: process.env.PRIVATE_KEY,
rpcUrl: process.env.RPC_URL,
})
async function main() {
const testFile = JSON.stringify({ address: client.publicKey })
const fileArray = [{ fileName: 'testFile.json', file: testFile }]
const uploadResponse = await client.upload(fileArray)
console.log(uploadResponse)
}
main()
Documentation
The following functions documentation will assume you have a MCS client instantiated. Using the client variable for the following examples.
const client = new mcsClient({
privateKey: process.env.PRIVATE_KEY,
rpcUrl: process.env.RPC_URL,
})
upload(files, options) - Uploading File(s)
You can use the MCS Client to upload and array of file(s) to Filswan IPFS gateway. The array holds a list of objects, and returns an array of response objects. Using fs is a simple way to read the file data. The options object is also optional to customize the upload.
const fileArray = [
{ fileName: 'file1', file: fs.createReadStream('./file1.txt') },
{ fileName: 'file2', file: fs.createReadStream('./file2.txt') },
]
//optional, showing default options
const options = {
delay: 1000, // delay between upload API calls for each file. May need to be raised for larger files
duration: 180, // the number of days to store the file on the Filecoin network.
fileType: 0, // set to 1 for nft metadata files. type 1 files will not show on the UI.
}
const uploadResponses = await client.upload(fileArray, options)
console.log(uploadResponses)
/* return
[
{
status: 'success',
code: '200',
data: {
payload_cid: 'bafk...',
ipfs_url: 'https://calibration-ipfs.filswan.com/ipfs/Qm...',
need_pay: <int>
}
},
{
status: 'success',
code: '200',
data: {
payload_cid: 'bafk...',
ipfs_url: 'https://calibration-ipfs.filswan.com/ipfs/Qm...',
need_pay: <int>
}
}
]
*/
makePayment(payloadCid, amount) - Pay for File Storage
Use USDC tokens to pay for your unpaid uploaded file. You need the payload_cid of the file. Returns a web3 receipt object
const PAYLOAD_CID = ''
const tx = await client.makePayment(PAYLOAD_CID, '0.05')
console.log(tx.transactionHash)
/* return (tx hash, can view on mumbai polygonscan)
0x...
*/
Note that amount is a type String. This is to avoid Big Number precision errors when dealing to amounts in Wei
checkStatus(dealCid) - Check File Status from Filecoin
Check the Filecoin storage status of a file using it's deal_cid
PAYLOAD_CID = ''
// search for file info to get deal_cid
const uploadInfo = await client.listUploads(client.publicKey, PAYLOAD_CID)
const dealCid = uploadInfo.data[0].deal_cid
if (dealCid) {
const fileStatus = await client.checkStatus(dealCid)
console.log(fileStatus)
} else {
console.log('deal_cid not found')
}
/* return
{
status: 'success',
code: '200',
data: {
offline_deal_logs: [ [Object], [Object], [Object], [Object], [Object] ]
}
}
*/
mintAsset(payloadCid, nft) - Mint Asset as NFT
After you upload a file, you can mint it to Opensea (testnet) as an NFT. First you will need your NFT metadata. Similarly to makePayment this function will return a web3 receipt object
const PAYLOAD_CID = ''
const IPFS_URL = ''
const nft = {
name: 'File 1', // the name of your NFT
description: 'This is the first file', // the description of your NFT
image: IPFS_URL, // asset URI, images will render on Opensea
}
const mintTx = await client.mintAsset(PAYLOAD_CID, nft)
console.log(mintTx)
listUploads(wallet, payloadCid, fileName, pageNumber, pageSize) - View Uploaded Files
This function will return an object of uploaded files. All the parameters have default values, so you can pass no parameters to view all your uploaded files.
console.log(await client.listUploads())
You can search for files, either by payload_cid or by file_name
console.log(await client.listUploads(client.publicKey, payloadCid))
console.log(await client.listUploads(client.publicKey, '', 'file1')
getFileDetails(payloadCid, dealId) View File Details
Using listUploads, you can retreive the payload_cid and deal_id of a file. Calling this function will return an object containing the details of the file.
console.log(await client.getFileDetails(payloadCid, 0))
Contributing
Feel free to join in and discuss. Suggestions are welcome! Open an issue or Join the Discord!
Sponsors
This project is sponsored by Filecoin Foundation
Flink SDK - A data provider offers Chainlink Oracle service for Filecoin Network
4 May 3, 2022
14 Jan 3, 2023
23 Jan 3, 2023
117 Jan 2, 2023
30 Jan 5, 2023
47 Oct 17, 2022
10 Sep 30, 2022
8 Aug 5, 2022
6 Mar 14, 2022
303 Jan 2, 2023