Skip to content

Commit

Permalink
feat: add blob/get
Browse files Browse the repository at this point in the history
  • Loading branch information
joaosa committed May 30, 2024
1 parent 73efe9a commit bd77b80
Showing 1 changed file with 102 additions and 0 deletions.
102 changes: 102 additions & 0 deletions w3-blob.md
Original file line number Diff line number Diff line change
Expand Up @@ -783,6 +783,108 @@ 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": {
"insertedAt": "2024-04-16T15:49:22.638Z",
"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<GetBlobOk, GetBlobError>
next: []
}
type GetBlobOk = ListBlobItem
type ListBlobItem = {
blob: blob
insertedAt: ISO8601Date
}
type ISO8601Date = string
type GetBlobError = {
message: string
}
```

##### Get Blob Effects

Receipt MUST not have any effects.

# Coordination

## Publishing Blob
Expand Down

0 comments on commit bd77b80

Please sign in to comment.