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