TECHNICAL DESIGN DOCUMENT

Walrus Starter Kit

Interactive CLI for scaffolding Walrus applications on Sui blockchain

Version 0.1.5 • Production Ready • Enoki Beta Integration

Read Documentation arrow_forward Try Interactive Builder

description Executive Summary

Walrus Starter Kit is a production-grade interactive CLI tool designed to simplify the development of applications on the Walrus Protocol (Sui blockchain). It provides a preset-based scaffolding system with pre-built, validated templates for rapid application development.

The CLI offers multiple SDKs, frameworks, and use cases with full TypeScript support and automated post-install workflows. Think of it as the "create-next-app" experience for the Walrus ecosystem.

3
Production Presets
97.5%
Test Coverage
100%
TS Compilation

visibility Product Vision

interactive Interactive Wizard

Multi-step CLI flow with intelligent defaults and skip flags for CI/CD automation

inventory Preset Architecture

Pre-built, validated template combinations for zero-error reliability

sdk Multi-SDK Support

Mysten (stable), Enoki (beta), Hibernuts (planned)

verified_user zkLogin Ready

Enoki integration for social authentication (Google OAuth)

trending_up Success Metrics

Metric Target Current Status
Preset Success Rate 100% 100% ✓ ACHIEVED
TS Compilation 100% 100% ✓ ACHIEVED
Test Coverage >95% 97.5% ✓ ACHIEVED
Post-Install Success >95% ~98% ✓ ACHIEVED
CLI Exec Time <3s <2s ✓ ACHIEVED

grid_view Compatibility Matrix

Current presets and planned combinations:

SDK Framework Use Case Status
@mysten/walrus React Simple Upload STABLE
@mysten/walrus React Gallery STABLE
@mysten/enoki React Simple Upload BETA
@mysten/walrus Vue All PLANNED
@hibernuts/walrus-sdk React, Plain TS Simple Upload PLANNED

architecture Preset Architecture

The project uses pre-built, validated template combinations for zero-error guarantees:

account_tree Monorepo Structure Diagram 

graph TD
    Root[walrus-starter-kit/]
    Root --> CLI[packages/cli/]
    Root --> Templates[templates/]
    Root --> Docs[docs/]
    Root --> Examples[examples/]

    CLI --> Src[src/]
    CLI --> Presets[presets/]
    CLI --> Scripts[scripts/]

    Presets --> P1[react-mysten-simple-upload/]
    Presets --> P2[react-mysten-gallery/]
    Presets --> P3[react-mysten-simple-upload-enoki/]

    Templates -.-> Base[base/]
    Templates -.-> SDK[sdk-mysten/]
    Templates -.-> Enoki[enoki/]
    Templates -.-> React[react/]
    Templates -.-> Upload[simple-upload/]
    Templates -.-> Gallery[gallery/]

    style Root fill:#0891b2,stroke:#06b6d4,color:#fff
    style CLI fill:#a855f7,stroke:#c084fc,color:#fff
    style Presets fill:#d8b4fe,stroke:#c084fc,color:#000
    style P1 fill:#22c55e,stroke:#4ade80,color:#000
    style P2 fill:#22c55e,stroke:#4ade80,color:#000
    style P3 fill:#eab308,stroke:#facc15,color:#000
    style Templates fill:#64748b,stroke:#94a3b8,color:#fff,stroke-dasharray: 5 5
Note: templates/ directory maintained for reference only. All scaffolding uses presets/

✓ Preset Benefits

  • • Zero runtime errors
  • • Pre-validated templates
  • • Automated testing
  • • Fast scaffolding (<2s)

⚙️ Generation Process

  • 1. Matrix lookup → Preset selection
  • 2. Copy preset directory
  • 3. Transform variables
  • 4. Auto-copy .env.example → .env
  • 5. Install deps & validate TS

account_tree CLI Pipeline

Streamlined preset-based scaffolding flow:

Pipeline Flow Diagram

