feat: attach SHA-256 checksum as a blob attribute on store

crates/walrus-e2e-tests/tests/test_client.rs

@@ -170,7 +170,7 @@ where
 
     let store_result = client
         .as_ref()
-        .reserve_and_store_blobs_retry_committees_with_path(blobs_with_paths, &store_args)
+        .reserve_and_store_blobs_retry_committees_with_path(blobs_with_paths, vec![], &store_args)
         .await?;
 
     // Wait for the tail uploads to complete.
@@ -770,7 +770,11 @@ pub async fn test_store_and_read_duplicate_blobs() -> TestResult {
 
     let store_args = StoreArgs::default_with_epochs(1).no_store_optimizations();
     let store_result_with_path = client
-        .reserve_and_store_blobs_retry_committees_with_path(blobs_with_paths.clone(), &store_args)
+        .reserve_and_store_blobs_retry_committees_with_path(
+            blobs_with_paths.clone(),
+            vec![],
+            &store_args,
+        )
         .await?;
 
     let read_result =

crates/walrus-sdk/src/node_client.rs

@@ -3000,10 +3000,15 @@ pub trait StoreBlobsApi: internal::StoreBlobApiInternal + Sized {
     /// Stores a list of blobs to Walrus, retrying if it fails because of epoch change.
     /// Similar to `[Client::reserve_and_store_blobs_retry_committees]`, except the result
     /// includes the corresponding path for blob.
+    ///
+    /// The `attributes` vector must be either empty or have the same length as
+    /// `blobs_with_paths`. If it is empty, a default (empty) attribute will be used for each
+    /// blob.
     #[tracing::instrument(skip_all, fields(blob_id))]
     fn reserve_and_store_blobs_retry_committees_with_path(
         &self,
         blobs_with_paths: Vec<(PathBuf, Vec<u8>)>,
+        attributes: Vec<BlobAttribute>,
         store_args: &StoreArgs,
     ) -> impl Future<Output = ClientResult<Vec<BlobStoreResultWithPath>>> + Send {
         async {
@@ -3012,7 +3017,7 @@ pub trait StoreBlobsApi: internal::StoreBlobApiInternal + Sized {
             let walrus_store_blobs =
                 WalrusStoreBlobMaybeFinished::unencoded_blobs_with_default_identifiers(
                     blobs,
-                    vec![],
+                    attributes,
                     self.encoding_config()
                         .await?
                         .get_for_type(store_args.encoding_type),

crates/walrus-service/src/client/cli/args.rs

@@ -1242,6 +1242,15 @@ pub struct CommonStoreOptions {
     #[arg(long)]
     #[serde(default)]
     pub share: bool,
+    /// Compute the SHA-256 checksum of each blob and attach it to the blob object as a
+    /// `sha256` attribute.
+    ///
+    /// The checksum is computed over the raw, unencoded blob bytes and stored on-chain as a
+    /// lowercase hex string, so it can be used to match externally-known file checksums to
+    /// blobs stored on Walrus.
+    #[arg(long)]
+    #[serde(default)]
+    pub attach_sha256_checksum: bool,
     /// The encoding type to use for encoding the files.
     #[arg(long, hide = true)]
     #[serde(default)]
@@ -2011,6 +2020,7 @@ mod tests {
                 deletable: false,
                 permanent: false,
                 share: false,
+                attach_sha256_checksum: false,
                 encoding_type: Default::default(),
                 upload_relay: None,
                 skip_tip_confirmation: false,

crates/walrus-service/src/client/cli/runner.rs

@@ -14,7 +14,10 @@ use std::{
 
 use anyhow::{Context, Result};
 use chrono::{DateTime, Utc};
-use fastcrypto::encoding::Encoding;
+use fastcrypto::{
+    encoding::Encoding,
+    hash::{HashFunction as _, Sha256},
+};
 use itertools::Itertools as _;
 use rand::seq::SliceRandom;
 use reqwest::Url;
@@ -771,6 +774,7 @@ impl ClientCommandRunner {
             store_optimizations,
             persistence,
             post_store,
+            attach_sha256_checksum,
             encoding_type,
             upload_relay,
             confirmation,
@@ -861,6 +865,9 @@ impl ClientCommandRunner {
                 for (path, _) in &blobs {
                     cmd.arg(path);
                 }
+                if attach_sha256_checksum {
+                    cmd.arg("--attach-sha256-checksum");
+                }
             },
             blobs.len(),
         )
@@ -869,6 +876,15 @@ impl ClientCommandRunner {
             return Ok(());
         }
 
+        let attributes = if attach_sha256_checksum {
+            blobs
+                .iter()
+                .map(|(_, blob)| sha256_checksum_attribute(blob))
+                .collect()
+        } else {
+            vec![]
+        };
+
         let base_store_args = StoreArgs::new(
             encoding_type,
             epochs_ahead,
@@ -928,7 +944,7 @@ impl ClientCommandRunner {
 
         let blobs_len = blobs.len();
         let results = client_created_in_bg
-            .reserve_and_store_blobs_retry_committees_with_path(blobs, &store_args)
+            .reserve_and_store_blobs_retry_committees_with_path(blobs, attributes, &store_args)
             .await?;
 
         internal_run_ctx.finalize_after_store(&mut store_args).await;
@@ -1134,6 +1150,7 @@ impl ClientCommandRunner {
             store_optimizations,
             persistence,
             post_store,
+            attach_sha256_checksum,
             encoding_type,
             upload_relay,
             confirmation,
@@ -1150,6 +1167,12 @@ impl ClientCommandRunner {
         if persistence.is_deletable() && post_store == PostStoreAction::Share {
             anyhow::bail!("deletable blobs cannot be shared");
         }
+        if attach_sha256_checksum {
+            anyhow::bail!(
+                "--attach-sha256-checksum is not supported for store-quilt; it only applies to \
+                the `store` command"
+            );
+        }
 
         let encoding_type = encoding_type.unwrap_or(DEFAULT_ENCODING);
         let config = self.config?;
@@ -2218,12 +2241,21 @@ impl ClientCommandRunner {
     }
 }
 
+/// Computes the SHA-256 checksum of `blob` and wraps it in a [`BlobAttribute`] under the
+/// well-known `sha256` key, as a lowercase hex string.
+fn sha256_checksum_attribute(blob: &[u8]) -> BlobAttribute {
+    let digest = Sha256::digest(blob).digest;
+    let checksum = digest.iter().map(|byte| format!("{byte:02x}")).join("");
+    BlobAttribute::from([("sha256".to_string(), checksum)])
+}
+
 struct StoreOptions {
     epoch_arg: EpochArg,
     dry_run: bool,
     store_optimizations: StoreOptimizations,
     persistence: BlobPersistence,
     post_store: PostStoreAction,
+    attach_sha256_checksum: bool,
     encoding_type: Option<EncodingType>,
     upload_relay: Option<Url>,
     confirmation: UserConfirmation,
@@ -2243,6 +2275,7 @@ impl TryFrom<CommonStoreOptions> for StoreOptions {
             deletable,
             permanent,
             share,
+            attach_sha256_checksum,
             encoding_type,
             upload_relay,
             skip_tip_confirmation,
@@ -2259,6 +2292,7 @@ impl TryFrom<CommonStoreOptions> for StoreOptions {
             ),
             persistence: BlobPersistence::from_deletable_and_permanent(deletable, permanent)?,
             post_store: PostStoreAction::from_share(share),
+            attach_sha256_checksum,
             encoding_type,
             upload_relay,
             confirmation: skip_tip_confirmation.into(),
@@ -2513,3 +2547,28 @@ async fn get_latest_checkpoint_sequence_number(
         None
     }
 }
+
+#[cfg(test)]
+mod checksum_tests {
+    use super::sha256_checksum_attribute;
+
+    #[test]
+    fn sha256_checksum_attribute_matches_known_digest() {
+        // echo -n "hello world" | sha256sum
+        let attribute = sha256_checksum_attribute(b"hello world");
+        assert_eq!(
+            attribute.get("sha256"),
+            Some("b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9")
+        );
+    }
+
+    #[test]
+    fn sha256_checksum_attribute_of_empty_blob() {
+        // echo -n "" | sha256sum
+        let attribute = sha256_checksum_attribute(b"");
+        assert_eq!(
+            attribute.get("sha256"),
+            Some("e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855")
+        );
+    }
+}

docs/content/walrus-client/storing-blobs.mdx

@@ -43,6 +43,21 @@ You can specify whether a newly stored blob is deletable or permanent through th
 
 Newly stored blobs are deletable by default.
 
+## Attach a SHA-256 checksum
+
+You can have the client compute the SHA-256 checksum of each blob and attach it to the blob
+object as a `sha256` [blob attribute](/docs/walrus-client/managing-blobs#set-blob-attributes)
+using the `--attach-sha256-checksum` flag:
+
+```sh
+$ walrus store <FILES> --epochs <EPOCHS> --attach-sha256-checksum
+```
+
+The checksum is computed over the raw, unencoded blob bytes and stored onchain as a lowercase
+hex string, so it can be used to match externally known file checksums to blobs stored on
+Walrus. Retrieve it later with `walrus get-blob-attribute <BLOB_OBJECT_ID>`. This flag is only
+supported for the `store` command, not `store-quilt`.
+
 ## Automatic optimizations
 
 When storing a blob, the client performs a number of automatic optimizations, including the following: