Site Builder SDK

A TypeScript SDK for building and deploying decentralized websites on Walrus + Sui, with integrated file operations using zenfs.

Features

- 🚀 Site Management: Create, update, and manage decentralized websites
- 📁 File Operations: Advanced file handling with zenfs integration
- 🔧 Type Safety: Full TypeScript support with comprehensive type definitions
- 🧪 Testing: Complete test suite with Node.js test runner
- 🌐 Web Compatible: Works in both Node.js and browser environments

Installation

``bash
npm install @cmdoss/walrus-site-builder
`

Quick Start

`typescript
import { WalrusSiteBuilderSdk } from '@cmdoss/walrus-site-builder'
import { ZenFsFileManager } from '@cmdoss/file-manager'
import { SuiClient } from '@mysten/sui/client'
import { WalrusClient } from '@mysten/walrus'

const suiClient = new SuiClient({ url: 'https://fullnode.example.com' })
const walrusClient = new WalrusClient({ suiClient })
const fileManager = new ZenFsFileManager()

const sdk = new WalrusSiteBuilderSdk({
suiClient,
walrusClient,
fileManager,
signAndExecuteTransaction: async (tx) => {
// Your wallet signing implementation
}
})

// Deploy a site
await sdk.publishSite({
siteDataPath: '/path/to/site',
numEpochs: 100
})
`

File System Integration

This SDK uses zenfs for file operations, providing:

- Cross-platform compatibility: Works in Node.js and browsers
- Memory-efficient: Handles large files without blocking
- Type-safe: Full TypeScript integration
- Feature-rich: Advanced file operations and metadata

Architecture

The SDK follows a modular architecture:

`mermaid
graph TD
A["🚀 WalrusSiteBuilderSdk
Entry Point"] --> B["📋 UpdateWalrusSiteFlow
Deployment Orchestrator"]
B --> C["📊 prepareResources
Compute Diff & Hashes"]
C --> D["📤 writeResources
Upload to Walrus"]
D --> E["✅ certifyResources
Associate Certificates"]
E --> F["⛓️ writeSite
Create Site on Sui"]
A --> G["📁 IFileManager
File Operations"]
G --> H["🌐 Node.js & Browser
Cross-platform"]

style A fill:#4F46E5,stroke:#312E81,color:#fff,stroke-width:3px
style B fill:#7C3AED,stroke:#5B21B6,color:#fff,stroke-width:3px
style C fill:#EC4899,stroke:#BE185D,color:#fff,stroke-width:2px
style D fill:#F97316,stroke:#C2410C,color:#fff,stroke-width:2px
style E fill:#06B6D4,stroke:#0E7490,color:#fff,stroke-width:2px
style F fill:#10B981,stroke:#065F46,color:#fff,stroke-width:2px
style G fill:#8B5CF6,stroke:#6D28D9,color:#fff,stroke-width:3px
style H fill:#6366F1,stroke:#3730A3,color:#fff,stroke-width:2px
`

Key Components:

- WalrusSiteBuilderSdk: Main entry point for site deployment
- UpdateWalrusSiteFlow: Orchestrates the deployment lifecycle
- prepareResources(): Computes file diff and generates hashes
- writeResources(): Uploads blobs to Walrus storage
- certifyResources(): Associates certificates with on-chain data
- writeSite()`: Creates/updates Site object on Sui blockchain
- IFileManager: Abstraction for file operations (supports both Node.js and browser)

For more details, see AGENTS.md in the root repository.

Examples

See the playground app for comprehensive examples showcasing:

- Site creation and deployment
- File management
- Wallet integration
- Resource management
- Site updates and publishing

Refer to the package source in src/ for detailed API documentation.

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

License

MIT

Acknowledgments

- Built on Sui blockchain infrastructure
- Uses Walrus for decentralized storage
- File operations powered by zenfs
- Inspired by the original Rust implementation