dartus 0.1.0

Dart SDK for Walrus decentralized blob storage with caching, streaming, and authentication.

Dartus

[Walrus SDK banner]

Dartus is a Dart SDK for Walrus decentralized blob storage.

Features

• Upload: putBlob, putBlobFromFile, putBlobStreaming with optional epochs, deletable flag (defaults to true), and SUI object routing
• Download: getBlob, getBlobByObjectId, getBlobAsFile, getBlobAsFileStreaming with automatic caching
• Metadata: getBlobMetadata for HEAD requests returning response headers
• Caching: Disk-based LRU cache with SHA-256 filenames, configurable size limits
• Auth: JWT support via instance-level or per-call tokens
• TLS: Configurable validation (insecure mode for testnet, secure for mainnet)
• Logging: Built-in console logging with none, basic, and verbose levels

Installation

From pub.dev

dependencies:
  dartus: ^0.1.0

From source

dependencies:
  dartus:
    git:
      url: https://github.com/Immadominion/Dartus.git

Then run:

dart pub get  # or flutter pub get

Quick Start

import 'package:dartus/dartus.dart';
import 'dart:io';

void main() async {
  final client = WalrusClient(
    publisherBaseUrl: Uri.parse('https://publisher.walrus-testnet.walrus.space'),
    aggregatorBaseUrl: Uri.parse('https://aggregator.walrus-testnet.walrus.space'),
    useSecureConnection: true, // use TLS for production
  );

  // Upload blob
  final imageBytes = await File('image.png').readAsBytes();
  final response = await client.putBlob(data: imageBytes);
  print('Uploaded: $response');

  // Extract blob ID from response
  final blobId = response['newlyCreated']?['blobObject']?['blobId'] 
      ?? response['alreadyCertified']?['blobId'];

  // Download blob (cached automatically)
  final downloaded = await client.getBlob(blobId);
  print('Downloaded ${downloaded.length} bytes');

  await client.close();
}

Documentation

Generate API documentation locally:

dart doc
dart pub global activate dhttpd
dart pub global run dhttpd --path doc/api

Then open http://localhost:8080 in your browser.

Published packages have API docs automatically generated at pub.dev/documentation/dartus/latest.

API Reference

WalrusClient

WalrusClient({
  required Uri publisherBaseUrl,
  required Uri aggregatorBaseUrl,
  Duration timeout = const Duration(seconds: 30),
  Directory? cacheDirectory,
  int cacheMaxSize = 100,
  bool useSecureConnection = false,
  String? jwtToken,
  HttpClient? httpClient,
  WalrusLogLevel logLevel = WalrusLogLevel.basic,
})

Upload Methods

• putBlob({required Uint8List data, ...}) - Upload in-memory bytes
• putBlobFromFile({required File file, ...}) - Upload from file path
• putBlobStreaming({required File file, ...}) - Stream large file uploads

Download Methods

• getBlob(String blobId) - Download with caching
• getBlobByObjectId(String objectId) - Download without caching
• getBlobAsFile({required String blobId, required File destination}) - Save to file
• getBlobAsFileStreaming({...}) - Stream download with progress
• getBlobMetadata(String blobId) - Fetch headers via HEAD request

Auth Methods

• setJwtToken(String token) - Set instance-level JWT
• clearJwtToken() - Remove instance-level JWT

Logging Methods

• setLogLevel(WalrusLogLevel level) - Control console output
• logInfo(String message), logVerbose(...), logWarning(...), logError(...)

TLS Configuration

Testnet (expired/self-signed certificates):

final client = WalrusClient(
  publisherBaseUrl: Uri.parse('https://publisher.testnet.walrus.com'),
  aggregatorBaseUrl: Uri.parse('https://agg.test.walrus.eosusa.io'),
  useSecureConnection: false, // default
);

Mainnet (valid certificates):

final client = WalrusClient(
  publisherBaseUrl: Uri.parse('https://publisher.walrus.com'),
  aggregatorBaseUrl: Uri.parse('https://aggregator.walrus.com'),
  useSecureConnection: true,
);

Testing

# Run all tests (unit + live integration)
dart test

# Run specific test suite
dart test test/blob_cache_test.dart

# Code analysis
dart analyze

# Format code
dart format .

Flutter Demo

A reference Flutter app lives in example/:

cd example
flutter pub get
flutter run

Features:

• Upload images via picker
• Fetch blobs by ID
• Console logging output

Requirements

• Dart SDK ≥ 3.9.2 or Flutter SDK ≥ 3.35.0
• Publisher and aggregator endpoints for your Walrus deployment
• iOS: ATS exceptions for insecure HTTP (testnet only)

License

MIT License - see LICENSE for details.

Links

• Walrus Documentation
• Issue Tracker
• Changelog