Skip to main content

dartus 0.4.1 copy "dartus: ^0.4.1" to clipboard
dartus: ^0.4.1 copied to clipboard

Dart and Flutter SDK for Walrus blob storage, with publisher uploads, aggregator reads, wallet transaction builders, quilts, and native encoding.

Changelog #

All notable changes to Dartus will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

0.4.1 - 2026-10-18 #

Added #

  • Persist and restore blob and quilt upload checkpoints, including content validation, relay nonces, certificates, and transaction receipts.
  • Recoverable wallet signers with stable request IDs for resuming interrupted transaction submissions.

Fixed #

  • Block replacement transactions while an externally signed request is unresolved.

0.4.0 - 2026-10-18 #

Added #

  • WalrusWriter for wallet-funded uploads on Flutter web and native: register, upload through a relay, and certify. Supports cost estimates, recipient addresses, and a maxRelayTip limit.
  • writeFiles and estimateFiles for storing multiple files as one quilt; WalrusClient.getQuiltPatch reads individual files by patch ID.
  • WalletTransactionSigner and KeypairTransactionSigner adapters. Retained write flows resume completed steps and block resubmission when a transaction's outcome is unknown.
  • Browser encoding through the bundled walrus-wasm Web Worker. createDefaultBlobEncoder selects the web or native encoder.
  • WalrusChainReader for system state, Blob objects, transaction results and balances over Sui gRPC-web.
  • WalrusTransactionBuilder.addRegisterBlob for WAL-funded registration in a larger transaction, and a default mainnet upload relay.

Breaking changes #

  • Requires Dart 3.11 or later and sui ^0.5.1. The default native chain client uses Sui gRPC.
  • Upload APIs reject deletable: false before submission. Existing non-deletable blobs remain readable.
  • Native users must rebuild libwalrus_ffi; encoding requires the new walrus_encode_blob_v2 symbol.
  • The deprecated WalrusTransactionBuilder.registerBlobTransaction throws UnsupportedError. Use registerBlobWithWal or addRegisterBlob.
  • TipStrategy.calculateTip and UploadRelayTipConfig.calculateTip now take encoded size. sendUploadRelayTip takes encodedSize. Tips above max throw instead of being capped.
  • WalrusClient.publisherBaseUrl is nullable, allowing read-only clients. Uploads without a publisher throw StateError.
  • WalrusNetwork.defaultUploadRelayUrl is non-null.
  • getBlobAsFileStreaming bypasses the byte cache. Use getBlobAsFile for cached downloads.

Fixed #

  • Native encoding returns complete metadata, including per-pair Merkle hashes.
  • Direct uploads send the correct secondary sliver indices to storage nodes.
  • Native reads and sliver upload helpers use the storage-node BCS format.
  • Native and keypair transactions support SUI address balances for gas.
  • Direct uploads validate storage confirmations and BLS signatures against the committee. Default storage-node HTTPS connections validate certificates.
  • Wallet flows prevent concurrent submissions and validate registration and certification results before continuing.
  • Relay uploads work on Flutter web and calculate tips from encoded size.
  • Quilt identifiers use the BCS string format expected by aggregators.
  • Object-ID downloads use the aggregator's /v1/blobs/by-object-id/ route.
  • Cache overwrites and concurrent writes preserve complete entries and enforce capacity. Streaming downloads stage writes before replacing the destination, preserve checked permission bits and symlink targets, and handle cleanup errors without masking the result.
  • HTTP response bodies time out when stalled; error diagnostics are bounded.
  • Automatic WAL coin selection follows pagination and handles duplicate coins and invalid continuation cursors.
  • WAL/SUI exchange helpers transfer the returned coin to the signer.
  • Native builds select the current platform's library artifact.

0.3.0 - 2026-06-20 #

Makes Dartus work on Flutter Web in HTTP mode. Contains breaking changes for direct-mode and custom-HTTP-client users (see below).

