raintree-technology/shelby

Shelby Protocol Expert

Shelby is a decentralized blob storage network on Aptos blockchain with erasure coding, micropayment channels, and dedicated private bandwidth.

When to Use

• Building dApps that need decentralized storage
• Integrating Shelby SDK (TypeScript/Node.js/Browser)
• Understanding erasure coding and data durability
• Working with storage providers and RPC servers
• Video streaming, AI training data, large datasets

Architecture Overview

User (Public Internet)
  ↓
Shelby RPC Server (handles blob operations)
  ↓ (Private Fiber Network)
Storage Provider Servers (16 per placement group)
  ↓
Aptos L1 Blockchain (state management)

Key Components:

• Aptos Smart Contract - System state, audits, settlements
• Storage Providers - Store erasure-coded chunks
• RPC Servers - User-facing API, erasure coding/decoding
• Private Network - Dedicated fiber for internal communication

Data Model

Erasure Coding (Clay Codes)

Data is split and encoded for durability:

10MB Blob → Split into chunksets → Erasure code each
                                         ↓
                               16 chunks per chunkset
                               (10 data + 6 parity)
                                         ↓
                               Distributed to 16 storage providers

Recovery: Any 10 of 16 chunks can reconstruct data

Why Clay Codes?

• Same storage efficiency as Reed-Solomon
• 4x less bandwidth during recovery
• Optimal for large-scale distributed storage

Blob Naming

<account>/<user-defined-path>

Examples:
0x123.../videos/intro.mp4
0x123.../datasets/training/batch-001.parquet

• Max 1024 characters
• Must NOT end with /
• Flat namespace (no directories, just paths)

SDK Integration

Installation

npm install @shelby-protocol/sdk @aptos-labs/ts-sdk

Node.js Client

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

const client = new ShelbyNodeClient({
  network: Network.SHELBYNET,
  apiKey: process.env.SHELBY_API_KEY,
});

Browser Client

import { ShelbyClient } from "@shelby-protocol/sdk/browser";
import { Network } from "@aptos-labs/ts-sdk";

const client = new ShelbyClient({
  network: Network.SHELBYNET,
  apiKey: process.env.SHELBY_API_KEY,
});

Common Operations

Upload Blob

const result = await client.uploadBlob({
  blobName: "user/data/file.txt",
  data: fileBuffer,
  expirationTimestamp: Date.now() + 30 * 24 * 60 * 60 * 1000, // 30 days
});

Download Blob

// Full blob
const data = await client.getBlob("user/data/file.txt");

// Byte range (efficient for large files)
const partial = await client.getBlob("user/data/file.txt", {
  range: { start: 0, end: 1024 },
});

Multipart Upload (Large Files)

For files > 10MB:

const upload = await client.startMultipartUpload({
  blobName: "large-dataset.bin",
  expirationTimestamp: futureTimestamp,
});

for (const [index, part] of fileParts.entries()) {
  await client.uploadPart({
    uploadId: upload.id,
    partNumber: index,
    data: part,
  });
}

await client.completeMultipartUpload({ uploadId: upload.id });

Session Management

Reuse sessions for multiple operations:

const session = await client.createSession({
  rpcUrl: "https://api.shelbynet.shelby.xyz/shelby",
  paymentAmount: 1000000, // ShelbyUSD micro-units
});

// Multiple reads on same session
for (const blobName of blobsToDownload) {
  await client.getBlob(blobName, { session });
}

await session.close();

Token Economics

Two-Token Model

| Token | Purpose | |-------|---------| | APT | Blockchain gas fees | | ShelbyUSD | Storage and bandwidth payments |

Funding

# APT from faucet
aptos account fund-with-faucet --profile my-profile --amount 1000000000

# ShelbyUSD from faucet
# Visit: https://faucet.shelbynet.shelby.xyz

Use Cases

Ideal Workloads:

• Video streaming (high bandwidth reads)
• AI training/inference (large datasets)
• Data analytics (read-heavy patterns)
• Content delivery (static assets)
• Archival storage (long-term retention)

Trade-offs:

• Optimized for large files (10MB+ chunksets)
• Blobs are immutable (no updates, only overwrite)
• User-pays model (storage + bandwidth)

Resources

• Documentation: https://docs.shelby.cloud
• Faucet: https://faucet.shelbynet.shelby.xyz
• SDK: @shelby-protocol/sdk