← All NIPs

NIP-B7

Blossom

DraftEvents

Use Blossom servers for media: files are stored and found by their sha256 hash, and your kind 10063 server list tells others where to look when a link stops working.

Status
In use and still allowed to change.
Kinds
Tags
  • server
Last changed
Apr 24, 2025

Try it

Edit the form or the JSON: both stay in sync, the badge says whether the result is valid, and tapping any field explains it.

What to build

How the parts connect: Upload, then find it anywhere

Examples
Valid 1 note

Not signed yet · Demo keys only. These personas' secret keys are public on purpose.

Form
Jan 1, 2025, 12:00 AM UTC

Content

Empty: the servers are in the tags.

This kind has no content: leave it as an empty string.

Tags

  1. server Required

    A Blossom server you use, most preferred first.

  2. server Required

    A Blossom server you use, most preferred first.

Add tag

How this NIP works

Step 1 of 5

Files are named by their hash

A Blossom server stores a file under its sha256 hash, so a URL looks like https://server/<64 hex characters>.png. The hash identifies the file whichever server holds it.

In the course

No course chapter covers this NIP yet. The editor above is the quickest way in.

Used by

See also

Specification

Specification text is quoted in English from the nostr-protocol/nips repository. Our explanations and the interface are translated. Source on GitHub at commit 0046368

Read the spec277 words, quoted from the repository at commit 0046368.

This NIP specifies how Nostr clients can use Blossom for handling media.

Blossom is a set of standards (called BUDs) for dealing with servers that store files addressable by their SHA-256 sums. Nostr clients may make use of all the BUDs for allowing users to upload files, manage their own files and so on, but most importantly Nostr clients SHOULD make use of BUD-03 to fetch kind:10063 lists of servers for each user:

{
  "id": "e4bee088334cb5d38cff1616e964369c37b6081be997962ab289d6c671975d71",
  "pubkey": "781208004e09102d7da3b7345e64fd193cd1bc3fce8fdae6008d77f9cabcd036",
  "content": "",
  "kind": 10063,
  "created_at": 1708774162,
  "tags": [
    ["server", "https://blossom.self.hosted"],
    ["server", "https://cdn.blossom.cloud"]
  ],
  "sig": "cc5efa74f59e80622c77cacf4dd62076bcb7581b45e9acff471e7963a1f4d8b3406adab5ee1ac9673487480e57d20e523428e60ffcc7e7a904ac882cfccfc653"
}

Whenever a Nostr client finds a URL in an event published by a given user and that URL ends a 64-character hex string (with or without an ending file extension) and that URL is not available anymore, that means that string is likely a representation of a sha256 and that the user may have a kind:10063 list of Blossom servers published.

Given that, the client SHOULD look into the kind:10063 list for other Blossom servers and lookup for the same 64-character hex string in them, by just using the hex string as a path (optionally with the file extension at the end), producing a URL like https://blossom.self.hosted/<hex-string>.png.

When downloading such files Nostr clients SHOULD verify that the sha256-hash of its contents matches the 64-character hex string.

More information can be found at BUD-03.

More complex interactions

Clients may use other facilities exposed by Blossom servers (for example, for checking if a file exists in a Blossom server, instead of actually downloading it) which are better documented in the BUDs.