diff --git a/README.md b/README.md index 1eeb1d4..a8bfc2f 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ BUDs or **Blossom Upgrade Documents** are short documents that outline an additi - [BUD-07: Payment required](./buds/07.md) - [BUD-08: Nostr File Metadata Tags](./buds/08.md) - [BUD-09: Blob Report](./buds/09.md) -- [BUD-10: Blob URI Schema](./buds/10.md) +- [BUD-10: Blossom URI Schema](./buds/10.md) ## Endpoints diff --git a/buds/10.md b/buds/10.md index a403e5c..b772efd 100644 --- a/buds/10.md +++ b/buds/10.md @@ -1,6 +1,6 @@ # BUD-10 -## Blob URI Schema +## Blossom URI Schema `draft` `optional` @@ -8,15 +8,15 @@ Defines a URI schema for referencing Blossom blobs similar to magnet links. This ## URI Format -The `blob:` URI schema MUST follow this format: +The `blossom:` URI schema MUST follow this format: ``` -blob:.[?param1=value1¶m2=value2...] +blossom:.[?param1=value1¶m2=value2...] ``` ### Components -- `blob:` - The URI scheme identifier +- `blossom:` - The URI scheme identifier - `` - A 64 character lowercase hexadecimal sha256 hash of the blob - `.` - A file extension (e.g., `.pdf`, `.png`, `.jpg`, `.mp4`). If the file extension is unknown, it MUST default to `.bin` - `[?params]` - Optional query parameters for discovery hints @@ -24,15 +24,15 @@ blob:.[?param1=value1¶m2=value2...] ### Examples ``` -blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf -blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.example.com -blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.png?as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&sz=184292 -blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.bin +blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf +blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.example.com +blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.png?as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&sz=184292 +blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.bin ``` ## Query Parameters -The `blob:` URI MAY include the following optional query parameters to assist with blob discovery: +The `blossom:` URI MAY include the following optional query parameters to assist with blob discovery: ### `as` - Author @@ -42,12 +42,12 @@ Clients can use this parameter to lookup the author's [BUD-03](./03.md) server l Example: ``` -blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0 +blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0 ``` Multiple authors: ``` -blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&as=781208004e09102d7da3b7345e64fd193cd1bc3fce8fdae6008d77f9cabcd036 +blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&as=781208004e09102d7da3b7345e64fd193cd1bc3fce8fdae6008d77f9cabcd036 ``` ### `xs` - Server @@ -58,17 +58,17 @@ The value SHOULD be a domain name only. Clients MUST assume the server operates Example: ``` -blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth +blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth ``` With optional scheme: ``` -blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=https://cdn.satellite.earth +blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=https://cdn.satellite.earth ``` Multiple servers: ``` -blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth&xs=blossom.primal.net +blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth&xs=blossom.primal.net ``` ### `sz` - Size @@ -82,7 +82,7 @@ The `sz` parameter MAY be used to specify the size of the blob in bytes. This ca Example: ``` -blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?sz=184292 +blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?sz=184292 ``` The size MUST be a positive integer representing the exact number of bytes in the blob. Clients SHOULD verify that the downloaded blob size matches the `sz` parameter if provided. @@ -92,23 +92,23 @@ The size MUST be a positive integer representing the exact number of bytes in th All parameters MAY be combined in a single URI: ``` -blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth&as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&xs=blossom.primal.net&sz=184292 +blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth&as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&xs=blossom.primal.net&sz=184292 ``` ## Client Implementation -### Parsing blob URIs +### Parsing blossom URIs -When parsing a `blob:` URI, clients MUST: +When parsing a `blossom:` URI, clients MUST: -1. Verify the URI starts with the `blob:` scheme +1. Verify the URI starts with the `blossom:` scheme 2. Extract the 64 character hexadecimal sha256 hash 3. Extract the file extension (which MUST be present) 4. Parse any query parameters (`as`, `xs`, and `sz`) into appropriate types to handle multiple values ### Resolution Strategy -When resolving a `blob:` URI to retrieve the actual blob, clients SHOULD attempt retrieval in the following order: +When resolving a `blossom:` URI to retrieve the actual blob, clients SHOULD attempt retrieval in the following order: 1. **Server Hints**: If the URI contains `xs` parameters, attempt to retrieve the blob from each specified server in the order they appear - For servers without a protocol scheme, try `https://` first, then `http://` @@ -132,7 +132,7 @@ When downloading is complete, if the `sz` parameter was provided, clients SHOULD Given this URI: ``` -blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.example.com&as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&sz=184292 +blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.example.com&as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&sz=184292 ``` A client would: @@ -144,9 +144,9 @@ A client would: 5. Verify the downloaded blob is exactly `184292` bytes 6. If still not found, fallback to well-known servers or local cache -### Creating and Sharing blob URIs +### Creating and Sharing blossom URIs -When creating or sharing a `blob:` URI, clients MUST: +When creating or sharing a `blossom:` URI, clients MUST: 1. Always include the sha256 hash 2. Always include a file extension - if the file extension is unknown or cannot be determined, default to `.bin` (similar to how [BUD-01](./01.md#get-sha256---get-blob) defaults the MIME type to `application/octet-stream`) @@ -162,12 +162,12 @@ Example of creating a URI after upload: ```javascript // After uploading to cdn.satellite.earth -const uri = `blob:${sha256}.${ext}?xs=cdn.satellite.earth&as=${userPubkey}&sz=${size}`; +const uri = `blossom:${sha256}.${ext}?xs=cdn.satellite.earth&as=${userPubkey}&sz=${size}`; ``` ## Use Cases -The `blob:` URI schema enables several use cases: +The `blossom:` URI schema enables several use cases: - **Decentralized Content Addressing**: Share content by hash with discovery hints instead of relying on a single server URL - **Resilient Links**: Links that can survive server outages by including multiple server hints or author information @@ -177,31 +177,31 @@ The `blob:` URI schema enables several use cases: ### Minimal URI ``` -blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf +blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf ``` ### Unknown File Type ``` -blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.bin +blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.bin ``` ### With Single Server Hint ``` -blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth +blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth ``` ### With Size and Author ``` -blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&sz=184292 +blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&sz=184292 ``` ### Full Featured URI ``` -blob:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth&xs=blossom.primal.net&as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&sz=184292 +blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth&xs=blossom.primal.net&as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&sz=184292 ``` ### Image with Multiple Authors and Servers ``` -blob:a7b3c2d1e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1.png?xs=cdn.example.com&xs=media.nostr.build&as=781208004e09102d7da3b7345e64fd193cd1bc3fce8fdae6008d77f9cabcd036&as=b53185b9f27962ebdf76b8a9b0a84cd8b27f9f3d4abd59f715788a3bf9e7f75e&sz=2547831 +blossom:a7b3c2d1e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1.png?xs=cdn.example.com&xs=media.nostr.build&as=781208004e09102d7da3b7345e64fd193cd1bc3fce8fdae6008d77f9cabcd036&as=b53185b9f27962ebdf76b8a9b0a84cd8b27f9f3d4abd59f715788a3bf9e7f75e&sz=2547831 ```