⏱️Quickstart

Learn how to get started with the DDC using the SDK Client library.

In order to complete this guide using the DDC Client library, you should have an account in Cere blockchain that has enough CERE tokens (amount depends on your needs) and the secret phrase (mnemonic) of that account (required to configure the client).

Use the 🔗 Setup guide to create and top-up an account.

Installation

Node JS

Latest version of SDK can be found on releases page.

Using NPM:

npm install @cere-ddc-sdk/ddc-client --save

Using yarn:

yarn add @cere-ddc-sdk/ddc-client

Usage

A quick guide of how to upload a file to DDC Testnet using the DdcClient API.

Create a DdcClient instance

To initialize the client we will use the account (wallet) created in Setup guide

TypeScript

import { DdcClient, TESTNET } from '@cere-ddc-sdk/ddc-client';

const seedPhrase = 'gospel fee escape timber toilet crouch artist catalog salt icon bulb ivory';
const ddcClient = await DdcClient.create(seedPhrase, TESTNET);

The account used to create the instance should have positive balance and DDC deposit

Create a bucket

TypeScript

Private bucket (by default)

const bucketId = await client.createBucket(clusterId);

or a public one

const bucketId = await client.createBucket(clusterId, { isPublic: true });

Creating a bucket results in a transaction on the Cere blockchain, and thus a portion of your wallet balance will be used to pay the associated fees.

Upload a file

To optimize memory consumption, we will read the file from the file system using NodeJS readable stream.

TypeScript

import * as fs from 'fs';
import { File } from '@cere-ddc-sdk/ddc-client';

const filePath = './my-picture.jpg';
const fileStats = fs.statSync(filePath);
const fileStream = fs.createReadStream(filePath);
const file = new File(fileStream, { size: fileStats.size });

const { cid: fileCid } = await ddcClient.store(bucketId, file);

console.log('The uploaded file CID', fileCid)

As a result, you will receive the unique Content Identifier (CID) of the uploaded file. This CID will be used later to access the file on the DDC.

Share the file

DDC offers Web API access to files, allowing them to be shared via URLs.

TypeScript

If the file's bucket is private

import { AuthTokenOperation } from '@cere-ddc-sdk/ddc-client';

const accessToken = await ddcClient.grantAccess({
  bucketId,
  pieceCid: fileCid,
  operations: [AuthTokenOperation.GET],
});

const fileUrl = `https://cdn.testnet.cere.network/${bucketId}/${fileCid}?token=${accessToken}`;

console.log('The file URL', fileUrl);

or public

const fileUrl = `https://cdn.testnet.cere.network/${bucketId}/${fileCid}`;

console.log('The file URL', fileUrl);

It is also possible to download the file by its CID using the SDK Client

TypeScript

To optimize memory consumption, we will store the file to the file system using NodeJS writable stream.

import * as fs from 'fs';
import { pipeline } from 'stream/promises';
import { Readable } from 'stream';
import { FileUri } from '@cere-ddc-sdk/ddc-client';

const outputFilePath = './my-downloaded-picture.jpg';

const uri = new FileUri(bucketId, fileCid);
const fileResponse = await ddcClient.read(uri, { accessToken });
const outputFileStream = fs.createWriteStream(outputFilePath);

/**
 * Stream the content from DDC to the destination file
 */
await pipeline(Readable.fromWeb(fileResponse.body), outputFileStream);

console.log('The file downloaded to', outputFilePath);

---

For more information about what this package provides, see API reference