direct library
Native-only entry point for Dartus direct mode.
Re-exports everything in package:dartus/dartus.dart plus the
client-side encoding and direct storage-node surface that depends on the
Rust FFI native library (dart:ffi). Because dart:ffi is not available
on the web, import this entry point only from native targets
(mobile / desktop / CLI):
import 'package:dartus/direct.dart';
final client = WalrusDirectClient.fromNetwork(
network: WalrusNetwork.testnet,
);
Web and pure-HTTP apps should import package:dartus/dartus.dart, which
stays free of dart:ffi.
Classes
- BlobCache
- LRU cache for blob storage.
- BlobEncoder
- Encodes raw blob data into Walrus slivers and computes metadata.
- BlobFileReader
- A reader that wraps raw blob bytes.
- BlobMetadata
- Metadata computed from encoding a blob, needed for on-chain registration.
- BlobReader
- A reader that lazily fetches blob data from Walrus storage nodes.
- BlobStatus
- Status of a blob on a specific storage node.
- BlobStatusDeletable
- Blob is stored but deletable.
- BlobStatusInvalid
- Blob exists and metadata is invalid.
- BlobStatusNonexistent
- Blob does not exist on this node.
- BlobStatusPermanent
- Blob is permanently stored.
- BlsDartProvider
-
BLS12-381 min_pk provider powered by the
bls_dartFFI package. - BlsProvider
- Interface for BLS12-381 min_pk signature operations.
- CertifyBlobOptions
- Options for certifying a blob on-chain.
- CommitteeInfo
- Summary of the current Walrus storage committee.
- CommitteeResolver
- Resolves the committee from on-chain staking state.
- ConfirmationAggregation
- Result of aggregating individual storage node confirmations into a single certificate for on-chain certification.
- ConstTipStrategy
- Fixed-amount tip strategy. Every upload pays the same tip in MIST.
- DeletableCounts
- Deletable counts sub-structure.
- DirectWriteOptions
- Options for a direct-mode blob write (no upload relay).
- EncodedBlob
- Result of encoding a blob for direct-mode distribution.
- EncodeQuiltResult
- Result of quilt encoding.
- EpochState
- Parsed epoch state with its kind and optional associated value.
- LinearTipStrategy
-
Linear tip strategy:
base + perEncodedKib * ceil(blobSize / 1024). - LocalFileReader
- A local file reader backed by in-memory data.
- ParsedBlobMetadata
-
Parsed blob metadata from a
BlobMetadataWithIdBCS response. - ParsedWalrusId
- Parsed Walrus ID — either a plain blob ID or a quilt patch ID.
- ProtocolMessageCertificate
- A certificate proving a blob has been stored by a quorum of storage nodes.
- QuiltBlob
- A blob to include in a quilt.
- QuiltBlobHeader
- Header information for a blob within a quilt.
- QuiltBlobReadResult
- Result of reading a blob from a quilt.
- QuiltFileReader
- Reads a single file from within a quilt blob.
- QuiltIndex
- Quilt index containing all patch entries.
- QuiltIndexEntry
- Entry in the quilt index for a patch.
- QuiltPatch
- A patch entry in the quilt index.
- QuiltPatchId
- A parsed quilt patch ID.
- QuiltPatchResult
- A single patch entry in a quilt write result, with its computed patch ID.
- QuiltReader
- Reads the structure of a quilt blob and provides access to patches.
- RegisterBlobOptions
- Options for registering a blob on-chain.
- SliverData
- A single encoded sliver for a specific pair index.
- SliverPair
- A pair of primary + secondary slivers assigned to a specific node.
- SliversForNode
- Slivers to be written to a specific storage node.
- StatusEvent
- Status event sub-structure.
- StorageConfirmation
- A storage confirmation from a single node.
- StorageCostInfo
- Storage cost breakdown for a blob.
- StorageNodeClient
- Client for a single Walrus storage node's HTTP API.
- StorageNodeInfo
- Information about a Walrus storage node.
- SuiObjectDataLoader
- A batched, caching Sui object loader.
- SystemStateReader
- Reads Walrus on-chain state from the Sui blockchain.
- TipStrategy
- Strategy for calculating the tip to send to the upload relay operator.
- UploadRelayClient
- Client for interacting with a Walrus Upload Relay.
- UploadRelayConfig
- Configuration for the upload relay client.
- UploadRelayTipConfig
- Configuration for tipping the upload relay operator.
- UploadRelayWriteResult
- Result of a successful upload relay write operation.
- WalrusBlob
- Represents a stored blob on Walrus with lazy content access.
- WalrusBlobEncoder
- Concrete BlobEncoder using Rust FFI for canonical RS2 encoding.
- WalrusBlobFilesFilter
- Filter options for WalrusBlob.files.
- WalrusBlobMetadata
- Metadata returned by WalrusFfiBindings.computeMetadata.
- WalrusClient
- High-level Walrus API client for HTTP publisher/aggregator operations with configurable logging via WalrusLogger.
- WalrusDirectClient
- Wallet-integrated Walrus client.
- WalrusEncodingParams
- Encoding parameters returned by WalrusFfiBindings.encodingParams.
- WalrusFfiBindings
- Dart FFI bindings for the walrus_ffi native library.
- WalrusFfiEncodedBlob
- Full encoding result from WalrusFfiBindings.encodeBlob.
- WalrusFile
- Walrus file abstraction.
- WalrusFileReader
- Interface for reading file data from various sources.
- WalrusLogger
- Configurable logger for the Dartus SDK.
- WalrusLogRecord
- A single log record produced by the SDK.
- WalrusPackageConfig
- Configuration for a Walrus deployment on a specific Sui network.
- WalrusStakingObject
- Staking object fields (id, version, package_id).
- WalrusStakingState
- Staking inner state with committee and shard information.
- WalrusSystemObject
- On-chain system object fields (id, version, package_id, new_package_id).
- WalrusSystemState
- Pricing and committee metadata from the system state inner.
- WalrusTransactionBuilder
- Builds Walrus-specific Sui transactions.
-
WeightedItem<
T> - An item paired with a weight for weightedShuffle.
- WriteBlobFlow
- Multi-step write blob flow for wallet integration.
- WriteBlobFlowRegisterOptions
- Options for WriteBlobFlow.register.
- WriteBlobFlowUploadOptions
- Options for WriteBlobFlow.upload.
- WriteBlobResult
- Result of a complete write blob operation.
- WriteFileResult
- Result for a single file in a WriteFilesFlow.
- WriteFilesFlow
- Multi-step write files flow for wallet integration.
- WriteFilesFlowRegisterOptions
- Options for WriteFilesFlow.register.
- WriteQuiltResult
- Result of a quilt write operation.
Enums
- EpochStateKind
- The epoch state of the Walrus staking system.
- SliverType
- Walrus sliver type — primary or secondary.
- WalrusLogLevel
- Severity levels for SDK log output, ordered from most to least restrictive.
- WalrusNetwork
- Known Walrus network identifiers.
Extensions
- WalrusNetworkConfig on WalrusNetwork
- Extension to resolve WalrusNetwork to its WalrusPackageConfig.
Constants
- kBlobIdentifierSizeBytesLength → const int
- Size of the blob identifier length field (2 bytes, little-endian u16).
- kBlobIdLen → const int
- Length of a Walrus Blob ID in bytes.
- kBytesPerStorageUnit → const int
- Bytes per storage unit for on-chain pricing.
- kDigestLen → const int
- Length of a SHA-256 digest in bytes.
- kEncodingTypeRedStuff → const int
- RedStuff encoding type identifier.
- kEncodingTypeRS2 → const int
- RS2 encoding type identifier used in on-chain registration.
- kHasTagsFlag → const int
- Bitmask: tags present in the patch.
- kMaxBlobIdentifierBytesLength → const int
- Maximum blob identifier length (2^16 - 1 = 65535 bytes).
- kMaxNumSliversForQuiltIndex → const int
- Maximum number of slivers (columns) the quilt index can span.
-
kMaxSymbolSize
→ const Map<
int, int> - Maximum symbol size by encoding type.
- kQuiltIndexPrefixSize → const int
- Total prefix size before the quilt index data.
- kQuiltIndexSizeBytesLength → const int
- Size of the quilt index length field (4 bytes, little-endian u32).
- kQuiltPatchBlobHeaderSize → const int
- Size of a QuiltPatchBlobHeader in BCS: version(1) + length(4) + mask(1).
- kQuiltVersionBytesLength → const int
- Size of the quilt version field (1 byte).
-
kRequiredAlignment
→ const Map<
int, int> - Required symbol alignment by encoding type.
- kTagsSizeBytesLength → const int
- Size of the tags length field (2 bytes, little-endian u16).
- mainnetWalrusPackageConfig → const WalrusPackageConfig
- Mainnet Walrus package configuration.
-
statusLifecycleRank
→ const Map<
String, int> -
Lifecycle rank for blob statuses, used by
getVerifiedBlobStatusto pick the "highest" status when multiple storage nodes disagree. - testnetWalrusPackageConfig → const WalrusPackageConfig
- Testnet Walrus package configuration.
Functions
-
bigIntToBytes32(
BigInt value) → Uint8List - Convert a 32-byte blob ID to a BigInt (u256) for on-chain representation.
-
blobIdFromBytes(
Uint8List blobId) → String - Convert raw 32-byte blob ID to URL-safe base64 (no padding).
-
blobIdFromInt(
BigInt blobId) → String - Convert a BigInt (u256) blob ID to URL-safe base64 (no padding).
-
blobIdFromUrlSafeBase64(
String encoded) → Uint8List - Decode a URL-safe base64 blob ID to 32 bytes.
-
blobIdToInt(
String blobId) → BigInt - Convert a URL-safe base64 blob ID to BigInt (u256).
-
blobIdToUrlSafeBase64(
Uint8List bytes) → String - Encode a 32-byte blob ID as URL-safe base64 (no padding).
-
bytes32ToBigInt(
Uint8List bytes) → BigInt - Convert 32 bytes to BigInt (big-endian).
-
computeBlobId(
{required int encodingType, required int unencodedLength, required Uint8List rootHash}) → Uint8List - Compute the Walrus blob ID from encoding parameters.
-
computeSymbolSize(
{required List< int> blobSizes, required int nColumns, required int nRows, required int maxNumColumnsForQuiltIndex, int encodingType = kEncodingTypeRS2}) → int - Find the minimum symbol size needed to store blobs in a fixed number of columns. Each blob must be stored in consecutive columns exclusively.
-
encodedBlobLength(
int unencodedLength, int nShards, {int encodingType = kEncodingTypeRS2}) → int - Total encoded blob length including metadata overhead.
-
encodedSliverSize(
int unencodedLength, int nShards, {int encodingType = kEncodingTypeRS2}) → int - Total encoded sliver size across all shards.
-
encodeQuilt(
{required List< QuiltBlob> blobs, required int numShards, int encodingType = kEncodingTypeRS2}) → EncodeQuiltResult - Encode multiple blobs into a single quilt.
-
encodeQuiltPatchId(
{required String quiltBlobId, required int version, required int startIndex, required int endIndex}) → String - Encode a quilt patch ID to URL-safe base64.
-
encodeSliverForUpload(
SliverData sliver, SliverType type) → Uint8List -
BCS-encode a SliverData as a
Sliverenum for storage node PUT. -
getMaxFaultyNodes(
int nShards) → int - Maximum number of faulty nodes the protocol tolerates.
-
getSizes(
int blobSize, int numShards, {int encodingType = kEncodingTypeRS2}) → ({int columnSize, int rowSize, int symbolSize}) - Compute the symbol size, row size, and column size for a blob.
-
getSourceSymbols(
int nShards, {int encodingType = kEncodingTypeRS2}) → ({int primary, int secondary}) - Number of primary and secondary source symbols for a given shard count.
-
isAboveValidity(
int size, int nShards) → bool -
Whether
sizefailures exceed the validity threshold (> f). -
isQuorum(
int size, int nShards) → bool -
Whether
sizenodes form a quorum (> 2f). -
parseBlobMetadataResponse(
Uint8List bcsBytes) → ParsedBlobMetadata -
Parse a BCS-encoded
BlobMetadataWithIdresponse. -
parseQuiltPatchId(
String id) → QuiltPatchId - Parse a quilt patch ID from URL-safe base64.
-
parseSliverResponse(
Uint8List bcsBytes) → SliverData -
Parse a BCS-encoded
Sliverresponse from a storage node GET endpoint. -
parseWalrusId(
String id) → ParsedWalrusId - Parse a Walrus ID from URL-safe base64.
-
retry<
T> (Future< T> fn(), {int count = 3, Duration? delay, Duration? jitter, bool condition(Object error)?}) → Future<T> -
Retries
fnup tocounttimes with configurabledelayandjitter. - Map a secondary sliver index to the shard responsible for it.
-
shuffle<
T> (List< T> list, [Random? rng]) → List<T> - Fisher-Yates shuffle — returns a new list with elements in random order.
-
signersToBitmap(
List< int> signers, int committeeSize) → Uint8List - Convert a list of signer indices to a compact bitmap.
-
sliverPairIndexFromSecondarySliverIndex(
int sliverIndex, int numShards) → int - Convert a secondary sliver index to its sliver pair index.
-
storageUnitsFromSize(
int size) → int - Convert encoded blob size to on-chain storage units (1 MiB each).
-
toPairIndex(
int shardIndex, Uint8List blobIdBytes, int numShards) → int - Inverse of toShardIndex: map a shard index back to a sliver pair index.
-
toShardIndex(
int sliverPairIndex, Uint8List blobIdBytes, int numShards) → int - Map a sliver pair index to the shard index responsible for it.
-
weightedShuffle<
T> (List< WeightedItem< items, [Random? rng]) → List<T> >T> -
Returns the values from
itemsin a random order that respects weights.
Typedefs
-
DirectWriteCallback
= Future<
Map< Function({required String blobObjectId, required CommitteeInfo committee, required bool deletable, required EncodedBlob encodedBlob})int, StorageConfirmation?> > - Callback type for direct-mode sliver writing.
- WalrusLogHandler = void Function(WalrusLogRecord record)
- Callback signature for custom log handlers.
Exceptions / Errors
- AuthenticationError
- 401 Unauthorized.
- BadRequestError
- 400 Bad Request.
- BehindCurrentEpochError
- Thrown when the client detects it is behind the current epoch, e.g. during an epoch change. The client should reset cached state and retry.
- BlobBlockedError
- Thrown when a blob is blocked by a quorum of storage nodes. NOT retryable — the content is legally restricted.
- BlobNotCertifiedError
- Thrown when a blob is not certified or determined to not exist. Retryable because blob certification may still be in progress.
- BlobNotRegisteredError
- 400 Bad Request — blob not yet registered on-chain.
- ConflictError
- 409 Conflict.
- InconsistentBlobError
- Thrown when a blob was determined to be incorrectly encoded. NOT retryable — the blob data itself is invalid.
- InsufficientWalBalanceError
- Thrown when no WAL coin with sufficient balance can be found.
- InternalServerError
- 5xx Internal Server Error.
- 451 Unavailable For Legal Reasons.
- NoBlobMetadataReceivedError
- Thrown when the client could not retrieve blob metadata from any storage node. Retryable because the metadata may appear once the blob is fully registered and propagated.
- NoBlobStatusReceivedError
- Thrown when the client could not retrieve the status of a blob from any storage node.
- NotEnoughBlobConfirmationsError
- Thrown when the client could not collect enough storage confirmations to certify the blob. Retryable because confirmations may still arrive.
- NotEnoughSliversReceivedError
- Thrown when the client could not retrieve enough slivers to reconstruct the blob. Retryable because nodes may come back online.
- NotFoundError
- 404 Not Found.
- NoVerifiedBlobStatusReceivedError
- Thrown when the client could not retrieve a verified blob status for the blob (i.e. no status reached a validity threshold from quorum).
- PermissionDeniedError
- 403 Forbidden.
- RateLimitError
- 429 Too Many Requests.
- RetryableWalrusClientError
- A WalrusClientError subclass that indicates the operation may succeed if retried (e.g. after an epoch change or transient node failure).
- StorageNodeApiError
- A storage node returned an unexpected HTTP status code.
- StorageNodeConnectionError
- Connection-level errors (timeout, DNS, etc.) — no HTTP status code.
- StorageNodeConnectionTimeoutError
- Connection timeout.
- StorageNodeError
- Base exception for storage node interaction failures.
- UnprocessableEntityError
- 422 Unprocessable Entity.
- UserAbortError
- The user explicitly aborted the request.
- WalrusApiError
- An error returned by the Walrus API or encountered during a request.
- WalrusClientError
- Base exception for all Walrus SDK client errors.
- WalrusFfiException
- Exception thrown when a walrus_ffi function call fails.