WalrusDirectClient class

Wallet-integrated Walrus client.

Usage (one-shot upload with upload relay):

final client = WalrusDirectClient(
  network: WalrusNetwork.testnet,
  suiClient: SuiClient(SuiUrls.testnet),
  walrusPackageId: '<package-id>',
  uploadRelay: UploadRelayConfig(
    host: 'https://upload-relay.testnet.walrus.space',
  ),
);

final result = await client.writeBlob(
  blob: rawData,
  metadata: preComputedMetadata,
  epochs: 3,
  signer: myAccount,
  deletable: true,
);

Usage (direct mode, no relay):

final client = WalrusDirectClient(
  network: WalrusNetwork.testnet,
  suiClient: SuiClient(SuiUrls.testnet),
  walrusPackageId: '<package-id>',
  encoder: WalrusBlobEncoder(),
);
client.setCommittee(committeeInfo);

final result = await client.writeBlob(
  blob: rawData,
  epochs: 3,
  signer: myAccount,
  deletable: true,
);

Usage (multi-step flow for dApp wallet):

final flow = client.writeBlobFlow(
  blob: rawData,
  metadata: preComputedMetadata,
);

await flow.encode();
final registerTx = flow.register(...);
// Sign registerTx with dApp wallet
await flow.upload(WriteBlobFlowUploadOptions(digest: txDigest));
final certifyTx = flow.certify();
// Sign certifyTx with dApp wallet
final result = await flow.getBlob();

Constructors

WalrusDirectClient({WalrusNetwork? network, WalrusPackageConfig? packageConfig, String? walrusPackageId, required SuiClient suiClient, UploadRelayConfig? uploadRelayConfig, BlobEncoder? encoder, BlsProvider? blsProvider, WalrusLogLevel logLevel = WalrusLogLevel.none, WalrusLogHandler? onLog})

WalrusDirectClient.fromNetwork({required WalrusNetwork network, String? walrusPackageId, SuiClient? suiClient, UploadRelayConfig? uploadRelay, BlobEncoder? encoder, BlsProvider? blsProvider, WalrusLogLevel logLevel = WalrusLogLevel.none, WalrusLogHandler? onLog})

Convenience constructor using a WalrusNetwork preset.

factory

Properties

blsProvider → BlsProvider?

Optional BLS12-381 provider for signature aggregation.

final

committee → CommitteeInfo?

Get the current committee info (returns null if not yet resolved).

no setter

committeeResolver → CommitteeResolver

Access the committee resolver.

no setter

encoder → BlobEncoder?

Optional blob encoder for computing metadata client-side.

final

hashCode → int

The hash code for this object.

no setter, inherited

logger → WalrusLogger

Logger for this client. Configure WalrusLogger.level or WalrusLogger.onRecord to control output.

final

network → WalrusNetwork?

The target Walrus network.

final

packageConfig → WalrusPackageConfig

On-chain Walrus system config.

final

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

stateReader → SystemStateReader

Access the system state reader for pricing and state queries.

no setter

suiClient → SuiClient

Sui RPC client for reading chain state and executing transactions.

final

uploadRelayConfig → UploadRelayConfig?

Upload relay configuration (if using relay mode).

final

Methods

certifyBlobTransaction(CertifyBlobOptions options) → Future<Transaction>

Build a certify blob transaction.

close() → void

Close cached storage node connections. Call when done with this client.

deleteBlobTransaction({required String blobObjectId}) → Future<Transaction>

Build a delete blob transaction.

encodeQuiltBlobs({required List<QuiltBlob> blobs}) → Future<EncodeQuiltResult>

Encode multiple blobs into a quilt.

exchangeAllForSui({required String walCoinObjectId, required SuiAccount signer, String? exchangeObjectId}) → Future<String>

Exchange all WAL in a coin for SUI tokens.

exchangeAllForWal({required String suiCoinObjectId, required SuiAccount signer, String? exchangeObjectId}) → Future<String>

Exchange all SUI in a coin for WAL tokens.

exchangeForSui({required String walCoinObjectId, required BigInt amountWal, required SuiAccount signer, String? exchangeObjectId}) → Future<String>

Exchange a specific amount of WAL for SUI tokens.

exchangeForWal({required String suiCoinObjectId, required BigInt amountSui, required SuiAccount signer, String? exchangeObjectId}) → Future<String>

Exchange a specific amount of SUI for WAL tokens.

executeCertifyBlobTransaction({required String blobId, required String blobObjectId, required bool deletable, ProtocolMessageCertificate? certificate, required SuiAccount signer, int? committeeSize}) → Future<String>

Execute a transaction that certifies a blob on-chain.

executeCreateStorageTransaction({required int size, required int epochs, required SuiAccount signer, String? walCoinObjectId, String? owner}) → Future<({String digest, String storageObjectId})>

Execute a transaction that creates a storage reservation.

executeDeleteBlobTransaction({required String blobObjectId, required SuiAccount signer}) → Future<String>

Execute a transaction that deletes a deletable blob.

executeExtendBlobTransaction({required String blobObjectId, required int epochs, required SuiAccount signer, String? walCoinObjectId}) → Future<String>

Execute a transaction that extends a blob's validity period.

executeRegisterBlobTransaction({required int size, required int epochs, required String blobId, required Uint8List rootHash, required bool deletable, required SuiAccount signer, String? owner, String? walCoinObjectId, Map<String, String?>? attributes}) → Future<({String blobObjectId, String digest})>

