blossom/buds/10.md

BUD-10

Blossom URI Schema

draft optional

Defines a URI schema for referencing Blossom blobs similar to magnet links. This allows users to share blob references that include discovery hints for locating the blob on other Blossom servers.

URI Format

The blossom: URI schema MUST follow this format:

blossom:<sha256>.<ext>[?param1=value1&param2=value2...]

Components

• blossom: - The URI scheme identifier
• <sha256> - A 64 character lowercase hexadecimal sha256 hash of the blob
• .<ext> - 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

Examples

blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf
blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.example.com
blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.png?as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&sz=184292
blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.bin

Query Parameters

The blossom: URI MAY include the following optional query parameters to assist with blob discovery:

as - Author

The as parameter specifies the hex pubkey of a user who uploaded the blob. This parameter MAY be repeated multiple times to specify multiple potential authors.

Clients can use this parameter to lookup the author's BUD-03 server list (kind:10063) and attempt to retrieve the blob from those servers.

Example:

blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0

Multiple authors:

blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&as=781208004e09102d7da3b7345e64fd193cd1bc3fce8fdae6008d77f9cabcd036

xs - Server

The xs parameter specifies a server domain where the blob may be available. This parameter MAY be repeated multiple times to specify multiple server hints.

The value SHOULD be a domain name only. Clients MUST assume the server operates at the root of the domain as per BUD-01. The protocol scheme (http/https) MAY be included but is optional. When no scheme is specified, clients SHOULD try both https:// and http:// with preference given to https://.

Example:

blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth

With optional scheme:

blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=https://cdn.satellite.earth

Multiple servers:

blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth&xs=blossom.primal.net

sz - Size

The sz parameter MAY be used to specify the size of the blob in bytes. This can help clients:

• Verify the downloaded blob matches the expected size
• Display download progress or estimated time
• Decide whether to download the blob based on size constraints
• Pre-allocate storage space

Example:

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.

Combined Parameters

All parameters MAY be combined in a single URI:

blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth&as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&xs=blossom.primal.net&sz=184292

Client Implementation

Parsing blossom URIs

When parsing a blossom: URI, clients MUST:

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 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://
   • Request the blob using the BUD-01 GET /<sha256> endpoint
   • Include the file extension from the URI if present
   • If the sz parameter is present, verify the Content-Length header matches before downloading

2. Author Server Lists: If the URI contains as parameters, for each author pubkey:

   • Fetch the author's BUD-03 server list (kind:10063)
   • Attempt to retrieve the blob from each server in the author's list in order
   • If multiple authors are specified, try each author's server list before giving up

3. Fallback Servers: If the blob cannot be found using hints, clients MAY fallback to:

   • Well-known public Blossom servers
   • Local cache or previously known locations
   • User-configured default servers

When downloading is complete, if the sz parameter was provided, clients SHOULD verify that the downloaded blob size matches the expected size.

Example Resolution Flow

Given this URI:

blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.example.com&as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&sz=184292

A client would:

1. Try http://cdn.example.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf
2. Check that Content-Length header is 184292 before downloading
3. If that fails, fetch the kind:10063 server list for pubkey ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0
4. Try each server from the author's list in order
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 blossom URIs

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 defaults the MIME type to application/octet-stream)

Clients SHOULD also:

3. Include the sz parameter with the blob size in bytes to help with verification and download management
4. Include at least one xs parameter pointing to a server where the blob is known to exist
5. Include the as parameter with the uploader's pubkey to enable future discovery via their server list
6. Include multiple xs parameters if the blob has been mirrored to multiple servers

Example of creating a URI after upload:

// After uploading to cdn.satellite.earth
const uri = `blossom:${sha256}.${ext}?xs=cdn.satellite.earth&as=${userPubkey}&sz=${size}`;

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
• P2P Sharing: Share blob references that don't depend on a specific server remaining online

Examples

Minimal URI

blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf

Unknown File Type

blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.bin

With Single Server Hint

blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth

With Size and Author

blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&sz=184292

Full Featured URI

blossom:b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf?xs=cdn.satellite.earth&xs=blossom.primal.net&as=ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0&sz=184292

Image with Multiple Authors and Servers

blossom:a7b3c2d1e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1.png?xs=cdn.example.com&xs=media.nostr.build&as=781208004e09102d7da3b7345e64fd193cd1bc3fce8fdae6008d77f9cabcd036&as=b53185b9f27962ebdf76b8a9b0a84cd8b27f9f3d4abd59f715788a3bf9e7f75e&sz=2547831