flowchart TD
    Start([User runs create-walrus-app]) --> Entry[Entry Point index.ts]
    Entry --> Parse[Parse Arguments commander]
    Parse --> Check{CLI flags provided?}
    Check -->|No| Prompts[Interactive Prompts prompts.ts]
    Check -->|Yes| Context
    Prompts --> Context[Build Context context.ts]
    Context --> Validate[Validate Compatibility matrix.ts]
    Validate --> Valid{Valid preset exists?}
    Valid -->|No| Error1[Error: Invalid combination]
    Valid -->|Yes| Generate[Generate Project generator]
    Generate --> Copy[Copy Preset Directory]
    Copy --> Transform[Transform Variables]
    Transform --> Env[Auto-copy env example]
    Env --> Install{Skip install flag?}
    Install -->|No| PM[Install Dependencies package-manager.ts]
    Install -->|Yes| Skip1[Skip to validation]
    PM --> Verify{Skip validation flag?}
    Skip1 --> Verify
    Verify -->|No| TSCheck[TypeScript Validation validator.ts]
    Verify -->|Yes| Success
    TSCheck --> TSValid{TS compiles?}
    TSValid -->|No| Error2[Show errors and recovery steps]
    TSValid -->|Yes| Success[Success Message Next steps UI]
    Success --> End([Project Ready])
    Error1 --> End
    Error2 --> End

Core Components

Component File Purpose
Entry Point index.ts Commander setup, SIGINT handling
Prompts prompts.ts Multi-step interactive wizard
Context context.ts Merge args/prompts, runtime validation
Generator generator/index.ts Preset copying & transformation
Post-Install post-install/index.ts Dependencies & validation orchestration

web React Framework Architecture

Modern React 18 with Vite, TanStack Query, and Sui wallet integration:

Provider Composition Hierarchy

graph TB
    App[App Component]
    QueryP[QueryProvider TanStack Query]
    WalletP[WalletProvider dapp-kit]
    EnokiP[EnokiProvider zkLogin Beta]
    QueryClient[QueryClient Instance]
    Network[Sui Network Config]
    Session[SessionStorage Adapter]

    QueryP --> App
    WalletP --> QueryP
    EnokiP --> WalletP

    QueryClient -.-> QueryP
    Network -.-> WalletP
    Session -.-> EnokiP

    QueryP -->|Provides| State[Async State Management]
    WalletP -->|Provides| Wallet[Wallet Connection Account Management]
    EnokiP -->|Provides| Auth[zkLogin Authentication Google OAuth]
Note: EnokiProvider only in enoki preset
query_stats

QueryProvider

  • • TanStack Query client
  • • Async state management
  • • Caching & refetching
  • • 5min staleTime default
account_balance_wallet

WalletProvider

  • • @mysten/dapp-kit wrapper
  • • Network config (testnet/mainnet)
  • • Sui RPC auto-connect
  • • Nested QueryClient
verified_user

EnokiProvider

  • • zkLogin authentication
  • • SessionStorage adapter
  • • Google OAuth integration
  • • Enoki preset only

React App Component Structure

graph TD
    App[App.tsx]
    Layout[Layout Component]
    Header[Header Navbar]
    Upload[Upload Component]
    Gallery[Gallery Component]
    FileCard[FileCard Component]

    subgraph Hooks
        UU[useUpload]
        UD[useDownload]
        UA[useStorageAdapter]
        UW[useCurrentAccount]
    end

    subgraph State
        LS[localStorage blob tracking]
        QC[TanStack Cache downloaded blobs]
    end

    App --> Layout
    Layout --> Header
    Layout --> Upload
    Layout --> Gallery
    Gallery --> FileCard

    Upload --> UU
    Gallery --> UD
    FileCard --> UD

    UU --> UA
    UD --> UA
    UA --> UW

    Upload --> LS
    Gallery --> LS
    UD --> QC

category Technology Stack

terminal CLI Engine

Runtime Node.js 20+ (ESM)
Language TypeScript 5.3+ (strict)
CLI Framework commander ^11.1.0
Prompts prompts ^2.4.2
Testing Vitest (97.5% coverage)

code React Presets

UI Library React 18.2+
Build Tool Vite 5.0+ (HMR)
State TanStack Query 5.17+
Sui Integration @mysten/dapp-kit 0.14+
Walrus SDK @mysten/walrus 0.9.0

extension Storage Adapter Interface

SDK-agnostic interface for Walrus storage operations:

Adapter Class Diagram