Changed (breaking) #

  • Web-safe public API split. package:dartus/dartus.dart is now free of dart:ffi and is the web-safe HTTP surface. The direct-mode + Rust FFI surface (WalrusDirectClient, WriteBlobFlow, WriteFilesFlow, WalrusBlobEncoder, WalrusFfiBindings) moved to a new entry point, package:dartus/direct.dart. Direct-mode users must import package:dartus/direct.dart.
  • WalrusClient's httpClient parameter now takes a package:http http.Client instead of a dart:io HttpClient. useSecureConnection is now a no-op (TLS is handled by the platform).
  • BlobCache.put() now returns File? (null on web) instead of File.

Fixed #

  • HTTP mode now builds and runs on Flutter Web. Removed two web-blocking dart:io crashes: BlobCache falls back to an in-memory store on web (previously Unsupported operation: _Namespace), and the HTTP transport (RequestExecutor, WalrusClient) moved from dart:io HttpClient to package:http (BrowserClient on web, IOClient on native).
  • Clarified RetryableWalrusClientError docs: these are thrown only by WalrusDirectClient (direct mode); recover via reset() or retryOnPossibleEpochChange(). HTTP-mode WalrusClient surfaces failures as WalrusApiError.

0.2.0 - 2026-03-25 #

Added #

Direct Mode Client (WalrusDirectClient)

  • WalrusDirectClient — wallet-integrated client for direct storage-node interaction
  • WalrusDirectClient.fromNetwork() — create from WalrusNetwork.testnet or .mainnet preset
  • readBlob() — read and decode blobs directly from storage nodes
  • getBlob() — get a WalrusBlob handle with .bytes(), .text(), .json(), .files()
  • getFiles() — read files by blob or quilt ID
  • writeBlob() — full write flow: encode → register → upload → certify
  • writeFiles() — write multiple files as a quilt
  • writeQuilt() — write a quilt from raw QuiltBlob entries
  • getBlobMetadata() — fetch metadata from storage nodes
  • getSlivers() — fetch primary slivers from storage nodes
  • getSecondarySliver() — fetch a specific secondary sliver
  • getVerifiedBlobStatus() — quorum-verified blob status
  • getBlobObjectInfo() — read on-chain blob object info (certified epoch, end epoch, etc.)
  • resolveBlobId() — resolve Sui object ID (0x...) to base64 blob ID with certification check
  • getOwnedBlobs() — list blob objects owned by a wallet address
  • lookupBlobObjectId() — find a blob's Sui object ID from its blob ID
  • storageCost() — calculate WAL storage cost
  • systemState() / stakingState() — read on-chain protocol state

Step-by-Step Write Flows

  • WriteBlobFlow — encode → register → upload → certify (for dApp wallets)
  • WriteFilesFlow — multi-file quilt write flow

Transaction Builders

  • registerBlobTransaction() — build a blob registration transaction
  • certifyBlobTransaction() — build a blob certification transaction
  • deleteBlobTransaction() — build a blob deletion transaction
  • readBlobAttributes() / writeBlobAttributes() — on-chain metadata attributes

File Abstractions

  • WalrusFile — file with identifier, tags, content; .bytes(), .text(), .json(), .getIdentifier(), .getTags()
  • WalrusBlob — blob handle with .asFile(), .files() (quilt reading), .bytes(), .exists()
  • QuiltReader / QuiltFileReader — read multi-file quilts
  • BlobReader — stream blob content from storage nodes

Client-Side Encoding (Rust FFI)

  • WalrusBlobEncoder — RS2 erasure coding using libwalrus_ffi (Rust walrus-core)
  • WalrusFfiBindings — Dart FFI bindings for walrus_compute_metadata, walrus_encode_blob, walrus_decode_blob
  • Removed fountain_codes dependency — FFI is now required, no pure-Dart fallback

Storage Node Client

  • StorageNodeClient — HTTP client for storage node APIs (sliver read/write, metadata, confirmation)
  • BCS serialization for sliver data and blob metadata

Upload Relay

  • UploadRelayClient — upload via relay server with configurable tip strategies
  • ConstTipStrategy / LinearTipStrategy — tip configuration

Error Hierarchy

  • 18+ typed error classes mirroring the TypeScript SDK
  • RetryableWalrusClientError base class for errors that may resolve after client.reset()
  • Storage-node HTTP errors: BadRequestError, NotFoundError, AuthenticationError, RateLimitError, etc.
  • BlobNotCertifiedError, BehindCurrentEpochError, InconsistentBlobError, InsufficientWalBalanceError

