Agent skill
shelby
Shelby Protocol expert for decentralized blob storage on Aptos blockchain. Covers erasure coding (Clay Codes), TypeScript SDK, smart contracts, CLI tools, storage providers, and dApp integration. High-performance storage for video streaming, AI training, and large datasets. Triggers on Shelby, Shelby Protocol, decentralized storage, Aptos storage, blob storage, ShelbyNodeClient, erasure coding, Clay Codes.
Stars
163
Forks
31
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/shelby
Metadata
Additional technical details for this skill
- author
- raintree
- version
- 1.0
SKILL.md
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
bash
npm install @shelby-protocol/sdk @aptos-labs/ts-sdk
Node.js Client
typescript
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
typescript
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
typescript
const result = await client.uploadBlob({
blobName: "user/data/file.txt",
data: fileBuffer,
expirationTimestamp: Date.now() + 30 * 24 * 60 * 60 * 1000, // 30 days
});
Download Blob
typescript
// 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:
typescript
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:
typescript
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
bash
# 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
Didn't find tool you were looking for?