classDiagram
    class StorageAdapter {
        <<interface>>
        +upload(file, options) Promise
        +getMetadata(blobId) Promise
        +download(blobId) Promise
        +delete(blobId) Promise
    }

    class UploadOptions {
        +epochs number
        +contentType string
        +signer any
    }

    class BlobMetadata {
        +blobId string
        +size number
        +contentType string
        +uploadedAt Date
    }

    class MystenAdapter {
        -client WalrusClient
        +upload(file, options) Promise
        +getMetadata(blobId) Promise
        +download(blobId) Promise
        +delete(blobId) Promise
    }

    class TuskyAdapter {
        -client TuskyClient
        +upload(file, options) Promise
        +getMetadata(blobId) Promise
        +download(blobId) Promise
        +delete(blobId) Promise
    }

    class useStorageAdapter {
        <<hook>>
        +useStorageAdapter() StorageAdapter
        -injectSigner() void
    }

    StorageAdapter <|.. MystenAdapter
    StorageAdapter <|.. TuskyAdapter
    StorageAdapter ..> UploadOptions
    StorageAdapter ..> BlobMetadata
    MystenAdapter ..> useStorageAdapter
    TuskyAdapter ..> useStorageAdapter

Adapter Benefits

  • check_circle SDK-agnostic: Switch between @mysten/walrus, @tusky, or custom implementations
  • check_circle Type-safe: Full TypeScript support with compile-time guarantees
  • check_circle Testable: Easy to mock for unit tests and local development

integration_instructions SDK Integration

Object-based SDK calls with V1 metadata structure (verified 2026-01-18):

SDK Integration Sequence

sequenceDiagram
    participant App
    participant Hook
    participant Adapter
    participant SDK
    participant Relay
    participant Network

    App->>Hook: upload.mutate file
    Hook->>Adapter: adapter.upload file options
    Adapter->>Adapter: Prepare blob data
    Adapter->>SDK: writeBlobToUploadRelay
    SDK->>Relay: HTTP POST v1 store
    Relay->>Network: Distribute blob chunks
    Network-->>Relay: Storage confirmation
    Relay-->>SDK: Response blobId metadata
    SDK-->>Adapter: Return blobId
    Adapter->>Adapter: Parse V1 metadata
    Adapter-->>Hook: Return blobId string
    Hook->>Hook: Update TanStack cache
    Hook-->>App: Success callback

    Note right of App: React Component
    Note right of Hook: useUpload Hook
    Note right of Adapter: StorageAdapter
    Note right of SDK: @mysten/walrus
    Note right of Relay: Upload Relay
    Note right of Network: Walrus Network
sdk-mysten/src/adapter.ts 
// Upload with object params
await client.writeBlobToUploadRelay({
  blob,
  nEpochs,
  signer
});

// Download with object params
await client.readBlob({ blobId });

// Metadata with V1 structure
const response = await client.getBlobMetadata({ blobId });
const size = response.metadata.V1.unencoded_length;
check

@mysten/walrus

Official Mysten Labs SDK with full testnet/mainnet support

STABLE
schedule

@tusky

Community SDK with enhanced features

PLANNED
schedule

@hibernuts

Alternative implementation

PLANNED

hooks React Hooks API

TanStack Query-powered hooks with wallet integration:

Data Flow: Upload & Download

flowchart LR
    subgraph UploadFlow[Upload Flow]
        U1[User selects file] --> U2[useUpload hook]
        U2 --> U3[useStorageAdapter]
        U3 --> U4{Wallet connected?}
        U4 -->|No| U5[Error: Connect wallet]
        U4 -->|Yes| U6[Inject signer]
        U6 --> U7[StorageAdapter upload]
        U7 --> U8[SDK writeBlobToUploadRelay]
        U8 --> U9[Walrus Network]
        U9 --> U10[Return blobId]
        U10 --> U11[Save to localStorage]
        U11 --> U12[Update UI]
    end

    subgraph DownloadFlow[Download Flow]
        D1[User clicks download] --> D2[useDownload hook]
        D2 --> D3[Check TanStack cache]
        D3 -->|Cached| D4[Return cached data]
        D3 -->|Not cached| D5[StorageAdapter download]
        D5 --> D6[SDK readBlob]
        D6 --> D7[Walrus Network]
        D7 --> D8[Return Uint8Array]
        D8 --> D9[Cache for 5min]
        D9 --> D10[Render in UI]
    end

