Overview

In this guide, we will walk you through the process of obtaining ShelbyUSD tokens and uploading a file to the Shelby network.

This guide assumes you already have a Node.js environment setup and will be using the Shelbynet network.

Getting Started

Installation

To get started, you will need to install the following dependencies to your Node.js environments.

npm install @shelby-protocol/sdk @aptos-labs/ts-sdk fs-extra glob node-fetch yaml

To setup a signer, you will need to have a private key for the signer you want to use. There are multiple ways to obtain a private key but for this example we will be using the aptos CLI. If you do not have the aptos CLI installed, you can install it by following the instructions here.

aptos init --network custom --rest-url https://api.shelbynet.shelby.xyz/v1 --faucet-url https://faucet.shelbynet.shelby.xyz

You can now find the private key and account address in the .aptos/config.yaml file.

cat .aptos/config.yaml

Should result in the following output:

---
profiles:
  default:
    network: Custom
    private_key: ed25519-priv-0x...
    public_key: ed25519-pub-0x...
    account: ...
    rest_url: "https://api.shelbynet.shelby.xyz/v1"
    faucet_url: "https://faucet.shelbynet.shelby.xyz"

To instantiate an Account object from the @aptos-labs/ts-sdk package, you can use the following code alongside your ed25519-priv private key from the config.yaml file.

uploadScript.ts

import { Ed25519Account, Ed25519PrivateKey } from "@aptos-labs/ts-sdk";

const signer = new Ed25519Account({
  privateKey: new Ed25519PrivateKey("ed25519-priv-<value_of_private_key_from_config.yaml>"),
});

Funding your signer

To upload a file, you will need to have a signer with two assets:

APT tokens: Used to pay for gas fees when sending transactions
ShelbyUSD tokens: Used to pay for the upload the file to the Shelby network

To fund your signer with APT tokens, you can use the aptos CLI to fund your account with APT tokens.

aptos account fund-with-faucet --amount 1000000000000000000

To fund your signer with ShelbyUSD tokens, you can provide your account address to the Shelby Faucet found below.

Faucet

Setting up clients

Now that you have setup a signer with funds, you can start setting up your clients to interact with the Shelby network.

uploadScript.ts

import { Ed25519Account, Ed25519PrivateKey, Network } from "@aptos-labs/ts-sdk";
import { ShelbyNodeClient } from "@shelby-protocol/sdk/node";

const signer = new Ed25519Account({
  privateKey: new Ed25519PrivateKey("ed25519-priv-<value_of_private_key_from_config.yaml>"),
});

const shelbyClient = new ShelbyNodeClient({
  network: Network.SHELBYNET,
});

Uploading a file

Lastly, to upload a file you can use the upload function from the ShelbyNodeClient class to upload a file to the Shelby network.

uploadScript.ts

import { Ed25519Account, Ed25519PrivateKey, Network } from "@aptos-labs/ts-sdk";
import { ShelbyNodeClient } from "@shelby-protocol/sdk/node";
import fs from "fs/promises";

// 1. Setup your signer
const signer = new Ed25519Account({
  privateKey: new Ed25519PrivateKey("ed25519-priv-<value_of_private_key_from_config.yaml>"),
});

// 2. Setup your client
const shelbyClient = new ShelbyNodeClient({
  network: Network.SHELBYNET,
});

// 3. Get the file data
const blobData = await fs.readFile("file.txt");

// 4. Upload the file
await shelbyClient.upload({
  signer,
  blobData,
  blobName: "path/to/file.txt",
  expirationMicros: (1000 * 60 * 60 * 24 * 30 + Date.now()) * 1000, // 30 days
});

Retrieving a file (Optional)

To retrieve a file, you can use the getBlob function of the ShelbyRPCClient class to retrieve a file from the Shelby network.

getBlobScript.ts

import { Ed25519Account, Ed25519PrivateKey, Network } from "@aptos-labs/ts-sdk";
import { ShelbyNodeClient, ShelbyBlob } from "@shelby-protocol/sdk/node";
import fs from "fs";

// 1. Setup your signer
const signer = new Ed25519Account({
  privateKey: new Ed25519PrivateKey("ed25519-priv-<value_of_private_key_from_config.yaml>"),
});

// 2. Setup your client
const shelbyClient = new ShelbyNodeClient({
  network: Network.SHELBYNET,
});

// 3. Get the file
const blob: ShelbyBlob = await shelbyClient.download({
  account: signer.accountAddress,
  blobName: "path/to/file.txt",
});

// 4. Save the file
blob.stream.pipe(fs.createWriteStream("file.txt"));

Alternatively, you can directly download the file using a GET request to the Shelby RPC endpoint.

curl -X GET "https://api.shelbynet.shelby.xyz/shelby/v1/blobs/{signer_account_address}/{blob_name}" > file.txt

The API documentation is still under development and will be provided at a late date.

Basic Example

Blob Name	Account Address
`file.txt`	`0x1234567890123456789012345678901234567890`

curl -X GET "https://api.shelbynet.shelby.xyz/shelby/v1/blobs/0x1234567890123456789012345678901234567890/file.txt" > file.txt

Relative Paths Example

Blob Name	Account Address
`path/to/file.txt`	`0x1234567890123456789012345678901234567890`

curl -X GET "https://api.shelbynet.shelby.xyz/shelby/v1/blobs/0x1234567890123456789012345678901234567890/path/to/file.txt" > file.txt

Conclusion

And that is it! You have now uploaded a file to the Shelby network. For more information about the SDK, feel free to refer to the Specifications page.

Specifications

Reference documentation for the API and specifications

Uploading a File

Overview

Getting Started

Installation

Setting up a signer

Funding your signer

Faucet

Setting up clients

Uploading a file

Retrieving a file (Optional)

Conclusion

Specifications

On this page