From ff366264db38179d4ccd7c1ed83d8371ccc6ef83 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20Sousa=20Andrade?=
 <659718+joaosa@users.noreply.github.com>
Date: Wed, 5 Jun 2024 10:27:26 +0100
Subject: [PATCH] feat: add blob/get (#126)

Adds the `blob/get` capability spec which is analogous to
https://github.com/w3s-project/specs/pull/82

---------

Co-authored-by: Vasco Santos <santos.vasco10@gmail.com>
Co-authored-by: Alan Shaw <alan.shaw@protocol.ai>
---
 w3-blob.md | 113 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 113 insertions(+)

diff --git a/w3-blob.md b/w3-blob.md
index e1c2f07..6de4fec 100644
--- a/w3-blob.md
+++ b/w3-blob.md
@@ -783,6 +783,119 @@ The `out.ok.size` MUST be set to the number of bytes that were freed from the sp
 
 Receipt MUST not have any effects.
 
+## Get Blob
+
+Authorized agent MAY invoke `/space/content/get/blob/0/1` capability on the [space] subject (`sub` field) to get Blobs added to it at the time of invocation.
+
+This may be used to check for inclusion, or to get the `size` of the blob in bytes.
+
+Note: In the future, we will likely deprecate this capability in favor of a suffix-free version that just returns the Blob receipt id.
+
+### Get Blob Invocation Example
+
+Shown Invocation example illustrates Alice getting a blob stored on their space.
+
+> ℹ️ We use `// "/": "bafy..` comments to denote CID of the parent object.
+
+```js
+{ // "/": "bafy..get"
+  "cmd": "/space/content/get/blob/0/1",
+  "sub": "did:key:zAlice",
+  "iss": "did:key:zAlice",
+  "aud": "did:web:web3.storage",
+  "args": {
+    // multihash of the blob as byte array
+    "digest": { "/": { "bytes": "mEi...sfKg" } },
+  }
+}
+```
+
+### Get Blob Receipt Example
+
+Shows an example receipt for the above `/space/content/get/blob/0/1` capability invocation.
+
+```js
+{
+  "iss": "did:web:web3.storage",
+  "aud": "did:key:zAlice",
+  "cmd": "/ucan/assert/result"
+  "sub": "did:web:web3.storage",
+  "args": {
+    // refers to the invocation from the example
+    "ran": { "/": "bafy..get" },
+    "out": {
+      "ok": {
+        // task that caused this invocation
+        "cause": { "/": "bafy..task" }
+        "blob": {
+          "size": 100,
+          "content": { "/": { "bytes": "mEi...sfKg" } },
+        }
+      }
+    },
+    "next": []
+  }
+}
+```
+
+### Get Blob Capability
+
+#### Get Blob Capability Schema
+
+```ts
+type GetBlob = {
+  cmd: "/space/content/get/blob/0/1"
+  sub: SpaceDID
+  args: {
+    digest: Multihash
+  }
+}
+
+type Multihash = bytes
+type SpaceDID = string
+```
+
+##### Get Digest
+
+The `args.digest` field MUST be a [multihash] digest of the blob payload bytes. Implementation SHOULD support SHA2-256 algorithm. Implementation MAY in addition support other hashing algorithms.
+
+### Get Blob Receipt
+
+#### Get Blob Receipt Schema
+
+```ts
+type GetBlobReceipt = {
+  out: Result<GetBlobOk, GetBlobError>
+  next: []
+}
+
+type GetBlobOk = {
+  cause:  Link<Task>
+  blob: Blob
+}
+
+type ISO8601Date = string
+
+type GetBlobError = {
+  message: string
+}
+
+type Blob = {
+  digest: Multihash
+  size: number
+}
+
+type Multihash = bytes
+```
+
+#### Get Cause
+
+The `args.cause` field MUST be set to the [Link] for the task, that caused a get.
+
+##### Get Blob Effects
+
+Receipt MUST NOT have any effects.
+
 # Coordination
 
 ## Publishing Blob