useUpload

Upload mutation (requires wallet connection)

const upload = useUpload();
upload.mutate({
  file: File,
  options?: UploadOptions
});

useDownload

Download query (no wallet required)

const { data: blob } = useDownload(blobId);

// Auto-caches for 5 minutes

Signer Injection Pattern

// HOC hook wraps adapter with wallet signer
export function useStorageAdapter() {
  const currentAccount = useCurrentAccount(); // From @mysten/dapp-kit

  return useMemo(() => ({
    upload: (file, options) =>
      storageAdapter.upload(file, {
        ...options,
        signer: currentAccount
      })
  }), [currentAccount]);
}

verified_user Enoki zkLogin Integration

info

Beta Status

Scaffolding complete, authentication logic implementation pending

Dual-Auth Flow Diagram

sequenceDiagram
    participant U
    participant App
    participant Enoki
    participant Google
    participant Wallet
    participant Walrus

    alt zkLogin Authentication
        U->>App: Login with Google
        App->>Enoki: initiate zkLogin
        Enoki->>Google: OAuth redirect
        Google->>U: Consent screen
        U->>Google: Approve
        Google->>Enoki: OAuth callback
        Enoki->>Enoki: Generate zkProof
        Enoki->>App: zkLogin session
        App->>Walrus: Upload with zkSigner
    else Standard Wallet Auth
        U->>App: Connect Wallet
        App->>Wallet: Request connection
        Wallet->>U: Approve transaction
        U->>Wallet: Sign
        Wallet->>App: Connected account
        App->>Walrus: Upload with wallet signer
    end

    Note right of U: User
    Note right of App: React App
    Note right of Enoki: EnokiProvider
    Note right of Google: Google OAuth
    Note right of Wallet: Sui Wallet
    Note right of Walrus: Walrus Network

✓ Completed

  • ✓ Folder structure & config
  • ✓ Documentation (setup guides)
  • ✓ Google OAuth integration guide
  • ✓ SessionStorage adapter setup

⏳ Pending

  • ⏳ Constants & Zod validation
  • ⏳ EnokiProvider implementation
  • ⏳ Auth flow implementation
  • ⏳ CLI matrix integration & testing

Features

• zkLogin via Google OAuth

Social authentication without Web3 wallets

• Dual-Auth Flow

zkLogin + standard wallet support

• SessionStorage Adapter

Secure browser-based auth state

• Walrus Sites Deployment

Production deployment guides

security Security Measures

shield Input Validation

  • • Path traversal prevention (.., /, \)
  • • Absolute path rejection
  • • NPM naming rules enforcement
  • • 214-character limit (npm limit)

verified Code Safety

  • • TypeScript strict mode
  • • Command injection hardening
  • • Path security validation
  • • Atomic rollback on errors

map Future Roadmap

Development Timeline

gantt
    title Walrus Starter Kit Roadmap
    dateFormat YYYY-MM-DD
    section Completed
    CLI Foundation          :done, p1, 2024-11-01, 2024-11-15
    React Presets (Mysten)  :done, p2, 2024-11-16, 2024-12-01
    Testing & Validation    :done, p3, 2024-12-02, 2024-12-15
    Enoki Scaffolding       :done, p4, 2024-12-16, 2025-01-18
    section In Progress
    Enoki Auth Logic        :active, p5, 2025-01-19, 2025-02-15
    section Planned
    Walrus Sites Deploy     :p11, 2025-02-16, 2025-03-15
    Vue.js Templates        :p12, 2025-03-16, 2025-04-15
    Tusky SDK               :p13a, 2025-04-16, 2025-05-15
    Hibernuts SDK           :p13b, 2025-05-16, 2025-06-15

Phase 11: Walrus Sites Integration

PLANNED

Automatic build & publish to Walrus Sites, Seal integration for private blobs

Phase 12: Vue.js & Plain TypeScript

PLANNED

Vue 3 framework templates with Composition API, Plain TypeScript templates

Phase 13: Additional SDKs

PLANNED

Tusky SDK integration, Hibernuts SDK integration, DeFi/NFT use cases

Questions or Feedback?

Join our community or report issues on GitHub

Discord GitHub