From 79d1543358d07456ae5d5de32a3a6475dd8fe651 Mon Sep 17 00:00:00 2001 From: hzrd149 Date: Sat, 18 May 2024 07:38:27 -0500 Subject: [PATCH 1/6] Add bud-02 User Server List --- Nostr.md | 26 -------------------------- README.md | 11 +++++++++++ buds/bud-02.md | 40 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 51 insertions(+), 26 deletions(-) delete mode 100644 Nostr.md create mode 100644 buds/bud-02.md diff --git a/Nostr.md b/Nostr.md deleted file mode 100644 index 9206007..0000000 --- a/Nostr.md +++ /dev/null @@ -1,26 +0,0 @@ -# Blossom nostr integration - -Blossom uses nostr for public / private key identities. Users are expected to sign authentication events to prove their identity when uploading or deleting blobs - -See [Authorization events](./Server.md#authorization-events) - -## User Server Discovery - -Users should publish a kind `10063` event with a list of ordered `server` tags indicating servers that others users should use when getting their blobs - -### Example - -```json -{ - "id": "e4bee088334cb5d38cff1616e964369c37b6081be997962ab289d6c671975d71", - "pubkey": "781208004e09102d7da3b7345e64fd193cd1bc3fce8fdae6008d77f9cabcd036", - "content": "", - "kind": 10063, - "created_at": 1708774162, - "tags": [ - ["server", "https://cdn.self.hosted"], - ["server", "https://cdn.satellite.earth"] - ], - "sig": "cc5efa74f59e80622c77cacf4dd62076bcb7581b45e9acff471e7963a1f4d8b3406adab5ee1ac9673487480e57d20e523428e60ffcc7e7a904ac882cfccfc653" -} -``` diff --git a/README.md b/README.md index e532dc6..baf58bf 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,17 @@ BUDs stand for **Blossom Upgrade Documents**. See the [BUDs](./buds) folder and specifically [BUD-01](./buds/bud-01.md) for a detailed explanation of the endpoints +## BUDs + + - [Core endpoint description](./buds/bud-01.md) + - [User Server List](./buds/bud-02.md) + +## Event kinds +| kind | description | NIP | +| ------------- | -------------------------- | ------------------------ | +| `24242` | Authorization event | [01](./buds/bud-01.md.md)| +| `10063` | User Server List | [02](./buds/bud-02.md.md)| + ## License Public domain. diff --git a/buds/bud-02.md b/buds/bud-02.md new file mode 100644 index 0000000..aff4fd7 --- /dev/null +++ b/buds/bud-02.md @@ -0,0 +1,40 @@ +BUD-02 +====== + +User Server List +------------------------- + +`draft` `optional` + +Defines a replaceable event using `kind:10063` to advertise the blossom servers for downloading a user's blobs from. + +The event MUST include an ordered list of `server` tags with the server URL including the `http://` or `https://`. + +The order of these tags is important and should be arranged with the users most "reliable" or "trusted" servers coming first. + +The `.content` is not used. + +```json +{ + "id": "e4bee088334cb5d38cff1616e964369c37b6081be997962ab289d6c671975d71", + "pubkey": "781208004e09102d7da3b7345e64fd193cd1bc3fce8fdae6008d77f9cabcd036", + "content": "", + "kind": 10063, + "created_at": 1708774162, + "tags": [ + ["server", "https://cdn.self.hosted"], + ["server", "https://cdn.satellite.earth"] + ], + "sig": "cc5efa74f59e80622c77cacf4dd62076bcb7581b45e9acff471e7963a1f4d8b3406adab5ee1ac9673487480e57d20e523428e60ffcc7e7a904ac882cfccfc653" +} +``` + +## Client Integration + +When uploading blobs clients should attempt to upload the blob to all or at least the top 3 server on the list event. + +This ensures that the blob is available in multiple locations in the case one of the servers goes offline. + +## Server Integration + +Servers may use this event kind to discover other servers that a user is uploading to in order to download specific blobs from. From eb85eef7d447fca573095fa4f1a8d1bfef065ba9 Mon Sep 17 00:00:00 2001 From: hzrd149 Date: Wed, 22 May 2024 09:32:17 -0500 Subject: [PATCH 2/6] small fixes for wording --- buds/{bud-02.md => 02.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename buds/{bud-02.md => 02.md} (87%) diff --git a/buds/bud-02.md b/buds/02.md similarity index 87% rename from buds/bud-02.md rename to buds/02.md index aff4fd7..42345a3 100644 --- a/buds/bud-02.md +++ b/buds/02.md @@ -6,9 +6,9 @@ User Server List `draft` `optional` -Defines a replaceable event using `kind:10063` to advertise the blossom servers for downloading a user's blobs from. +Defines a replaceable event using `kind:10063` to advertise the blossom servers a user uses to host their blobs. -The event MUST include an ordered list of `server` tags with the server URL including the `http://` or `https://`. +The event MUST include at least one `server` tag containing the full server URL including the `http://` or `https://`. The order of these tags is important and should be arranged with the users most "reliable" or "trusted" servers coming first. From 7d61cd96d2e6a074cf51008c2e120686d2c5a8b1 Mon Sep 17 00:00:00 2001 From: hzrd149 Date: Sat, 8 Jun 2024 09:25:12 -0500 Subject: [PATCH 3/6] add client implementation details --- buds/03.md | 50 ++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 44 insertions(+), 6 deletions(-) diff --git a/buds/03.md b/buds/03.md index 42345a3..e52d010 100644 --- a/buds/03.md +++ b/buds/03.md @@ -10,9 +10,9 @@ Defines a replaceable event using `kind:10063` to advertise the blossom servers The event MUST include at least one `server` tag containing the full server URL including the `http://` or `https://`. -The order of these tags is important and should be arranged with the users most "reliable" or "trusted" servers coming first. +The order of these tags is important and should be arranged with the users most "reliable" or "trusted" servers being first. -The `.content` is not used. +The `.content` field is not used. ```json { @@ -29,12 +29,50 @@ The `.content` is not used. } ``` -## Client Integration +## Client Upload Implementation -When uploading blobs clients should attempt to upload the blob to all or at least the top 3 server on the list event. +When uploading blobs clients MUST attempt to upload the blob to at least the first `server` listed in the users server list. + +Optionally clients MAY upload the blob to all the servers or mirror the blob to the other servers if they support [BUD-04](./04.md) This ensures that the blob is available in multiple locations in the case one of the servers goes offline. -## Server Integration +## Client Retrieval Implementation -Servers may use this event kind to discover other servers that a user is uploading to in order to download specific blobs from. +When extracting the SHA256 hash from the URL clients MUST use the last occurrence of a 64 char hex string. This allows clients to extract hashes from blossom URLs and SOME non-blossom URLs. + +In all the following examples, the hash `b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553` should be selected + +- Blossom URLs + - `https://blossom.example.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf` + - `https://cdn.example.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553` +- Non Blossom URLs + - `https://cdn.example.com/user/ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0/media/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf` + - `https://cdn.example.com/media/user-name/documents/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf` + - `http://download.example.com/downloads/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553` + - `http://media.example.com/documents/b1/67/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf` + +In the context of nostr events, clients SHOULD use the author's server list when looking for blobs that are no longer available at the original URL. + +Take the following event as an example + +```json +{ + "id": "834185269f4ab72539193105060dbb1c8b2efd702d14481cea345c47beefe6eb", + "pubkey": "ec4425ff5e9446080d2f70440188e3ca5d6da8713db7bdeef73d0ed54d9093f0", + "content": "I've developed a new open source P2P e-cash system called Bitcoin. check it out\nhttps://cdn.broken-domain.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf", + "kind": 1, + "created_at": 1297484820, + "tags": [], + "sig": "bd4bb200bdd5f7ffe5dbc3e539052e27b05d6f9f528e255b1bc4261cc16b8f2ad85c89eef990c5f2eee756ef71b4c571ecf6a88ad12f7338e321dd60c6a903b5" +} +``` + +Once the client discovers that the URL `https://cdn.broken-domain.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf` is no longer available. It should perform the following steps to find the blob: + +1. Get the SHA256 has from the URL +2. Look for the authors server list `kind:10063` +3. If found, Attempt to retrieve the blob from each `server` listed started with the first +3. If not found, the client MAY fallback to using a well-known popular blossom server to retrieve the blob + +This ensures clients can quickly find missing blobs using the users list of trusted servers. From 2e2abe2678e4221880d7968ffa833e4c3c33997f Mon Sep 17 00:00:00 2001 From: hzrd149 Date: Sat, 8 Jun 2024 09:34:16 -0500 Subject: [PATCH 4/6] update readme --- README.md | 15 +++++++++------ buds/03.md | 2 +- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 05812b5..78f67e8 100644 --- a/README.md +++ b/README.md @@ -35,14 +35,17 @@ See the [BUDs](./buds) folder and specifically [BUD-01](./buds/01.md) and [BUD-0 ## BUDs - - [Core endpoint description](./buds/bud-01.md) - - [User Server List](./buds/bud-02.md) +- [Server requirements and blob retrieval](./buds/01.md) +- [Blob upload and management](./buds/02.md) +- [User Server List](./buds/03.md) +- [Mirroring blobs](./buds/04.md) ## Event kinds -| kind | description | NIP | -| ------------- | -------------------------- | ------------------------ | -| `24242` | Authorization event | [01](./buds/bud-01.md.md)| -| `10063` | User Server List | [02](./buds/bud-02.md.md)| + +| kind | description | BUD | +| ------- | ------------------- | ------------------ | +| `24242` | Authorization event | [01](./buds/01.md) | +| `10063` | User Server List | [03](./buds/03.md) | ## License diff --git a/buds/03.md b/buds/03.md index e52d010..b98404b 100644 --- a/buds/03.md +++ b/buds/03.md @@ -1,4 +1,4 @@ -BUD-02 +BUD-03 ====== User Server List From 559c0274b93b28695f422cddef3e44ad1a286fdc Mon Sep 17 00:00:00 2001 From: hzrd149 Date: Mon, 22 Jul 2024 09:39:19 -0500 Subject: [PATCH 5/6] small spelling fix --- buds/03.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buds/03.md b/buds/03.md index b98404b..0cf971a 100644 --- a/buds/03.md +++ b/buds/03.md @@ -68,7 +68,7 @@ Take the following event as an example } ``` -Once the client discovers that the URL `https://cdn.broken-domain.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf` is no longer available. It should perform the following steps to find the blob: +Once the client discovers that the URL `https://cdn.broken-domain.com/b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553.pdf` is no longer available. It can perform the following steps to find the blob: 1. Get the SHA256 has from the URL 2. Look for the authors server list `kind:10063` From ea53e0b389593fc3872266dac446162ca76109b9 Mon Sep 17 00:00:00 2001 From: hzrd149 Date: Mon, 22 Jul 2024 09:40:19 -0500 Subject: [PATCH 6/6] update bud list --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 78f67e8..9c9c85c 100644 --- a/README.md +++ b/README.md @@ -35,10 +35,10 @@ See the [BUDs](./buds) folder and specifically [BUD-01](./buds/01.md) and [BUD-0 ## BUDs -- [Server requirements and blob retrieval](./buds/01.md) -- [Blob upload and management](./buds/02.md) -- [User Server List](./buds/03.md) -- [Mirroring blobs](./buds/04.md) +- [BUD-01: Server requirements and blob retrieval](./buds/01.md) +- [BUD-02: Blob upload and management](./buds/02.md) +- [BUD-03: User Server List](./buds/03.md) +- [BUD-04: Mirroring blobs](./buds/04.md) ## Event kinds