Walrus File Upload Tool

A Node.js CLI tool for uploading files to Walrus decentralized storage on Sui blockchain using the Walrus SDK.

Features

• Upload files to Walrus decentralized storage
• Configuration-based keypair management
• Network selection (mainnet, testnet, devnet, localnet)
• CLI init command for easy setup
• Support for various file types with automatic content-type detection
• Built-in error handling and user feedback
• Persistent keypair storage with cross-platform config paths

Installation

# Install dependencies
pnpm install

# Build the project
pnpm build

Quick Start

1. Installation & Build

# Install dependencies
pnpm install

# Build the project
pnpm build

2. Initialize Configuration

# Initialize with testnet (recommended for development)
node dist/cli.js init testnet

# Or with other networks
node dist/cli.js init mainnet
node dist/cli.js init devnet
node dist/cli.js init localnet

3. Upload Files

# Upload a file
node dist/cli.js ./example.txt

# Upload different file types
node dist/cli.js ./document.pdf
node dist/cli.js ./image.png
node dist/cli.js ./data.json

Usage

CLI Commands

# Show help and available commands
node dist/cli.js
node dist/cli.js --help
node dist/cli.js -h

# Initialize configuration with network
node dist/cli.js init <network>

# Check wallet balance
node dist/cli.js balance

# Download file from blobId
node dist/cli.js download <blobId>

# Upload file to Walrus
node dist/cli.js <file-path>

Command Examples

# Initialize with testnet
node dist/cli.js init testnet

# Initialize with mainnet
node dist/cli.js init mainnet

# Check wallet balance
node dist/cli.js balance

# Download file from blobId
node dist/cli.js download VjwvPVHuNeaBOyzNqoYSdYUWlatbMNB8TGyH5IBo6cM

# Upload a text file
node dist/cli.js ./readme.txt

# Upload an image
node dist/cli.js ./photo.png

# Upload a document
node dist/cli.js ./document.pdf

Using npm Scripts

# Initialize configuration
npm run init testnet

# Check wallet balance
npm run balance

# Upload file (main script)
npm start ./example.txt

# Upload with relay (faster, requires relay setup)
npm run upload-relay ./example.txt

Supported Networks

• testnet - Sui testnet (recommended for development)
• mainnet - Sui mainnet (production)
• devnet - Sui devnet (development)
• localnet - Local Sui network

Prerequisites

Important: To upload files to Walrus, you need:

1. SUI tokens - For transaction fees
2. WAL tokens - For storage costs (Walrus native token)

Getting Testnet Tokens

After running init, you'll see your wallet address. Use this address to get tokens:

1. Get SUI tokens from testnet faucet:

   • Visit: https://docs.sui.io/guides/developer/getting-started/get-coins
   • Use the address shown after running init

2. Get WAL tokens:

   • WAL tokens are required for storage costs
   • You may need to acquire them through the Walrus ecosystem or testnet faucets
   • Check Walrus documentation for WAL token faucets

How It Works

1. Configuration: Loads network and keypair settings from platform-specific config directory
2. Client Setup: Creates a Walrus client connected to the configured network
3. Keypair Loading: Loads the configured Ed25519 keypair for signing transactions
4. File Reading: Reads the specified file and converts it to Uint8Array
5. Upload Process:
   • Registers the blob on-chain
   • Uploads data to storage nodes (~2200 requests)
   • Certifies the blob availability
6. Storage: File is stored for configured epochs and marked as deletable

Configuration

The tool uses a configuration file with cross-platform paths. Key settings:

• Network: Configurable (mainnet, testnet, devnet, localnet)
• Keypair: Stored securely in platform-specific config directory
• Storage Duration: 3 epochs (configurable)
• Deletable: true (configurable)
• Content Types: Automatically detected based on file extension

Configuration File Paths

The tool automatically uses the appropriate configuration directory for your operating system:

• Windows: %APPDATA%\my-walrus-tool\config.json
• macOS/Linux: ~/.config/my-walrus-tool/config.json

Configuration File Structure

{
  "network": "testnet",
  "keypair": {
    "secretKey": "suiprivkey1qpxl288m22j4qdyxn60tv4v5nm4jtrztc8ldm95d22m8effq53n5qhpgtuv",
    "address": "0x92adb54ddb6af5317b8ec88e4590af8577875fe82764ab5d02c3bb2a911b766c"
  },
  "walrus": {
    "epochs": 3,
    "deletable": true
  }
}

Configuration Management

• Security: The secretKey is stored in plain text - keep your config file secure
• Backup: Always backup your config file
• Network Switching: Use init <network> to switch networks (creates new keypair)
• Manual Editing: You can manually edit your config file to change settings

File Size Considerations

• Uploads require approximately 2200 requests to storage nodes
• Larger files will take longer to upload
• Consider using upload relays for better performance in production

Network Configuration

WAL Token Package IDs

The tool automatically uses the correct WAL token package ID for each network. If you need to update the package IDs, you can find them in src/config.ts:

const WAL_PACKAGE_IDS = {
  mainnet: "0x8270feb7375eee355e64fdb69c50abb6b5f9393a722883c1cf45f8e26048810a::wal::WAL", // Mainnet WAL package ID
  testnet: "0x0000000000000000000000000000000000000000000000000000000000000000::wal::WAL", // TODO: Update with actual testnet package ID
  devnet: "0x0000000000000000000000000000000000000000000000000000000000000000::wal::WAL", // TODO: Update with actual devnet package ID
  localnet: "0x0000000000000000000000000000000000000000000000000000000000000000::wal::WAL", // TODO: Update with actual localnet package ID
};

