Shelby SDK Developer

Purpose

Expert guidance for developers integrating Shelby Protocol's decentralized storage system using the TypeScript SDK. Shelby is a high-performance blob storage network built on Aptos blockchain with erasure coding, micropayment channels, and dedicated private bandwidth.

When to Use

Auto-invoke when users mention:

• SDK Integration - ShelbyNodeClient, ShelbyClient, @shelby-protocol/sdk
• Operations - upload blob, download blob, Shelby storage, file storage
• Features - session management, micropayment channel, multipart upload
• Environments - Node.js Shelby, browser Shelby, TypeScript SDK
• Workflows - blob operations, storage integration, decentralized storage

Knowledge Base

All Shelby Protocol documentation is located in:

.claude/skills/blockchain/aptos/docs/

Key documentation files:

• sdks_typescript.md - SDK overview and installation
• sdks_typescript_core_specifications.md - Core SDK types and functions
• sdks_typescript_node_specifications.md - Node.js specific APIs
• sdks_typescript_browser.md - Browser environment APIs
• sdks_typescript_node_guides_uploading-file.md - Upload workflows
• sdks_typescript_acquire-api-keys.md - API key setup
• protocol_architecture_overview.md - System architecture

Core Concepts

1. Shelby Architecture

• Aptos Smart Contract - Manages system state and data correctness audits
• Storage Providers (SP) - Store erasure-coded chunks of user data
• RPC Servers - User-facing API for blob operations
• Private Network - Fiber network for internal communication

2. Data Model

• Blobs - User data stored in account-specific namespaces
• Chunking - Data split into 10MB chunksets, erasure coded to 16 chunks
• Erasure Coding - Clay Codes provide 10 data + 6 parity chunks
• Placement Groups - Manage chunk distribution across 16 storage providers

3. SDK Components

Node.js:

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

const config = {
  network: Network.SHELBYNET,
  apiKey: "aptoslabs_***",
};

const shelbyClient = new ShelbyNodeClient(config);

Browser:

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

const config = {
  network: Network.SHELBYNET,
  apiKey: "aptoslabs_***",
};

const shelbyClient = new ShelbyClient(config);

Common Tasks

Installation

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

Upload Workflow

1. Create Client

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

2. Upload Blob

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

3. Multipart Upload (Large Files)

// For files > chunkset size (10MB)
const upload = await client.startMultipartUpload({
  blobName: "large-dataset.bin",
  expirationTimestamp: futureTimestamp
});

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

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

Download Workflow

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

// Download byte range
const partialBlob = await client.getBlob("user/data/file.txt", {
  range: { start: 0, end: 1024 }
});

Session Management

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

// Use session for reads
const data = await client.getBlob("blob/name", { session });

// Close session when done
await session.close();

Micropayment Channels

// Create micropayment channel for efficient payments
const channel = await client.createMicropaymentChannel({
  amount: 10000000, // ShelbyUSD micro-units
  recipient: rpcServerAddress
});

// Channel automatically manages payments during operations

SDK Specifications

Core Types

BlobMetadata:

interface BlobMetadata {
  blobName: string;
  size: number;
  chunkCount: number;
  merkleRoot: string;
  expirationTimestamp: number;
  placementGroup: number;
}

UploadOptions:

interface UploadOptions {
  blobName: string;
  data: Buffer | ReadableStream;
  expirationTimestamp: number;
  overwrite?: boolean;
}

SessionConfig:

interface SessionConfig {
  rpcUrl: string;
  paymentAmount: number;
  autoRenew?: boolean;
}

Node.js Specific

File Upload Helper:

import { uploadFile } from "@shelby-protocol/sdk/node";

await uploadFile({
  client,
  filePath: "/path/to/file.txt",
  blobName: "stored/file.txt",
  expirationTimestamp: Date.now() + 30 * 24 * 60 * 60 * 1000
});

Stream Support:

import fs from 'fs';

const readStream = fs.createReadStream('large-file.bin');
await client.uploadBlob({
  blobName: "stream-upload.bin",
  data: readStream,
  expirationTimestamp: futureDate
});

Browser Specific

File Input Handling:

async function handleFileUpload(file: File) {
  const arrayBuffer = await file.arrayBuffer();

  await shelbyClient.uploadBlob({
    blobName: `uploads/${file.name}`,
    data: new Uint8Array(arrayBuffer),
    expirationTimestamp: Date.now() + 30 * 24 * 60 * 60 * 1000
  });
}

Progress Tracking:

const result = await shelbyClient.uploadBlob({
  blobName: "file.txt",
  data: fileData,
  expirationTimestamp: futureDate,
  onProgress: (progress) => {
    console.log(`Upload: ${progress.percentage}%`);
  }
});

Token Economics

Required Tokens

1. APT (Aptos Tokens) - Gas fees for blockchain transactions
2. ShelbyUSD - Storage and bandwidth payments

Funding Accounts

Get tokens from faucet:

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

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

Check balance:

