Software applications events #1336
+319
−3
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,316 @@ | ||
| NIP-82 | ||
| ====== | ||
|
|
||
| Software Applications | ||
| --------------------- | ||
|
|
||
| `draft` `optional` | ||
|
|
||
| This NIP defines kind 32267 to describe a software application, kind 30063 for a software release and kind 3063 for a software asset. | ||
|
|
||
| ## Software Application | ||
|
|
||
| An application is a parameterizable replaceable event as a pubkey may maintain many different ones and update their description over time. | ||
|
|
||
| ```jsonc | ||
| { | ||
| "kind": 32267, | ||
| // Full description of the application, markdown is allowed | ||
| "content": "<description>", | ||
| "tags": [ | ||
| [ | ||
| // REQUIRED | ||
| // Reverse-domain identifier (com.example.app) recommended, can be any string | ||
| "d", "<app-id>" | ||
| ], | ||
| [ | ||
| // REQUIRED | ||
| // App name | ||
| "name", "<human-readable project name>" | ||
| ], | ||
| [ | ||
| // OPTIONAL | ||
| // Summary, short description, Markdown not allowed | ||
| "summary", "<summary-text>" | ||
| ], | ||
| [ | ||
| // OPTIONAL | ||
| // Icon URL | ||
| "icon", "<icon-url>" | ||
| ], | ||
| [ | ||
| // OPTIONAL, MULTIPLE | ||
| // Image URL | ||
| "image", "<image-url>" | ||
| ], | ||
| [ | ||
| // OPTIONAL, MULTIPLE | ||
| // Tags used to describe the application | ||
| "t", "<tag>" | ||
| ], | ||
| [ | ||
| // OPTIONAL | ||
| // Website URL for the application | ||
| "url", "<website-url>" | ||
| ], | ||
| [ | ||
| // OPTIONAL | ||
| // Source code repository URL: https://github.com/example/android | ||
| // Must be able to `git clone <repo-url>` | ||
| "repository", "<repo-url>" | ||
| ], | ||
| [ | ||
| // OPTIONAL | ||
| // Pointer to NIP-34 repository | ||
| "a", "30617:<destination-pubkey>:<repo-id>", "<relay-url>" | ||
| ], | ||
| [ | ||
| // REQUIRED, MULTIPLE | ||
| // All platform identifiers supported in available assets (kind 3063 events) | ||
| // NOTE: See Appendix A | ||
| "f", "<platform-identifier>" | ||
| ], | ||
| [ | ||
| // OPTIONAL | ||
| // SPDX license ID | ||
| "license", "<spdx-id>" | ||
| ] | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| All tags are optional but `d` MUST be present. | ||
|
|
||
| Applications SHOULD use their application or bundle identifier (typically in reverse-domain notation) as the `d` tag. Note that application and asset identifiers are independent, an Android app may have `com.example.android` as ID while its MacOS counterpart may use `com.example.mac`. | ||
|
|
||
| For `icon` and `image` tags any URL is valid but a Blossom [BUD-01](https://github.com/hzrd149/blossom/blob/master/buds/01.md#get-sha256---get-blob) endpoint is recommended. | ||
|
|
||
| `f` tags SHOULD be included to describe supported platforms that MUST match predefined identifiers. See [Appendix A](#). | ||
|
|
||
| License IDs are SPDX IDs as defined in https://spdx.org/licenses/. | ||
|
|
||
| ## Software Release | ||
|
|
||
| A release is a parameterizable replaceable event, it is important for developers to be able to overwrite a bad release and update pointers to the right assets. | ||
|
|
||
| It also contains a release channel name. | ||
|
|
||
| ```jsonc | ||
| { | ||
| "kind": 30063, | ||
| // Full release notes, Markdown allowed | ||
| "content": "<release-notes>", | ||
| "tags": [ | ||
| [ | ||
| // REQUIRED | ||
| // This MUST be the `d` tag in the application kind 32267 | ||
| "i", "<app-id>" | ||
| ], | ||
| [ | ||
| // REQUIRED | ||
| // Release version: 1.2.3, v0.1.2-rc1 | ||
| "version", "<version>" | ||
| ], | ||
| [ | ||
| // REQUIRED | ||
| // MUST be the `i` and `version` tags joined by '@' | ||
| "d", "<identifier>@<version>" | ||
| ], | ||
| [ | ||
| // REQUIRED | ||
| // See Appendix C for channel IDs | ||
| "c", "<channel-id>" | ||
| ], | ||
| [ | ||
| // REQUIRED, MULTIPLE | ||
| // Asset ID | ||
| "e", "<asset-id>" | ||
|
Contributor
There was a problem hiding this comment. I'm having trouble finding the assets, because there is no pubkey hint for a relay list look up. Can you add it? |
||
| ], | ||
| [ | ||
| // OPTIONAL | ||
| // SHA1 commit id used to build the release | ||
| "commit", "<sha1-commit-id>" | ||
| ], | ||
| [ | ||
| // OPTIONAL | ||
| // URL to the release notes: https://github.com/teambtcmap/btcmap-android/releases/tag/v0.9.2 | ||
| "r", "<release-url>" | ||
| ] | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| The `e` tags are pointers to all [Software Asset](#)s in this release. This event MUST be the authoritative source for assets belonging to a given version. | ||
|
|
||
| The identifier `i` MUST be the exact same used in the application. The `d` tag is required and MUST be `<identifier>@<version>` (`i` and `version` tags joined by `@`). | ||
|
|
||
| Note that a release version, typically a git tag, does not need to coincide with any of the linked asset versions. | ||
|
|
||
| ## Software Asset | ||
|
|
||
| An asset is a regular non-replaceable event, mainly used to cryptographically link a file through its SHA-256 hash. This kind is an extension of [kind 1063](94.md). | ||
|
|
||
| ```jsonc | ||
| { | ||
| "kind": 3063, | ||
| // Empty content | ||
| "content": "", | ||
| "tags": [ | ||
| // Tags derived from kind 1063 | ||
| [ | ||
| // REQUIRED | ||
| // Reverse-domain identifier: com.example.app | ||
| // NOTE: Here "i" stands for "identifier", not "infohash" | ||
| "i", "<asset-id>" | ||
| ], | ||
| [ | ||
| // OPTIONAL | ||
| // URL of the asset, may be a Blossom URL | ||
| "url", "<asset-url>" | ||
| ], | ||
| [ | ||
| // OPTIONAL | ||
| // MIME type of the asset | ||
| // NOTE: We rely on platform (`f` tag) | ||
| "m", "<mime-type>" | ||
| ], | ||
| [ | ||
| // REQUIRED | ||
| // SHA-256 hash of the asset | ||
| "x", "<sha256-hash>" | ||
| ], | ||
| [ | ||
| // OPTIONAL | ||
| // Size of the asset in bytes | ||
| "size", "<size-bytes>" | ||
| ], | ||
|
|
||
| // Software Asset-specific tags | ||
| [ | ||
| // REQUIRED | ||
| // Version: 1.2.3, 0.1.2-rc1 | ||
| "version", "<version>" | ||
| ], | ||
| [ | ||
| // REQUIRED, MULTIPLE | ||
| // Platforms | ||
| // NOTE: See Appendix A | ||
| "f", "<platform-id>" | ||
| ], | ||
| [ | ||
| // OPTIONAL | ||
| // Minimum operating system version (minimum compatibility) | ||
| // NOTE: On Android this would be obtained from min_sdk_version | ||
| "min_os_version", "<min-os-version>" | ||
|
Contributor
There was a problem hiding this comment. Wouldn't it have made sense to call it something like |
||
| ], | ||
| [ | ||
| // OPTIONAL | ||
| // Target operating system version (version software was designed for) | ||
| // NOTE: On Android this would be obtained from target_sdk_version | ||
| "target_os_version", "<target-os-version>" | ||
| ], | ||
| [ | ||
| // MULTIPLE | ||
| // Supported Nostr NIP by this software | ||
| // TBD: Should it be kinds? How does this relate to NIP-89 (kind 31990)? | ||
| // TBD: How to support PWAs here (we do support `web` in Appendix A) | ||
| "supported_nip", "<nip-id-string>" | ||
| ], | ||
| [ | ||
| // MULTIPLE | ||
| // Operating system specific permission string | ||
| "permission", "<permission>" | ||
| ], | ||
| [ | ||
| // OPTIONAL | ||
| // On Android: Used for detecting variants, as there is no | ||
| // reliable way of detecting variant/flavor inside an APK | ||
| // Could be useful for other OSes | ||
| // Slashes are NOT allowed | ||
| "filename", "<original-filename>" | ||
| ], | ||
| [ | ||
| // OPTIONAL | ||
| // For self-signers that want to make it clear, fall back to filename above | ||
| "variant", "" | ||
| // "variant", "offline" | ||
| ], | ||
|
|
||
| // Android-specific tags | ||
| [ | ||
| // REQUIRED | ||
| // Android version code | ||
| "version_code", "<version-code-int>" | ||
| ], | ||
| [ | ||
| // REQUIRED, MULTIPLE | ||
| // APK signature hash | ||
| "apk_signature_hash", "<apk-signature-hash>" | ||
| ], | ||
|
|
||
| // CLI-specific tags | ||
| // Runtime dependencies, test script, service (long-running) | ||
|
|
||
| [ | ||
| // MULTIPLE | ||
| // Regular expression of paths to executable inside an archive | ||
| "executable", "<regexp>" | ||
| ], | ||
| [ | ||
| // OPTIONAL | ||
| // Shell call to run in a shell, exit code MUST be zero and regexp MUST be matched | ||
| // `$version` will be replaced by the version tag before evaluating the regexp | ||
| "verification", "<verification-call>", "<assertion-regexp>" | ||
| // "verification", "jq --version", "jq-$version" | ||
| ], | ||
|
|
||
| // TBD: post-install hook? For example with android-commandlinetools use sdkmanager to install latest | ||
|
|
||
| // Linux GUI-specific | ||
| // TBD: Define specific mime-types | ||
| // AppImage, other | ||
| // TBD: Identifier should conform to some regexp? A program can't be called "Happy //C.L.I.// Program" right | ||
|
|
||
| // MacOS GUI-specific | ||
| // TBD: Define specific mime-types | ||
| // DMG, pkg, other | ||
| // Universal builds? | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| Both asset identifier `i` and `version` tags MAY be different to the application and release identifier and version. | ||
|
|
||
| ## Appendix A: Platform identifiers | ||
|
|
||
| Platform is defined as the specific underlying system on which the application is executed, a combination of operating system and hardware architecture. We use the `f` tag for this purpose, with the following identifiers loosely based off `uname -sm`: | ||
|
|
||
| | Identifier | OS | Architecture | | ||
| | --------- | --- | --- | | ||
| | `android-arm64-v8a` | Android | ARMv8-A | | ||
| | `android-armeabi-v7a` | Android | ARMv7-A | | ||
| | `android-x86` | Android | x86 | | ||
| | `android-x86_64` | Android | x86-64 | | ||
| | `darwin-arm64` | MacOS | ARM64 | | ||
| | `darwin-x86_64` | MacOS | x86-64 | | ||
| | `linux-aarch64` | Linux | ARM64 | | ||
| | `linux-x86_64` | Linux | x86-64 | | ||
| | `windows-aarch64` | Windows | ARM64 | | ||
| | `windows-x86_64` | Windows | x86-64 | | ||
| | `ios-arm64` | iOS | ARM64 | | ||
| | `web` | (Web browsers) | - | | ||
|
|
||
| ## Appendix B: ? | ||
|
|
||
| TBC | ||
|
|
||
| ## Appendix C: Channel IDs | ||
|
|
||
| - `main` (Default) | ||
| - `beta` | ||
| - `nightly` | ||
| - `dev` | ||
|
|
||
| ## Appendix D: Attribution | ||
|
|
||
| Signers MAY include other pubkeys as `p` tags and `zap` tags as per [NIP-57 - Appendix G](57.md) in any of the defined event kinds. This is useful when the signer is not the maintainer of the software, or in the case of multiple authors. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this used by anyone?
30063 is already reserved in rust-nostr as
Kind::ReleaseArtifactSet@yukibtcThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You remind me that we should update NIP-51 with changes here (mention that kind 30063 is covered here, and that it should point to kind 3063 events)