Utilities

  • blobIdFromInt() / blobIdToInt() — blob ID format conversions (verified against TS SDK)
  • encodeQuilt() — encode multiple blobs into quilt format
  • computeBlobId() — compute blob ID from root hash
  • weightedShuffle() — weighted random shuffle for storage node selection
  • retry() / retryOnPossibleEpochChange() — retry utilities

Network Configuration

  • WalrusNetwork.testnet / WalrusNetwork.mainnet enum
  • testnetWalrusPackageConfig / mainnetWalrusPackageConfig with pre-configured IDs
  • WalrusPackageConfig — walrus package ID, system/staking/exchange object IDs

Changed #

Logging System

  • Breaking: Logging is now silent by default (WalrusLogLevel.none). Previously defaulted to basic. Set logLevel: WalrusLogLevel.info to restore previous behavior.
  • Extracted logging into standalone WalrusLogger class — accessible via client.logger
  • Expanded log levels: none, error, warning, info, basic (alias for info), debug, verbose
  • Added WalrusLogHandler callback for custom log routing (integrate with your own logger)
  • Added WalrusLogRecord structured log records with timestamp, level, message, error, stackTrace
  • Added onLog parameter to both WalrusClient and WalrusDirectClient constructors
  • Logs now output to stderr instead of stdout (standard practice for libraries)
  • Replaced internal debug print() statements with proper debug-level logging

General

  • README rewritten to cover all three operational modes (HTTP, relay, direct)
  • Comprehensive error handling documentation added
  • flutter constraint updated to >=3.35.0 (was >=3.0.0)
  • Added sui: ^0.3.7, bls_dart: ^0.1.2, ffi: ^2.1.4, http: ^1.2.0 dependencies
  • Test suite expanded from 8 files to 30 files (473+ tests)
  • Added issue_tracker, documentation URLs and topics to pubspec

Removed #

  • fountain_codes dependency — replaced by Rust FFI
  • test_destroy_zero.dart — debugging script removed
  • build_native.sh — relocated to native/build.sh
  • Empty docs/ directory
  • Bare print('[Dartus DEBUG]...') statements — now routed through WalrusLogger

Notes #

  • Phase 2/3 tests (5 test files) require flutter test instead of dart test due to package:sui → dart:ui dependency. All 473 tests pass with flutter test.

0.1.2 - 2026-03-11 #

Added #

  • Include generated API documentation (doc/api/) in the published package
  • Updated banner with Walrus Foundation logo

0.1.1 - 2026-02-06 #

Added #

  • Documentation: Added "Storage Costs (SUI & WAL)" section explaining the publisher payment model
  • Clarified that Dartus is an HTTP client and does not handle wallet/token operations

Notes #

  • No code changes; documentation-only release

0.1.0 - 2026-01-20 #

Added #

  • Initial release with Walrus HTTP API support
  • Upload methods: putBlob, putBlobFromFile, putBlobStreaming (default deletable=true)
  • Download methods: getBlob, getBlobByObjectId, getBlobAsFile, getBlobAsFileStreaming
  • Metadata retrieval: getBlobMetadata for HEAD requests
  • Disk-based blob cache with LRU eviction and SHA-256 filenames
  • JWT authentication support with instance and per-call tokens
  • Configurable TLS validation via useSecureConnection
  • Built-in logging with levels: none, basic, verbose
  • Flutter demo app with upload and fetch flows
  • Live integration tests against Walrus testnet endpoints

Notes #

  • Blobs are created as deletable by default; pass deletable: false to create permanent blobs
1
likes
160
points
689
downloads

Documentation

API reference

Publisher

unverified uploader

Weekly Downloads

Dart and Flutter SDK for Walrus blob storage, with publisher uploads, aggregator reads, wallet transaction builders, quilts, and native encoding.

Repository (GitHub)
View/report issues
Contributing

Topics

#walrus #storage #blockchain #sui #decentralized

License

MIT (license)

Dependencies

bls_dart, crypto, ffi, http, meta, sui

More

Packages that depend on dartus