dartus 0.4.1
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 #
WalrusWriterfor wallet-funded uploads on Flutter web and native: register, upload through a relay, and certify. Supports cost estimates, recipient addresses, and amaxRelayTiplimit.writeFilesandestimateFilesfor storing multiple files as one quilt;WalrusClient.getQuiltPatchreads individual files by patch ID.WalletTransactionSignerandKeypairTransactionSigneradapters. Retained write flows resume completed steps and block resubmission when a transaction's outcome is unknown.- Browser encoding through the bundled
walrus-wasmWeb Worker.createDefaultBlobEncoderselects the web or native encoder. WalrusChainReaderfor system state, Blob objects, transaction results and balances over Sui gRPC-web.WalrusTransactionBuilder.addRegisterBlobfor 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: falsebefore submission. Existing non-deletable blobs remain readable. - Native users must rebuild
libwalrus_ffi; encoding requires the newwalrus_encode_blob_v2symbol. - The deprecated
WalrusTransactionBuilder.registerBlobTransactionthrowsUnsupportedError. UseregisterBlobWithWaloraddRegisterBlob. TipStrategy.calculateTipandUploadRelayTipConfig.calculateTipnow take encoded size.sendUploadRelayTiptakesencodedSize. Tips abovemaxthrow instead of being capped.WalrusClient.publisherBaseUrlis nullable, allowing read-only clients. Uploads without a publisher throwStateError.WalrusNetwork.defaultUploadRelayUrlis non-null.getBlobAsFileStreamingbypasses the byte cache. UsegetBlobAsFilefor 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.dartis now free ofdart:ffiand 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 importpackage:dartus/direct.dart. WalrusClient'shttpClientparameter now takes apackage:httphttp.Clientinstead of adart:ioHttpClient.useSecureConnectionis now a no-op (TLS is handled by the platform).BlobCache.put()now returnsFile?(nullon web) instead ofFile.
Fixed #
- HTTP mode now builds and runs on Flutter Web. Removed two web-blocking
dart:iocrashes:BlobCachefalls back to an in-memory store on web (previouslyUnsupported operation: _Namespace), and the HTTP transport (RequestExecutor,WalrusClient) moved fromdart:ioHttpClienttopackage:http(BrowserClienton web,IOClienton native). - Clarified
RetryableWalrusClientErrordocs: these are thrown only byWalrusDirectClient(direct mode); recover viareset()orretryOnPossibleEpochChange(). HTTP-modeWalrusClientsurfaces failures asWalrusApiError.
0.2.0 - 2026-03-25 #
Added #
Direct Mode Client (WalrusDirectClient)
WalrusDirectClient— wallet-integrated client for direct storage-node interactionWalrusDirectClient.fromNetwork()— create fromWalrusNetwork.testnetor.mainnetpresetreadBlob()— read and decode blobs directly from storage nodesgetBlob()— get aWalrusBlobhandle with.bytes(),.text(),.json(),.files()getFiles()— read files by blob or quilt IDwriteBlob()— full write flow: encode → register → upload → certifywriteFiles()— write multiple files as a quiltwriteQuilt()— write a quilt from rawQuiltBlobentriesgetBlobMetadata()— fetch metadata from storage nodesgetSlivers()— fetch primary slivers from storage nodesgetSecondarySliver()— fetch a specific secondary slivergetVerifiedBlobStatus()— quorum-verified blob statusgetBlobObjectInfo()— read on-chain blob object info (certified epoch, end epoch, etc.)resolveBlobId()— resolve Sui object ID (0x...) to base64 blob ID with certification checkgetOwnedBlobs()— list blob objects owned by a wallet addresslookupBlobObjectId()— find a blob's Sui object ID from its blob IDstorageCost()— calculate WAL storage costsystemState()/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 transactioncertifyBlobTransaction()— build a blob certification transactiondeleteBlobTransaction()— build a blob deletion transactionreadBlobAttributes()/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 quiltsBlobReader— stream blob content from storage nodes
Client-Side Encoding (Rust FFI)
WalrusBlobEncoder— RS2 erasure coding usinglibwalrus_ffi(Rustwalrus-core)WalrusFfiBindings— Dart FFI bindings forwalrus_compute_metadata,walrus_encode_blob,walrus_decode_blob- Removed
fountain_codesdependency — 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 strategiesConstTipStrategy/LinearTipStrategy— tip configuration
Error Hierarchy
- 18+ typed error classes mirroring the TypeScript SDK
RetryableWalrusClientErrorbase class for errors that may resolve afterclient.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 formatcomputeBlobId()— compute blob ID from root hashweightedShuffle()— weighted random shuffle for storage node selectionretry()/retryOnPossibleEpochChange()— retry utilities
Network Configuration
WalrusNetwork.testnet/WalrusNetwork.mainnetenumtestnetWalrusPackageConfig/mainnetWalrusPackageConfigwith pre-configured IDsWalrusPackageConfig— walrus package ID, system/staking/exchange object IDs
Changed #
Logging System
- Breaking: Logging is now silent by default (
WalrusLogLevel.none). Previously defaulted tobasic. SetlogLevel: WalrusLogLevel.infoto restore previous behavior. - Extracted logging into standalone
WalrusLoggerclass — accessible viaclient.logger - Expanded log levels:
none,error,warning,info,basic(alias for info),debug,verbose - Added
WalrusLogHandlercallback for custom log routing (integrate with your own logger) - Added
WalrusLogRecordstructured log records with timestamp, level, message, error, stackTrace - Added
onLogparameter to bothWalrusClientandWalrusDirectClientconstructors - Logs now output to
stderrinstead ofstdout(standard practice for libraries) - Replaced internal debug
print()statements with properdebug-level logging
General
- README rewritten to cover all three operational modes (HTTP, relay, direct)
- Comprehensive error handling documentation added
flutterconstraint 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.0dependencies - Test suite expanded from 8 files to 30 files (473+ tests)
- Added
issue_tracker,documentationURLs andtopicsto pubspec
Removed #
fountain_codesdependency — replaced by Rust FFItest_destroy_zero.dart— debugging script removedbuild_native.sh— relocated tonative/build.sh- Empty
docs/directory - Bare
print('[Dartus DEBUG]...')statements — now routed throughWalrusLogger
Notes #
- Phase 2/3 tests (5 test files) require
flutter testinstead ofdart testdue topackage:sui→dart:uidependency. All 473 tests pass withflutter 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 #
0.1.0 - 2026-01-20 #
Added #
- Initial release with Walrus HTTP API support
- Upload methods:
putBlob,putBlobFromFile,putBlobStreaming(defaultdeletable=true) - Download methods:
getBlob,getBlobByObjectId,getBlobAsFile,getBlobAsFileStreaming - Metadata retrieval:
getBlobMetadatafor 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: falseto create permanent blobs