Execute a transaction that registers a blob on-chain.

executeWriteBlobAttributesTransaction({required String blobObjectId, required Map<String, String?> attributes, required SuiAccount signer}) → Future<String>

Execute a transaction that writes attributes to a blob.

extendBlobTransaction({required String blobObjectId, required int epochs, String? walCoinObjectId, BigInt? extensionCost}) → Future<Transaction>

Build an extend blob transaction.

findWalCoin(String ownerAddress, BigInt requiredAmount, {bool merge = false}) → Future<String?>

Find a WAL coin with sufficient balance for the given amount.

getBlob({required String blobId}) → Future<WalrusBlob>

Get a WalrusBlob by blob ID for lazy reading.

getBlobIdFromObjectId({required String objectId}) → Future<String?>

Look up the base64 blob ID for a Sui Blob object given its object ID.

getBlobMetadata({required String blobId, int concurrencyLimit = 3}) → Future<Uint8List>

Get blob metadata from storage nodes.

getBlobObjectInfo({required String objectId}) → Future<Map<String, dynamic>?>

Read full on-chain info for a Walrus Blob object.

getBlobType() → Future<String>

Get the Sui Move type for Walrus Blob objects.

getCommittee() → Future<CommitteeInfo>

Get the current committee info, auto-resolving from chain if needed.

getFiles({required List<String> ids}) → Future<List<WalrusFile>>

Get WalrusFile instances for a list of blob IDs or quilt patch IDs.

getOwnedBlobs({required String owner, int limit = 50}) → Future<List<Map<String, dynamic>>>

Query all Walrus Blob objects owned by owner.

getSecondarySliver({required String blobId, required int sliverIndex}) → Future<Uint8List>

Read a single secondary sliver for a blob from the appropriate node.

getSlivers({required String blobId}) → Future<List<SliverData>>

Read primary slivers from storage nodes for blob reconstruction.

getVerifiedBlobStatus({required String blobId}) → Future<BlobStatus>

Get the verified blob status from multiple storage nodes.

getWalExchangePackageId() → Future<String>

Resolve the WAL exchange package ID from the first exchange object.

getWalType() → Future<String>

Resolve WAL coin type from on-chain staking module.

lookupBlobObjectId({required String blobId, required String owner}) → Future<String?>

Look up the Sui object ID for a blob given its blob ID (base64) and owner address.

mergeWalCoins(String ownerAddress, SuiAccount signer) → Future<String>

Merge all WAL coins for an address into a single coin.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

readBlob({required String blobId}) → Future<Uint8List>

Read a full blob from storage nodes by fetching slivers and decoding.

readBlobAttributes({required String blobObjectId}) → Future<Map<String, String>?>

Read the on-chain attributes (metadata key-value pairs) for a blob.

registerBlobTransaction(RegisterBlobOptions options, {required String walCoinObjectId, required BigInt storageCost, required BigInt writeCost}) → Future<Transaction>

Build a register blob transaction with proper WAL payment.

reset() → void

Clear all cached values. Call after epoch changes.

resolveBlobId(String id) → Future<String>

Resolve an input that may be either a base64 blob ID or a Sui object ID (0x...) into a base64 blob ID.

retryOnPossibleEpochChange<T>(Future<T> fn()) → Future<T>

Retry a function once if it throws RetryableWalrusClientError.

setCommittee(CommitteeInfo committee) → void

Set the committee info for direct mode operations.

stakingState() → Future<WalrusStakingState>

Read the staking state (epoch, committee, epoch state).

storageCost(int size, int epochs) → Future<StorageCostInfo>

Calculate storage cost for a blob.

systemState() → Future<WalrusSystemState>

Read current system state (pricing, epoch, shards).

toString() → String

A string representation of this object.

inherited

writeBlob({required Uint8List blob, BlobMetadata? metadata, required int epochs, required SuiAccount signer, required bool deletable, String? owner, String? walCoinObjectId, Map<String, String?>? attributes}) → Future<WriteBlobResult>

Upload a blob in a single call (registers, uploads, certifies).

writeBlobAttributesTransaction({required String blobObjectId, required Map<String, String?> attributes, Transaction? transaction}) → Future<Transaction>

Build a transaction that writes attributes to a blob.

writeBlobFlow({required Uint8List blob, BlobMetadata? metadata}) → Future<WriteBlobFlow>

Create a multi-step write blob flow for dApp wallet integration.

writeEncodedBlobToNodes({required EncodedBlob encodedBlob, required CommitteeInfo committee, required bool deletable, required String blobObjectId, Duration nodeTimeout = const Duration(seconds: 30), int maxConcurrency = 20}) → Future<Map<int, StorageConfirmation?>>

Write encoded slivers to all storage nodes in the committee.

writeFiles({required List<WalrusFile> files, required int epochs, required SuiAccount signer, required bool deletable, String? owner, String? walCoinObjectId, Map<String, String?>? attributes}) → Future<List<WriteFileResult>>

Upload multiple WalrusFiles as a quilt in a single call.

writeFilesFlow({required List<WalrusFile> files}) → Future<WriteFilesFlow>

Create a multi-step write files flow for dApp wallet integration.

writeQuilt({required List<QuiltBlob> blobs, required int epochs, required SuiAccount signer, required bool deletable, String? owner, String? walCoinObjectId, Map<String, String?>? attributes}) → Future<WriteQuiltResult>

Upload a quilt (multi-file blob) in a single call.

Operators

operator ==(Object other) → bool

The equality operator.

inherited