⚠️ Important: The placeholder package IDs above need to be updated with the actual package IDs for each network. Currently, only the mainnet package ID is correct.

To find the correct package IDs for your network:

1. Check Walrus Documentation
2. Use Sui Explorer
3. Check network-specific Walrus configuration
4. Contact Walrus team for official package IDs

How to update package IDs:

1. Open src/config.ts
2. Find the WAL_PACKAGE_IDS constant
3. Replace the placeholder 0x0000000000000000000000000000000000000000000000000000000000000000 with the actual package ID for your network
4. Save the file and rebuild: pnpm build

Example:

// Before (placeholder)
testnet: "0x0000000000000000000000000000000000000000000000000000000000000000::wal::WAL",

// After (actual package ID)
testnet: "0x1234567890abcdef1234567890abcdef12345678::wal::WAL",

Error Handling

The tool includes comprehensive error handling for:

• File not found errors
• Network connectivity issues
• Insufficient token balances
• Transaction failures

Development

# Start development server
pnpm start

# Run CLI in development
pnpm cli

# Build for production
pnpm build

Example Output

Initialization

$ node dist/cli.js init testnet
🚀 Initializing Walrus File Upload CLI...
🌐 Network: testnet
✅ Configuration created successfully!
📝 Address: 0x92adb54ddb6af5317b8ec88e4590af8577875fe82764ab5d02c3bb2a911b766c
🌐 Network: testnet
📁 Config file: ~/.config/my-walrus-tool/config.json (macOS/Linux)

Next steps:
1. Get SUI tokens for transaction fees
2. Get WAL tokens for storage costs
3. Run: my-site <file-path> to upload files

Check Balance

$ node dist/cli.js balance
💰 Querying wallet balance...
✅ Balance retrieved successfully!
📝 Address: 0x86293c9a8d7f2d732b5b9d9295576fb558fae7748389bbac65a22ab30822659a
🌐 Network: testnet

💰 Token Balances:
   SUI: 0.500000 SUI
   WAL: 0.500000 WAL

💡 SUI tokens are required for transaction fees
💡 WAL tokens are required for Walrus storage costs

Balance Formatting:

• Both SUI and WAL balances are automatically converted from MIST to human-readable units
• Very small amounts (< 0.000001) are shown in MIST for precision
• Amounts are formatted with appropriate decimal places for clarity
• 1 SUI = 1,000,000,000 MIST
• 1 WAL = 1,000,000,000 MIST

File Upload

$ node dist/cli.js ./example.txt
🚀 Loading configuration...
🚀 Initializing Walrus client...
🔑 Loading keypair from config...
📝 Address: 0x92adb54ddb6af5317b8ec88e4590af8577875fe82764ab5d02c3bb2a911b766c
🌐 Network: testnet
📁 Reading file: ./example.txt
📦 Preparing file for upload...
💾 Uploading file to Walrus...
⏳ This may take a while as it requires ~2200 requests...
📊 File size: 291 bytes
✅ Upload successful!
📋 Results: {
  "blobId": "0x...",
  "blobObject": { ... }
}

🌐 File Access URL:
   https://walrus.mystenlabs.com/blob/0x...

💡 You can use this URL to access your uploaded file
💡 The file is stored on Walrus decentralized storage

🔍 Testing blob access...
✅ Blob access test successful!
📄 File content preview (text): Hello Walrus! This is a test file.
📄 Raw Uint8Array preview: [72, 101, 108, 108, 111, 32, 87, 97, 108, 114, 117, 115, 33, 10]

File Download

$ node dist/cli.js download VjwvPVHuNeaBOyzNqoYSdYUWlatbMNB8TGyH5IBo6cM
🚀 Loading configuration...
🚀 Initializing Walrus client...
🔑 Loading keypair from config...
📝 Address: 0x86293c9a8d7f2d732b5b9d9295576fb558fae7748389bbac65a22ab30822659a
🌐 Network: testnet
📥 Downloading blob: VjwvPVHuNeaBOyzNqoYSdYUWlatbMNB8TGyH5IBo6cM
✅ Download successful!
📊 Blob size: 27 bytes

📄 File content:
──────────────────────────────────────────────────
Testing Walrus URL access!

──────────────────────────────────────────────────

💡 You can save this content to a file if needed

Troubleshooting

"Config file not found" Error

Error: Config file not found. Please run 'my-site init <network>' first.

Solution: Run the initialization command:

node dist/cli.js init testnet

"Not enough WAL tokens" Error

This error occurs when the keypair doesn't have sufficient WAL tokens for storage costs. To resolve:

1. Get WAL tokens from a testnet faucet or exchange
2. Transfer WAL tokens to the address shown in your config
3. Ensure you have enough SUI tokens for transaction fees

"Keypair not configured" Error

Error: Keypair not configured. Please run 'npm run init' to generate a keypair.

Solution: Initialize the configuration:

node dist/cli.js init testnet

Network Issues

If you encounter network issues:

• Check your internet connection
• Verify the configured network is accessible
• Try switching to a different network with init <network>
• Check Sui network status

License

ISC

Contributing

Feel free to submit issues and enhancement requests!