From 2b0717dc3dcc090f76b01e28ba7be0cea6df5c45 Mon Sep 17 00:00:00 2001
From: Andreas Fackler <afck@users.noreply.github.com>
Date: Thu, 12 Sep 2024 18:16:31 +0200
Subject: [PATCH] Add a section about data blobs. (#131)

* Add a short chapter about data blobs.

* Mention the node service mutation as well.
---
 src/SUMMARY.md              |  1 +
 src/developers/sdk/blobs.md | 30 ++++++++++++++++++++++++++++++
 2 files changed, 31 insertions(+)
 create mode 100644 src/developers/sdk/blobs.md

diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index 5ab9f1bf..7f203a74 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -27,6 +27,7 @@
     - [Deploying the Application](developers/sdk/deploy.md)
     - [Cross-Chain Messages](developers/sdk/messages.md)
     - [Calling other Applications](developers/sdk/composition.md)
+    - [Using Data Blobs](developers/sdk/blobs.md)
     - [Printing Logs from an Application](developers/sdk/logging.md)
     - [Writing Tests](developers/sdk/testing.md)
 
diff --git a/src/developers/sdk/blobs.md b/src/developers/sdk/blobs.md
new file mode 100644
index 00000000..11bb44c2
--- /dev/null
+++ b/src/developers/sdk/blobs.md
@@ -0,0 +1,30 @@
+# Using Data Blobs
+
+Some applications may want to use static assets, like images or other data: e.g.
+the `non-fungible` example application implements NFTs, and each NFT has an
+associated image.
+
+Data blobs are pieces of binary data that, once published on _any_ chain, can be
+used on _all_ chains. What format they are in and what they are used for is
+determined by the application(s) that read(s) them.
+
+You can use the `linera publish-data-blob` command to publish the contents of a
+file, as an operation in a block on one of your chains. This will print the ID
+of the new blob, including its hash. Alternatively, you can run `linera service`
+and use the `publishDataBlob` GraphQL mutation.
+
+Applications can now use `runtime.read_data_blob(blob_hash)` to read the blob.
+This works on any chain, not only the one that published it. The first time your
+client executes a block reading a blob, it will download the blob from the
+validators if it doesn't already have it locally.
+
+In the case of the NFT app, it is only the service, not the contract, that
+actually uses the blob data to display it as an image in the frontend. But we
+still want to make sure that the user has the image locally as soon as they
+receive an NFT, even if they don't view it yet. This can be achieved by calling
+`runtime.assert_data_blob_exists(blob_hash)` in the contract: It will make sure
+the data is available, without actually loading it.
+
+For the complete code please take a look at the [`non-fungible`
+contract](https://github.com/linera-io/linera-protocol/blob/{{#include ../../../.git/modules/linera-protocol/HEAD}}/examples/non-fungible/src/contract.rs)
+and [service](https://github.com/linera-io/linera-protocol/blob/{{#include ../../../.git/modules/linera-protocol/HEAD}}/examples/non-fungible/src/service.rs).