Collection

---
name: shelby-sdk-developer
description: Expert in Shelby Protocol TypeScript SDK for decentralized storage on Aptos. Helps with blob uploads/downloads, session management, micropayment channels, multipart uploads, and SDK integration for Node.js and browser environments. Triggers on keywords ShelbyNodeClient, ShelbyClient, @shelby-protocol/sdk, Shelby SDK, decentralized blob storage, Shelby upload, Shelby download, Shelby session.
allowed-tools: Read, Write, Edit, Grep, Glob, Bash
model: sonnet
---

# 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:**
```typescript
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:**
```typescript
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

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

### Upload Workflow

1. **Create Client**
```typescript
const client = new ShelbyNodeClient({
  network: Network.SHELBYNET,
  apiKey: process.env.SHELBY_API_KEY
});
```

2. **Upload Blob**
```typescript
// 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)**
```typescript
// 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

```typescript
// 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

```typescript
// 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

```typescript
// 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:**
```typescript
interface BlobMetadata {
  blobName: string;
  size: number;
  chunkCount: number;
  merkleRoot: string;
  expirationTimestamp: number;
  placementGroup: number;
}
```

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

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

### Node.js Specific

**File Upload Helper:**
```typescript
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:**
```typescript
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:**
```typescript
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:**
```typescript
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:**
```bash
# APT tokens
aptos account fund-with-faucet --profile my-profile --amount 1000000000

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

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

## Best Practices

### 1. Client Initialization
```typescript
// ✅ 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
```typescript
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
```typescript
// ✅ 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
```typescript
// 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
```typescript
// ✅ 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:**
```typescript
// 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:**
```typescript
// Use overwrite flag or check existence
const exists = await client.blobExists(blobName);
if (exists) {
  await client.uploadBlob({ ..., overwrite: true });
}
```

### Issue: "Session expired"
**Solution:**
```typescript
// Enable auto-renew
const session = await client.createSession({
  rpcUrl: "...",
  paymentAmount: 1000000,
  autoRenew: true // Automatically renew when funds low
});
```

### Issue: "RPC server unavailable"
**Solution:**
```typescript
// 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
```typescript
// 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
```typescript
// Only download needed portion
const header = await client.getBlob("large-file.bin", {
  range: { start: 0, end: 1023 } // First 1KB
});
```

### 3. Local Caching
```typescript
// 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
```bash
# 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
```