const balance = await client.getAccountBalance();
console.log(`APT: ${balance.apt}`);
console.log(`ShelbyUSD: ${balance.shelbyUSD}`);

Best Practices

1. Client Initialization

// ✅ Singleton pattern for long-lived applications
class ShelbyService {
  private static client: ShelbyNodeClient;

  static getClient() {
    if (!this.client) {
      this.client = new ShelbyNodeClient({
        network: Network.SHELBYNET,
        apiKey: process.env.SHELBY_API_KEY
      });
    }
    return this.client;
  }
}

2. Error Handling

try {
  await client.uploadBlob(options);
} catch (error) {
  if (error.code === 'INSUFFICIENT_FUNDS') {
    // Handle funding issue
  } else if (error.code === 'BLOB_ALREADY_EXISTS') {
    // Handle duplicate blob
  } else {
    // Generic error handling
  }
}

3. Blob Naming

// ✅ Use hierarchical paths
"users/0x123.../documents/report.pdf"
"projects/my-app/assets/logo.png"

// ❌ Avoid ending with /
"users/0x123.../" // Invalid

// ✅ Canonical directory structure
"prefix/bar"
"prefix/foo/baz"
"prefix/foo/buzz"

4. Large File Handling

// Files > 10MB: Use multipart upload
const FILE_SIZE_THRESHOLD = 10 * 1024 * 1024; // 10MB

async function smartUpload(file: Buffer, blobName: string) {
  if (file.length > FILE_SIZE_THRESHOLD) {
    return await multipartUpload(file, blobName);
  }
  return await client.uploadBlob({ blobName, data: file, ... });
}

5. Session Reuse

// ✅ Reuse sessions for multiple operations
const session = await client.createSession({...});

for (const blob of blobsToDownload) {
  await client.getBlob(blob, { session });
}

await session.close();

Common Issues & Solutions

Issue: "Insufficient ShelbyUSD tokens"

Solution:

// Check balance first
const balance = await client.getAccountBalance();
if (balance.shelbyUSD < estimatedCost) {
  throw new Error('Please fund account with ShelbyUSD');
}

Issue: "Blob name already exists"

Solution:

// Use overwrite flag or check existence
const exists = await client.blobExists(blobName);
if (exists) {
  await client.uploadBlob({ ..., overwrite: true });
}

Issue: "Session expired"

Solution:

// Enable auto-renew
const session = await client.createSession({
  rpcUrl: "...",
  paymentAmount: 1000000,
  autoRenew: true // Automatically renew when funds low
});

Issue: "RPC server unavailable"

Solution:

// Implement retry logic
async function uploadWithRetry(options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await client.uploadBlob(options);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(1000 * Math.pow(2, i)); // Exponential backoff
    }
  }
}

Performance Optimization

1. Concurrent Uploads

// Upload multiple blobs in parallel
const uploads = files.map(file =>
  client.uploadBlob({
    blobName: file.name,
    data: file.data,
    expirationTimestamp: futureDate
  })
);

await Promise.all(uploads);

2. Byte Range Downloads

// Only download needed portion
const header = await client.getBlob("large-file.bin", {
  range: { start: 0, end: 1023 } // First 1KB
});

3. Local Caching

// Cache frequently accessed blobs
const cache = new Map<string, Buffer>();

async function getCachedBlob(blobName: string) {
  if (cache.has(blobName)) {
    return cache.get(blobName);
  }

  const data = await client.getBlob(blobName);
  cache.set(blobName, data);
  return data;
}

Process for Helping Users

1. Identify Task

• Setup/installation
• Upload implementation
• Download implementation
• Session management
• Error troubleshooting
• Performance optimization

2. Search Documentation

# Find relevant docs
Grep "upload|download" docs/ --output-mode files_with_matches
Read docs/sdks_typescript_node_guides_uploading-file.md

3. Provide Solution

• Show complete code example
• Explain key concepts
• Handle error cases
• Reference token requirements
• Suggest optimizations

4. Follow-up

• Testing recommendations
• Monitoring suggestions
• Cost optimization tips
• Security best practices

References

When helping users, cite specific documentation:

• SDK guides: .claude/skills/blockchain/aptos/docs/sdks_typescript_*.md
• Protocol architecture: .claude/skills/blockchain/aptos/docs/protocol_architecture_*.md
• API endpoints: .claude/skills/blockchain/aptos/docs/apis_rpc_*.md

Response Style

• Code-first - Show working examples immediately
• Practical - Focus on real-world usage
• Complete - Include imports, config, error handling
• Modern - Use async/await, TypeScript best practices
• Tested - Only suggest patterns documented in official guides

Example Interaction

User: "How do I upload a file to Shelby from Node.js?"

Response:
1. Install dependencies
2. Show complete upload example with error handling
3. Explain token requirements (APT + ShelbyUSD)
4. Mention blob naming best practices
5. Suggest multipart upload for large files
6. Reference: docs/sdks_typescript_node_guides_uploading-file.md