From 204d9bb246c20cac5f6bf9a718fd72d26601bafc Mon Sep 17 00:00:00 2001 From: Joao Andrade Date: Thu, 30 May 2024 12:53:04 +0100 Subject: [PATCH 01/13] feat: add blob/get --- w3-blob.md | 98 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 98 insertions(+) diff --git a/w3-blob.md b/w3-blob.md index e1c2f07..2485419 100644 --- a/w3-blob.md +++ b/w3-blob.md @@ -783,6 +783,104 @@ 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` 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` and `origin` properties for a shard. + +### Get Blob Invocation Example + +Shown Invocation example illustrates Alice getting a blob stored on their space. + +```js +{ + "cmd": "/space/content/get/blob", + "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` capability invocation. + +> ℹ️ We use `// "/": "bafy..` comments to denote CID of the parent object. + +```js +{ // "/": "bafy..get", + "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": { + "blob": { + "size": 100, + "content": { "/": { "bytes": "mEi...sfKg" } }, + } + } + }, + // set of tasks to be scheduled. + "next": [] + } +} +``` + +### Get Blob Capability + +#### Get Blob Capability Schema + +```ts +type GetBlob = { + cmd: "/space/content/get/blob" + 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 + next: [] +} + +type GetBlobOk = { + blob: blob +} + +type ISO8601Date = string + +type GetBlobError = { + message: string +} +``` + +##### Get Blob Effects + +Receipt MUST not have any effects. + # Coordination ## Publishing Blob From c03bb5552b81109ca11627d356fcf35240db6654 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Sousa=20Andrade?= <659718+joaosa@users.noreply.github.com> Date: Thu, 30 May 2024 16:02:46 +0100 Subject: [PATCH 02/13] fix: remove origin property Co-authored-by: Vasco Santos --- w3-blob.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/w3-blob.md b/w3-blob.md index 2485419..aa6f105 100644 --- a/w3-blob.md +++ b/w3-blob.md @@ -787,7 +787,7 @@ Receipt MUST not have any effects. Authorized agent MAY invoke `/space/content/get/blob` 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` and `origin` properties for a shard. +This may be used to check for inclusion, or to get the `size` property for a shard. ### Get Blob Invocation Example From 343c426af10cb6481a01ee8d8c66bdd5f869d4d5 Mon Sep 17 00:00:00 2001 From: Joao Andrade Date: Thu, 30 May 2024 16:48:48 +0100 Subject: [PATCH 03/13] fix: include the cause field --- w3-blob.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/w3-blob.md b/w3-blob.md index aa6f105..6cbeff4 100644 --- a/w3-blob.md +++ b/w3-blob.md @@ -823,6 +823,8 @@ Shows an example receipt for the above `/space/content/get/blob` capability invo "ran": { "/": "bafy..get" }, "out": { "ok": { + // task that caused this invocation + "cause": { "/": "bafy..add" } "blob": { "size": 100, "content": { "/": { "bytes": "mEi...sfKg" } }, @@ -867,6 +869,7 @@ type GetBlobReceipt = { } type GetBlobOk = { + cause: Link blob: blob } @@ -877,6 +880,10 @@ type GetBlobError = { } ``` +#### 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. From 2a95949918be913ffea6b40a3ac8cbabcfb4431d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Sousa=20Andrade?= <659718+joaosa@users.noreply.github.com> Date: Thu, 30 May 2024 16:58:54 +0100 Subject: [PATCH 04/13] fix: address typo Co-authored-by: Alan Shaw --- w3-blob.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/w3-blob.md b/w3-blob.md index 6cbeff4..c5f8374 100644 --- a/w3-blob.md +++ b/w3-blob.md @@ -886,7 +886,7 @@ 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. +Receipt MUST NOT have any effects. # Coordination From eb6c84b783d20300397052c35cecda2c22bb0f8a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Sousa=20Andrade?= <659718+joaosa@users.noreply.github.com> Date: Thu, 30 May 2024 16:59:15 +0100 Subject: [PATCH 05/13] fix: address desc Co-authored-by: Alan Shaw --- w3-blob.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/w3-blob.md b/w3-blob.md index c5f8374..310c924 100644 --- a/w3-blob.md +++ b/w3-blob.md @@ -787,7 +787,7 @@ Receipt MUST not have any effects. Authorized agent MAY invoke `/space/content/get/blob` 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` property for a shard. +This may be used to check for inclusion, or to get the `size` of the blob in bytes. ### Get Blob Invocation Example From 21e142257f56919c57ee28da8f7ccf2d4577016b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Sousa=20Andrade?= <659718+joaosa@users.noreply.github.com> Date: Thu, 30 May 2024 17:00:05 +0100 Subject: [PATCH 06/13] fix: define invocation CID Co-authored-by: Alan Shaw --- w3-blob.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/w3-blob.md b/w3-blob.md index 310c924..f808d2c 100644 --- a/w3-blob.md +++ b/w3-blob.md @@ -793,8 +793,10 @@ This may be used to check for inclusion, or to get the `size` of the blob in byt 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", "sub": "did:key:zAlice", "iss": "did:key:zAlice", From d58f097e1915678c91ef0fe9671f4cbefd445e77 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Sousa=20Andrade?= <659718+joaosa@users.noreply.github.com> Date: Thu, 30 May 2024 17:00:21 +0100 Subject: [PATCH 07/13] fix: remove unneeded invocation CID Co-authored-by: Alan Shaw --- w3-blob.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/w3-blob.md b/w3-blob.md index f808d2c..6e4daab 100644 --- a/w3-blob.md +++ b/w3-blob.md @@ -812,10 +812,9 @@ Shown Invocation example illustrates Alice getting a blob stored on their space. Shows an example receipt for the above `/space/content/get/blob` capability invocation. -> ℹ️ We use `// "/": "bafy..` comments to denote CID of the parent object. ```js -{ // "/": "bafy..get", +{ "iss": "did:web:web3.storage", "aud": "did:key:zAlice", "cmd": "/ucan/assert/result" From 0daf93f09a2aa4e5b5e3498353359a2ffaa78cdc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Sousa=20Andrade?= <659718+joaosa@users.noreply.github.com> Date: Thu, 30 May 2024 17:00:37 +0100 Subject: [PATCH 08/13] fix: remove leftover desc Co-authored-by: Alan Shaw --- w3-blob.md | 1 - 1 file changed, 1 deletion(-) diff --git a/w3-blob.md b/w3-blob.md index 6e4daab..7e408e7 100644 --- a/w3-blob.md +++ b/w3-blob.md @@ -832,7 +832,6 @@ Shows an example receipt for the above `/space/content/get/blob` capability invo } } }, - // set of tasks to be scheduled. "next": [] } } From f9e3951c142d1a117ae48f777adb1b1e371f02e2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Sousa=20Andrade?= <659718+joaosa@users.noreply.github.com> Date: Thu, 30 May 2024 17:00:55 +0100 Subject: [PATCH 09/13] fix: define blob type Co-authored-by: Alan Shaw --- w3-blob.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/w3-blob.md b/w3-blob.md index 7e408e7..1fa7d75 100644 --- a/w3-blob.md +++ b/w3-blob.md @@ -878,6 +878,8 @@ type ISO8601Date = string type GetBlobError = { message: string } + +type Blob = { /* ??? */ } ``` #### Get Cause From aef5e88fa2c8e2fa9098e546710006951aaad661 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Sousa=20Andrade?= <659718+joaosa@users.noreply.github.com> Date: Thu, 30 May 2024 17:01:05 +0100 Subject: [PATCH 10/13] fix: use blob type Co-authored-by: Alan Shaw --- w3-blob.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/w3-blob.md b/w3-blob.md index 1fa7d75..dbcbb0f 100644 --- a/w3-blob.md +++ b/w3-blob.md @@ -870,7 +870,7 @@ type GetBlobReceipt = { type GetBlobOk = { cause: Link - blob: blob + blob: Blob } type ISO8601Date = string From b692239ab5f2cfa867c24ae8f56d53f641fe7ba8 Mon Sep 17 00:00:00 2001 From: Joao Andrade Date: Thu, 30 May 2024 17:02:51 +0100 Subject: [PATCH 11/13] fix: remove whitespace --- w3-blob.md | 1 - 1 file changed, 1 deletion(-) diff --git a/w3-blob.md b/w3-blob.md index dbcbb0f..42cc6cb 100644 --- a/w3-blob.md +++ b/w3-blob.md @@ -812,7 +812,6 @@ Shown Invocation example illustrates Alice getting a blob stored on their space. Shows an example receipt for the above `/space/content/get/blob` capability invocation. - ```js { "iss": "did:web:web3.storage", From 16bef517890297d63fcb84fbd1bb0770891fd4bf Mon Sep 17 00:00:00 2001 From: Joao Andrade Date: Fri, 31 May 2024 17:01:09 +0100 Subject: [PATCH 12/13] fix: suffix blob/get capability --- w3-blob.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/w3-blob.md b/w3-blob.md index 42cc6cb..69d7903 100644 --- a/w3-blob.md +++ b/w3-blob.md @@ -785,10 +785,12 @@ Receipt MUST not have any effects. ## Get Blob -Authorized agent MAY invoke `/space/content/get/blob` capability on the [space] subject (`sub` field) to get Blobs added to it at the time of invocation. +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. @@ -797,7 +799,7 @@ Shown Invocation example illustrates Alice getting a blob stored on their space. ```js { // "/": "bafy..get" - "cmd": "/space/content/get/blob", + "cmd": "/space/content/get/blob/0/1", "sub": "did:key:zAlice", "iss": "did:key:zAlice", "aud": "did:web:web3.storage", @@ -810,7 +812,7 @@ Shown Invocation example illustrates Alice getting a blob stored on their space. ### Get Blob Receipt Example -Shows an example receipt for the above `/space/content/get/blob` capability invocation. +Shows an example receipt for the above `/space/content/get/blob/0/1` capability invocation. ```js { @@ -824,7 +826,7 @@ Shows an example receipt for the above `/space/content/get/blob` capability invo "out": { "ok": { // task that caused this invocation - "cause": { "/": "bafy..add" } + "cause": { "/": "bafy..task" } "blob": { "size": 100, "content": { "/": { "bytes": "mEi...sfKg" } }, @@ -842,7 +844,7 @@ Shows an example receipt for the above `/space/content/get/blob` capability invo ```ts type GetBlob = { - cmd: "/space/content/get/blob" + cmd: "/space/content/get/blob/0/1" sub: SpaceDID args: { digest: Multihash From c9476ca4a0e357d03b20d0a020d93b15fefb2041 Mon Sep 17 00:00:00 2001 From: Joao Andrade Date: Tue, 4 Jun 2024 18:34:21 +0100 Subject: [PATCH 13/13] fix: specify Blob type --- w3-blob.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/w3-blob.md b/w3-blob.md index 69d7903..6de4fec 100644 --- a/w3-blob.md +++ b/w3-blob.md @@ -880,7 +880,12 @@ type GetBlobError = { message: string } -type Blob = { /* ??? */ } +type Blob = { + digest: Multihash + size: number +} + +type Multihash = bytes ``` #### Get Cause