Skip to content

CESS DeOSS

Jump to bottom
hong edited this page Jul 25, 2023 · 3 revisions

Please refer to the most updated version!

Introduction

CESS Decentralized Object Storage Service (DeOSS) aims to provide low-cost, secure, and scalable decentralized data storage services for Web3. Both individuals and enterprises can use DeOSS to store, manage and share data, such as NFT images and videos, dApp user data, and DeFi programs.

The mission of DeOSS is to return data ownership back to the data creators, rather than being owned by centralized institutions. DeOSS follows the Apache 2.0 open-source protocol, allowing anyone to deploy and access files stored anywhere in the world.

In the first stage of the roadmap, CESS DeOSS will provide a standard storage method to implement the basic functions of object storage, including storage space purchase, storage container creation/deletion, file upload/download/deletion, and permission verification for user access requests.

Configuration Requirement

· Linux-amd64

· Go1.19 or above

Deploy DeOSS

Step 1: Install the environment

Install Universal Tools

sudo apt upgrade -y && sudo apt install make gcc git curl wget vim util-linux -y

Install Golang

  1. Download go1.19.3.linux-amd64.tar.gz and extract it to /usr/local directory.
wget -c https://golang.org/dl/go1.19.3.linux-amd64.tar.gz -O - | sudo tar -xz -C /usr/local
  1. Add environment variables.
echo "export PATH=$PATH:/usr/local/go/bin" >> ~/.bashrc && source ~/.bashrc
  1. Check the golang version to confirm installation is successful.
go version

