walrus-ts

Walrus Typescript SDK

A TypeScript SDK for the Walrus decentralized storage protocol built on Sui

---

📋 Table of Contents

• What is Walrus?
• Features
• Installation
• Quick Start
• API Reference
• Examples
• Use Cases
• Future Roadmap
• Development
• About Walrus
• Disclaimer
• License

🌊 What is Walrus?

Walrus is a decentralized storage and data availability protocol designed specifically for large binary files ("blobs"). Built on the Sui blockchain, Walrus provides:

• 🛡️ Robust, affordable storage for unstructured content
• 🔄 High availability even in the presence of Byzantine faults
• ⛓️ Integration with the Sui blockchain for coordination, attestation, and payments
• 🔒 Client-side encryption for storing sensitive data

✨ Features

🗃️ Core Storage Operations Store data from multiple sources (byte arrays, files, streams, URLs) Retrieve data in multiple formats Get metadata without downloading content	🔐 Advanced Encryption AES-256-GCM encryption (recommended, provides authentication) AES-256-CBC encryption (with custom IV support) Stream-based encryption and decryption
📂 File & Stream Handling Upload files directly from disk Download blobs to files Stream-based uploads and downloads	⚠️ Error Handling Detailed error types Automatic retries with configurable policy Comprehensive error reporting
⚙️ Customization Custom endpoints for aggregators and publishers Configurable retry mechanisms Upload size limits and more

📦 Installation

Install the SDK using your favorite package manager:

# Using Bun (recommended)
bun add walrus-ts

# Using npm
npm install walrus-ts

# Using yarn
yarn add walrus-ts

# Using pnpm
pnpm add walrus-ts

🚀 Quick Start

import { createWalrusClient } from 'walrus-ts';

// Create client with default testnet endpoints
const client = createWalrusClient();

// Store data
const data = new TextEncoder().encode('Hello, Walrus!');
const response = await client.store(data, { epochs: 10 });

console.log(`Data stored with blob ID: ${response.blob.blobId}`);

// Retrieve data
const retrievedData = await client.read(response.blob.blobId);
console.log(`Retrieved: ${new TextDecoder().decode(retrievedData)}`);

📖 API Reference

Client Creation

import { createWalrusClient } from 'walrus-ts';

// With default options
const client = createWalrusClient();

// With custom options
const client = createWalrusClient({
  aggregatorURLs: ['https://custom-aggregator.example.com'],
  publisherURLs: ['https://custom-publisher.example.com'],
  maxRetries: 3,
  retryDelay: 1000, // ms
  maxUnknownLengthUploadSize: 10 * 1024 * 1024, // 10MB
});

Core Methods

Method	Description
store(data, options)	Store data (Uint8Array)
storeFromStream(stream, options)	Store data from a ReadableStream
storeFromURL(url, options)	Store content from a URL
storeFile(path, options)	Store a file from disk
storeJSON(data, options)	Store JSON data with proper serialization
read(blobId, options)	Read data as Uint8Array
readJSON(blobId, options)	Read and parse JSON data
readToFile(blobId, path, options)	Save blob to a file
readToStream(blobId, options)	Get blob as ReadableStream
head(blobId)	Get blob metadata
getAPISpec(isAggregator)	Get API specification

Encryption

// Generate a random encryption key
const key = crypto.getRandomValues(new Uint8Array(32)); // AES-256

// Store with GCM encryption (recommended)
const response = await client.store(data, {
  epochs: 10,
  encryption: {
    key,
    suite: CipherSuite.AES256GCM,
  }
});

// Retrieve and decrypt data
const decrypted = await client.read(response.blob.blobId, {
  encryption: {
    key,
    suite: CipherSuite.AES256GCM,
  }
});

📚 Examples

The SDK includes several example scripts demonstrating various features:

# Run examples using the provided scripts
bun run example:basic      # Basic storage operations
bun run example:encrypted  # Data encryption/decryption
bun run example:file       # File and stream operations
bun run example:url        # Working with remote URLs
bun run example:client     # Custom client configuration
bun run example:error      # Error handling techniques
bun run example:json       # JSON data operations
bun run example:logging    # Logging configuration

Working with JSON Data

import { createWalrusClient } from 'walrus-ts';

// Create client
const client = createWalrusClient();

// Store JSON data
const jsonData = {
  name: "Walrus Protocol",
  description: "Decentralized storage on Sui",
  features: ["Fast", "Secure", "Decentralized"],
  metrics: {
    reliability: 99.9,
    nodes: 42,
    storageCapacity: "1PB",
  }
};

// Store the data
const response = await client.storeJSON(jsonData, { epochs: 10 });
console.log(`JSON data stored with blob ID: ${response.blob.blobId}`);

// Retrieve the data with type safety
interface WalrusConfig {
  name: string;
  features: string[];
  metrics: {
    reliability: number;
    nodes: number;
    storageCapacity: string;
  };
}

// Retrieve with type checking
const typedData = await client.readJSON<WalrusConfig>(response.blob.blobId);
console.log(`Name: ${typedData.name}`);
console.log(`Features: ${typedData.features.join(", ")}`);
console.log(`Reliability: ${typedData.metrics.reliability}%`);

// Store sensitive data with encryption
const key = crypto.getRandomValues(new Uint8Array(32));
const encryptedResponse = await client.storeJSON(
  { apiKey: "secret-key-12345", accessToken: "sensitive-token" },
  {
    epochs: 5,
    encryption: { key }
  }
);

// Read with decryption
const decryptedData = await client.readJSON(encryptedResponse.blob.blobId, {
  encryption: { key }
});

See the examples directory for more detailed examples and documentation.

🔍 Use Cases

🖼️ NFT and dApp Media Storage Store images, sounds, videos, and other assets for web3 applications	🔒 Encrypted Data Store sensitive information with client-side encryption	🤖 AI Models and Datasets Store model weights, training data, and outputs
📜 Blockchain History Archive historical blockchain data	⚡ Layer 2 Data Availability Certify data availability for L2 solutions	🌐 Decentralized Websites Host complete web experiences including HTML, CSS, JS, and media
🔑 Subscription Models Store encrypted content and manage access via decryption keys

🔮 Future Roadmap

The SDK will continue to evolve with these planned features:

• ⛓️ Sui Blockchain Integration: Verify blob availability and certification on-chain
• 💰 WAL Token Support: Purchase storage and stake tokens directly through the SDK
• 🌐 Walrus Sites: Deploy decentralized websites with simplified workflows

💻 Development

# Clone the repository
git clone https://github.com/soya-miruku/walrus-ts.git
cd walrus-ts

# Install dependencies
bun install

# Build the SDK
bun run build

# Run tests
bun test

ℹ️ About Walrus

Walrus is a decentralized storage protocol with the following key features:

• 📦 Storage and Retrieval: Write and read blobs with high availability
• 💸 Cost Efficiency: Advanced erasure coding keeps storage costs low
• ⛓️ Sui Blockchain Integration: Uses Sui for coordination and payment
• 💰 Tokenomics: WAL token for staking and storage payments
• 🔌 Flexible Access: CLI, SDKs, and HTTP interfaces

⚠️ Disclaimer

The current Testnet release of Walrus is a preview intended to showcase the technology and solicit feedback. All transactions use Testnet WAL and SUI which have no value. The store state can be wiped at any point without warning. Do not rely on the Testnet for production purposes.

All blobs stored in Walrus are public and discoverable by all. Do not use Walrus to store secrets or private data without client-side encryption.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.