SUI Walrus Integration

Decentralized blob storage for NFTs, media, and large files.

Overview

Walrus provides:

• Decentralized blob storage (images, videos, metadata)
• Content-addressable storage (immutable blob IDs)
• High availability through erasure coding
• Integration with SUI Move contracts

Use Cases

• NFT metadata and images
• Game assets and textures
• Document storage
• Media CDN
• DApp static assets

Quick Start

Install Walrus CLI

# Install Walrus CLI
cargo install walrus-cli

# Configure network
walrus config --network testnet

Upload Blob

# Upload file to Walrus
walrus upload myimage.png

# Returns blob ID: bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

Store Blob ID in Move

module nft::metadata {
    use sui::object::{Self, UID};
    use std::string::String;

    public struct NFT has key, store {
        id: UID,
        name: String,
        walrus_blob_id: vector<u8>,  // Store blob ID
    }

    public fun create_nft(
        name: String,
        walrus_blob_id: vector<u8>,
        ctx: &mut TxContext
    ): NFT {
        NFT {
            id: object::new(ctx),
            name,
            walrus_blob_id,
        }
    }

    public fun metadata_url(nft: &NFT): String {
        // Construct Walrus URL
        string::utf8(b"walrus://")
            .append(string::utf8(nft.walrus_blob_id))
    }
}

Frontend Integration

Upload from Browser

import { WalrusClient } from '@walrus-sdk/client';

const client = new WalrusClient({ network: 'testnet' });

async function uploadNFTMetadata(file: File) {
  // Upload to Walrus
  const blobId = await client.upload(file);

  // Store in Move contract
  const tx = new Transaction();
  tx.moveCall({
    target: `${PACKAGE_ID}::nft::create_nft`,
    arguments: [
      tx.pure('My NFT'),
      tx.pure(Array.from(Buffer.from(blobId, 'hex')))
    ]
  });

  return blobId;
}

Retrieve and Display

function NFTImage({ blobId }: { blobId: string }) {
  const url = `https://walrus-testnet.storage/${blobId}`;

  return <img src={url} alt="NFT" />;
}

Best Practices

• Store blob ID (32 bytes) in Move, not full URL
• Upload metadata and images separately
• Use IPFS CID format for compatibility
• Implement retry logic for uploads
• Cache blob IDs for quick access

Common Mistakes

❌ Storing full URL in Move contract

• Problem: URLs change, wastes storage (200+ bytes vs 32 bytes)
• Fix: Store only blob ID, construct URL in frontend

❌ No retry logic on upload failure

• Problem: Network failures break user experience
• Fix: Implement exponential backoff retry (3-5 attempts)

❌ Uploading without checksum verification

• Problem: Silent corruption, blob ID mismatch
• Fix: Verify blob ID matches uploaded content hash

❌ Hardcoding Walrus gateway URLs

• Problem: Gateway changes break all URLs
• Fix: Use environment variables for gateway URLs

❌ Not handling large file uploads

• Problem: Browser memory issues, upload timeout
• Fix: Implement chunked upload for files >10MB

Query latest Walrus docs:

const walrusInfo = await sui_docs_query({
  type: "docs",
  target: "walrus",
  query: "blob upload API and storage patterns"
});

---

Decentralized, permanent storage for your SUI NFTs and dApps!