📋 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

📦 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

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

🔮 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.