Step 2: Purchase Storage

  1. Wallet registration: Go to Create a CESS Wallet for CESS wallet registration guide.

  2. Add tokens to Wallet: If you are using the CESS testnet, please go to the CESS testnet-faucet (https://testnet-faucet.cess.cloud/) to get the test token for free. If you are using the official network then please purchase CESS tokens.

  3. Purchase storage: Please follow the Buy Space operation guide to purchase storage space.

  4. Space authorization: Please refer to Authorize to authorize the use of storage for DeOSS. Related links: Test Network CESS Blockchain Explorer | Official Network CESS Blockchain Explorer

Step 3: Set up DeOSS program

Compile and install DeOSS after downloading it when you completed all the steps above:

git clone https://github.com/CESSProject/cess-oss.git
cd cess-oss/
go build -o deoss cmd/main.go

Step 4: Configure and start DeOSS

  1. Use the DeOSS program to generate a configuration file template in the current directory
sudo chmod +x deoss
./deoss profile
  1. The content of the configuration file template is as follows, you need to fill in your own information in the file. By default, DeOSS uses conf.toml in the current directory as the runtime configuration file. You can specify the configuration file location with -c or --config. Note that the configuration file does not allow empty entries, so all information needs to be filled in.
# The rpc address of the chain node
RpcAddr     = "wss://testnet-rpc0.cess.cloud/ws/"
# The IP address of the machine's public network used by the scheduler program
ServiceAddr = ""
# Port number monitored by the scheduler program
ServicePort = "8081"
# Data storage directory
DataDir     = ""
# Phrase or seed of wallet account
AccountSeed = ""
  1. Start the DeOSS service
sudo nohup ./deoss run 2>&1 &

Other DeOSS Operation Instructions

  1. Update the DeOSS service IP address and port
./deoss update [ip] [port]
  1. DeOSS service address lookup
./deoss state

DeOSS API Operation Instructions

The public API endpoint URL of CESS-DeOSS is the server you deploy, All endpoints described in this document should be made relative to this root URL,The following example uses URL instead.

User Authentication

  • Interface Description

The authorization interface is for generating user tokens.

  • Request Method
POST
  • Request Header
key value
Content-Type application/json
  • Request Body
field value
account your account address
message custom signature message
signature signature data

Reference for signature calculation method: Link

  • Responses

Response schema: application/json

HTTP Code Message Description
200 token returns a token
400 Invalid.Body body content error
400 InvalidParameter.Account account error
400 InvalidParameter.Message message error
400 InvalidParameter.Signature signature error
403 NoPermission signature verification failed
500 InternalError service internal error
  • Request example
curl -X POST URL/auth -d '{"account": "cXgfFb...bjfR", "message": "123456", "signature": [44,30,117,...,109,141]}' -H "Content-Type: application/json"

Create a Bucket

  • Interface Description

The put bucket interface is for creating a bucket. When uploading files, the bucket must be specified for storage.

  • Request Method
PUT
  • Request Header
key value
Authorization token
  • Responses

Response schema: application/json

HTTP Code Message Description
200 Block hash create bucket block hash
400 InvalidHead.MissingToken token is empty
400 InvalidHead.Token token error
400 InvalidParameter.Name wrong bucket name
403 NoPermission signature verification failed
500 InternalError service internal error
  • Request example
curl -X PUT URL/BucketName -H "Authorization: eyJhbGciOiJIUzI1NiIsI......P0Jrg-hX4bXlIyn5I8ML1g"

File Upload

  • Interface Description

The put file interface is for uploading files to the CESS system. You need to submit the file as form data and use provide the specific field.

If the upload is successful, you will get the fileID (fid) of the file.

  • Request Method
PUT
  • Request Header
key value
Authorization token
BucketName stored bucket name
  • Request Body
key value
file file[binary]
  • Responses

Response schema: application/json

HTTP Code Message Description
200 fid file id
400 InvalidHead.MissingToken token is empty
400 InvalidHead.MissingBucketName bucketname is empty
400 InvalidHead.BucketName wrong bucket name
400 InvalidHead.Token token error
400 Invalid.DuplicateFileName duplicate file name
400 Unauthorized deoss is not authorized
400 InvalidParameter.EmptyFile file is empty
400 InvalidParameter.FormFile form File
400 InvalidParameter.File error receiving file
403 NoPermission signature verification failed
500 InternalError service internal error
  • Request example
curl -X PUT URL/test.log -F 'file=@test.log;type=application/octet-stream' -H "Authorization: eyJhbGciOiJIUzI...Iyn5I8ML1g" -H "BucketName: bucket1"

File Download

  • Interface Description

The get file interface downloads the file in the CESS storage system according to the fid.

  • Request Method
GET
  • Request Header
key value
Operation download
  • Request Body
key value
file file[binary]
  • Responses

The response schema for the normal return status is: application/octet-stream The response schema for the exception return status is: application/json, The message returned by the exception is as follows:

HTTP Code Message Description
400 InvalidHead.Operation operation error
403 BackingUp file is being backed up
404 NotFound file not found
500 InternalError service internal error
  • Request example
curl -X GET -o <savefilename> URL/fid -H "Operation: download"

File Deletion

  • Interface Description

The delete file interface is for deleting a put file.

  • Request Method
Delete
  • Request Header
key value
Authorization token
  • Responses

Response schema: application/json

HTTP Code Message Description
200 Block hash delete file block hash
400 InvalidHead.MissingToken token is empty
400 InvalidHead.Token token error
400 InvalidParameter.Name fid is error
403 NoPermission signature verification failed
500 InternalError service internal error
  • Request example
curl -X DELETE URL/fid -H "Authorization: eyJhbGciOiJIUzI1Ni......g-hX4bXlIyn5I8ML1g"

Delete Bucket

  • Interface Description

The delete bucket interface is for deleting a bucket, all files in the bucket will also be deleted altogether.

  • Request Method
Delete
  • Request Header
key value
Authorization token
  • Responses

Response schema: application/json

HTTP Code Message Description
200 Block hash delete bucket block hash
400 InvalidHead.MissingToken token is empty
400 InvalidHead.Token token error
400 InvalidParameter.Name fid is error
403 NoPermission signature verification failed
500 InternalError service internal error
  • Request example
curl -X DELETE URL/fid -H "Authorization: eyJhbGciOiJIUzI1Ni......g-hX4bXlIyn5I8ML1g"

Bucket detailed information Lookup

  • Interface Description

This interface is for looking up bucket information, including the number of stored files and file IDs.

  • Request Method
GET
  • Request Header
key value
Account account address
  • Responses

Response schema: application/json

HTTP Code Message Description
200 success total number of files in bucket and file id
400 InvalidHead.MissingAccount account is empty
400 InvalidHead.Account account is error
400 InvalidParameter.Name bucket name is error
404 NotFound bucket not found
500 InternalError service internal error
  • Request example
curl -X GET URL/BucketName -H "Account: cXgfFbnV9H......PMQLoKbjfR"

Bucket List Lookup

  • Interface Description

This interface is for looking up all buckets.

  • Request Method
GET
  • Request Header
key value
Account account address
  • Responses

Response schema: application/json

HTTP Code Message Description
200 success all bucket names
400 InvalidHead.MissingAccount account is empty
400 InvalidHead.Account account is error
400 InvalidParameter.Name * is error
404 NotFound bucket not found
500 InternalError service internal error
  • Request example
curl -X GET URL/* -H "Account: cXgfFbnV9H......PMQLoKbjfR"

File Information Lookup

  • Interface Description

This interface is for looking up the basic information of a file.

  • Request Method
GET
  • Request Header
key value
Operation view
  • Responses

Response schema: application/json

HTTP Code Message Description
200 success file information
400 InvalidParameter.Name fid or operation is error
404 NotFound file not found
500 InternalError service internal error
  • Request example
curl -X GET URL/fid -H "Operation: view"

Home

CESS Wallet

Storage Miners

Consensus Miners

CESS DeOSS

Smart Contracts in CESS Network

Clone this wiki locally