Beluga | EVM to Walrus Bridge

What is Beluga?

Beluga is a lightweight cross-chain data bridge that enables developers to store and retrieve Walrus-backed data through a simple, unified API. It works seamlessly across all EVM chains without requiring any custom smart contract deployments.

Purpose

Beluga bridges the gap between Ethereum-based networks and Walrus decentralized storage by:

• Simplifying Walrus Integration: No need to interact directly with Sui blockchain for storage operations
• Providing On-Chain Metadata: All file metadata (hash, size, MIME type, epochs) is stored on Ethereum contracts
• Enabling Cross-Chain Access: Access your Walrus-stored files from any EVM-compatible chain
• Offering Transparent Pricing: Gas cost estimation before any transaction

Prerequisites

Walrus CLI (Required)

Beluga depends on the Walrus CLI for storage operations. You must install it before using Beluga.

• Walrus Website: https://www.walrus.xyz
• Documentation: https://docs.wal.app
• Getting Started: https://docs.wal.app/usage/started.html

Make sure the walrus command is available in your PATH after installation.

Other Requirements

• Node.js 18+
• Ethereum wallet with testnet ETH (Sepolia)

Installation

npm install -g beluga-cli
npx beluga-cli --version

Commands

Upload

Upload a file to Walrus and register it on Ethereum.

npx beluga-cli upload <file>

Arguments:

• <file> - Path to the file to upload

Process:

1. Prompts for RPC URL (default: Sepolia)
2. Prompts for private key
3. Prompts for number of epochs (storage duration)
4. Calculates file hash (keccak256) and size
5. Detects MIME type from file extension
6. Estimates gas costs and shows summary
7. Asks for confirmation
8. Deploys WalrusGateway contract with metadata
9. Uploads file to Walrus using Walrus CLI
10. Confirms upload on contract with blob ID and Sui Object ID
11. Returns contract address and blob ID

Example:

npx beluga-cli upload ./document.pdf
npx beluga-cli upload ./image.png
npx beluga-cli upload ./video.mp4

Output:

═══════════════════════════════════════════════════
🎉 UPLOAD SUCCESSFUL!
═══════════════════════════════════════════════════
📋 Contract Address: 0x1234...abcd
🔗 Blob ID: abc123def456...
🆔 Sui Object ID: 0x789...
🌐 Explorer: https://walruscan.com/testnet/blob/abc123def456...
═══════════════════════════════════════════════════

Download

Download a file from Walrus using its contract address.

npx beluga-cli download <contractAddress>

Arguments:

• <contractAddress> - Ethereum contract address

Process:

1. Prompts for RPC URL
2. Reads blob details from contract (blobIdString, blobObjectId)
3. Prompts for output file name
4. Downloads file using Walrus CLI

Example:

npx beluga-cli download 0x1234567890abcdef...

Output:

═══════════════════════════════════════════════════
🎉 DOWNLOAD SUCCESSFUL!
═══════════════════════════════════════════════════
📁 Output File: downloaded_file
🔗 Blob ID: abc123def456...
═══════════════════════════════════════════════════

Extend

Extend the storage duration of a blob.

npx beluga-cli extend <contractAddress> <epochs>

Arguments:

• <contractAddress> - Contract address of the blob
• <epochs> - Number of epochs to extend

Process:

1. Prompts for RPC URL and private key
2. Reads current epoch from contract
3. Estimates gas costs for updateEpoch transaction
4. Asks for confirmation
5. Calls updateEpoch on contract (emits BlobExtended event)
6. Executes Walrus CLI extend command

Example:

npx beluga-cli extend 0x1234567890abcdef... 5

Output:

═══════════════════════════════════════════════════
🎉 EXTENSION SUCCESSFUL!
═══════════════════════════════════════════════════
🔗 Blob ID: abc123def456...
🆔 Sui Object ID: 0x789...
⏱️  Old Epoch: 10
⏱️  New Epoch: 15
⏱️  Epochs Extended: 5
═══════════════════════════════════════════════════

Delete

Mark a blob for deletion.

npx beluga-cli delete <contractAddress>

Arguments:

• <contractAddress> - Contract address of the blob

Process:

1. Reads blob details from contract
2. Emits DeleteRequest event on contract
3. Marks blob as deleted

Example:

npx beluga-cli delete 0x1234567890abcdef...

License

MIT