{"id":"89a120fd6ecd865f44cc0a80ce1e0f3e2875fe4745761c1e97bb97f300bd3b68","pubkey":"df67f9a7e41125745cbe7acfbdcd03691780c643df7bad70f5d2108f2d4fc200","created_at":1770301019,"kind":30817,"tags":[["d","nip-trusted-events"],["title","TRUSTed Events"],["k","37571"],["k","37572"],["k","37573"],["client","nostrhub.io"]],"content":"TRUSTed Info, Rankings, & Assertions\n===\n\n`nip-trusted-events`\n\n`draft`\n\n`kind` `37571` \"TRUSTed Info\"\n\n`kind` `37572` \"TRUSTed Rankings\"\n\n`kind` `37573` \"TRUSTed Assertions\"\n\n\n\n`extends` [nip-trusted-filters](https://nostrhub.io/naddr1qvzqqqrcvypzphm8lxn7gyf9w3wtu7k0hhxsx6ghsrry8hmm44c0t5ss3uk5lssqqy2hwumn8ghj7erfw36x7tnsw43z7un9d3shjqqnde5hqtt5wf6hxar9vskkv6tvw3jhyuc7am7eg)\n\n`extends` [nip-trusted-filter-presets](https://nostrhub.io/naddr1qvzqqqrcvypzphm8lxn7gyf9w3wtu7k0hhxsx6ghsrry8hmm44c0t5ss3uk5lssqqy2hwumn8ghj7erfw36x7tnsw43z7un9d3shjqq6de5hqtt5wf6hxar9vskkv6tvw3jhyttswfjhxet5wvrtz6pf)\n\n---\n\nThis NIP specifies three event kinds and for generating Assertions, Rankings, and Stats from TRUSTed Filters, and a general purpose ranking plugin \n\n- The **TRUSTed Info Event** (kind `37571`) renders general interpreted data (not limited to a `subject` or a `pov`) about the network or a set of events. Used for publishing aggregated metrics, counts, and computed values.\n- The **TRUSTed Rankings Event** (kind `37572`) renders interpreted `ranking` values related to ONE or MORE `subjects` from ONE `pov` and ONE `context`. Used for publishing WoT style rankings for any `type` of `subject`.\n- The **TRUSTed Assertions Event** (kind `37573`) renders any set of interpreted data about a SINGLE `subject` using any number of `assertion presets`. Used for making specific claims about a single subject. \n\n**Terminology:**\n- `subject` - a value (from index 1) of any standard indexable tag (single letter key) about which assertions MAY be generated. (eg: a *pubkey* from `p` tags, an *event id* from `e` tags, a *hashtag* string from `t` tags)\n- `type` - Any single-letter tag key used typing subject data and for matching subject tags in events (e.g., `p`, `e`, `t`)\n- `ranking` (or `rank`) - A numeric value (0-100) representing a subject's influence within a context.\n- `context` - A unique (per author) string identifying a `ranking preset` (which generates TRUSTed Rankings events) OR a reference to ANY event containing `p` tags (a list of possibly ranked users).\n- `pov` - The \"point of view\" pubkey from which rankings MAY be calculated (usually subscriber pubkey) within a context.\n- `assertion preset` - Any preset that writes interpreted data about a subject to `IO.assertions` (for rendering as a tag in assertion events).\n\n## TRUSTed Info Event (kind `37571`)\n\nThis is the simplest of TRUSTed events. Because interpreted data is not related to a specific subject or context, generation of these events does not require any special plugins or `W` inputs.\n\n**Use Cases:**\n- Network-wide statistics (total events, user counts, etc.)\n- Aggregated metrics (sums, averages, min/max values)\n- Time-based analytics (events per day, growth rates)\n- Any computed values that don't relate to a specific subject\n\n**Info Event Format**\n\n```jsonc\n{\n  \"kind\": 37571,\n  \"pubkey\": \"<subscription_pubkey>\",\n  \"tags\": [\n    // Required: replaceable event identifier\n    [\"d\", \"<identifier>\"],\n\n    // Reference one or more data presets\n    [\"W\", \"<naddr_to_data_preset>\"],\n    // (or assertion presets that DON'T require `W` inputs)\n    [\"W\", \"<naddr_to_assertion_preset>\"],\n\n    // tags SHOULD be rendered \n    // from aggregated IO `w` and `#` namespaces\n    [\"w\", \"<key>:<value>\"],\n  ]\n}\n```\n\n**Info Preset Format:**\n```jsonc\n{\n  \"kind\": 37570,\n  // preset content is always JSON stringified (and MAY be encrypted)\n  \"content\": [\n    // any number of filters MAY collect events from the network\n    {\n      \"plugins\": [\n        // any number of plugins MAY interpret data from events\n        [\"<any_plugin>\", \n          // plugins SHOULD NOT require `W` inputs\n          // plugins SHOULD write data to `w` or `#` namespaces in `IO`\n        ],\n        // IO should NOT be published to events\n      ]\n    }\n  ]\n\n}\n```\n\n## TRUSTed Rankings Event (kind `37572`)\n\nTRUSTed Rankings events are used to rank multiple subjects from a single point of view within a specific context. These events are rendered by ONE ranking preset, which outputs ranked subject tags to the event. Each TRUSTed Ranking Preset interprets interactions and calculates rank values for subjects.\n\n\n**Rankings Event Format:**\n\n```jsonc\n{\n  \"kind\": 37572,\n  \"pubkey\": \"<subscription_pubkey>\",\n  \"tags\": [\n    // Required: replaceable event identifier\n    [\"d\", \"<rankings_event_id>\"],\n\n    // Reference one ranking preset\n    [\"W\", \"<naddr_to_ranking_preset>\"],\n\n    // These (lowercase) `w` output tags \n    // SHOULD be provided by each ranking preset\n    // to help identify the events generated by it\n    [\"w\", \"ranking:<ranking_preset_id>\"],\n    [\"w\", \"tagletter:<tag_letter>\"],\n\n    // this (uppercase) `W` tag\n    // reflects the `pov` pubkey used by the ranking preset\n    [\"W\", \"pov:<pov_pubkey>\"],\n\n    // Additional (uppercase) `W` tags\n    // may reflect provider specific inputs to calculate ranking \n    [\"W\", \"<provider_param>:<param_value>\"],\n    \n\n    // ALL ranking presets SHOULD output ranked subject tags\n    // in the format: [\"<type>\", \"<subject>\", \"<rank>\"]\n    [\"<type>\", \"<subject_1>\", \"<rank>\"],\n    [\"<type>\", \"<subject_2>\", \"<rank>\"],\n  ]\n}\n```\n\n**Ranking Preset Format:**\n\n```jsonc\n{\n  \"kind\": 37570,\n  \"pubkey\": \"<subscription_pubkey>\",\n  \"tags\": [\n    // Required: replaceable event identifier\n    [\"d\", \"<ranking_preset_id>\"],\n  ],\n  \"content\": [\n    {\n      \"plugins\": [\n        // Ranking presets SHOULD \n        // set \"default\" values in these (lowercase) `w` output plugins\n        // to advertise specific info about the ranking preset (in generated events)\n        [\"w\", \n          // `tagletter` is a single letter tag key used for the output subject tags\n          // (set default to the tag letter used by the ranking preset)\n          [\"tagletter\", \"\", \"p\"],\n\n          // `ranking` SHOULD reflect the preset's `d` tag value \n          // (and make it available for string replacement in the filters)\n          [\"ranking\", \"\", \"<ranking_preset_id>\"],\n        ],\n\n        // Rankings presets SHOULD \n        // get input from requestors using these (uppercase) `W` plugins\n        [\"W\", \n          // `pov` is a pubkey \"point of view\" for the generated rankings\n          // (usually a subscriber or subscription pubkey)\n          [\"pov\", \"pubkey\"],\n\n          // ranking presets MAY have additional (calculator) `W` inputs\n          // required or optional as determined by the service provider\n          [\"<provider_param>\", \"<param_type>\", \"\", \"<param_default>\"]\n        ],\n      ]\n    },\n    // any number of filters MAY be used to collect events from the network\n    // for interpreting interactions and calculating ranks\n    {\n      \"plugins\": [\n        // Rankings presets SHOULD output \"ranked subject\" tags to `IO.#`\n        // (in the format of: [\"<tagletter>\", \"<subject>\", \"<rank>\"]).\n        // Rankings presets MAY use the `ranked` plugin to request this list directly\n        // from the service provider and to output it to `#` namespace\n        [\"ranked\", [\"${W.pov}\", \"${w.ranking}\", \"${w.tagletter}\", \"#\"]]\n      ]\n    }\n  ]\n}\n```\n\n---\n\n## TRUSTed Assertions Event (kind `37573`)\n\nTRUSTed Assertion events are used to assert specific claims about a single subject. These events are rendered by ONE OR MORE Assertion Presets, each charged with outputting ONE or more assertion tags to `IO:#`. Each TRUSTed Assertion Preset MAY make use of (a list of) TRUSTed Rankings in the process of filtering events for generating assertion values.\n\n\n**Assertions Event Format:**\n\n```jsonc\n{\n  \"kind\": 37573,\n  \"pubkey\": \"<subscription_pubkey>\",\n  \"tags\": [\n    // Required: replaceable event identifier\n    [\"d\", \"<assertion_event_id>\"],\n\n    // Reference one or more assertion presets\n    [\"W\", \"<naddr_to_assertion_preset>\"],\n    [\"W\", \"<naddr_to_assertion_preset>\"],\n\n    // the following `W` inputs\n    // are passed to every assertion preset\n    [\"W\", \"subject:<tag_value>\"],\n    [\"W\", \"tagletter:<tag_letter>\"],\n    [\"W\", \"ranking:<ranking_preset_id>\"],\n    [\"W\", \"pov:<pov_pubkey>\"],\n\n    // assertion presets SHOULD output these (lowercase) `w` tags \n    // advertising the `d` tag value of the preset\n    [\"w\", \"assertion:<assertion_preset_id_1>\",],\n    [\"w\", \"assertion:<assertion_preset_id_2>\",],\n    \n\n    // ALL assertion presets SHOULD output `assertion` tags \n    // keyed by the `d` tag value of the assertion preset\n    [\"<assertion_preset_id_1>\", \"<value>\"],\n    [\"<assertion_preset_id_2>\", \"<value>\"],\n  ]\n}\n```\n\n**Assertions Preset Format:**\n\n```jsonc\n{\n  \"kind\": 37570,\n  \"pubkey\": \"<subscription_pubkey>\",\n  \"tags\": [\n    // Required: replaceable event identifier\n    [\"d\", \"<assertion_preset_id>\"],\n  ],\n  \"content\": [\n    // Assertions presets SHOULD have the following \n    // (uppercase) `W` plugin inputs\n    {\n      \"plugins\": [\n        [\"W\", \n          // `W.tagletter` is the expected tag letter \n          // (type) for subject (MAY default to `p`)\n          [\"tagletter\", \"tagletter\", \"\", \"p\"],\n          // `W.subject` is a unique identifier for a subject (of `tagletter`)\n          // upon which assertions are made (like a pubkey or an event id)\n          [\"subject\", \"string\"],\n          // `W.pov` is a pubkey \"point of view\" for the generated assertions\n          // (usually a subscriber or subscription pubkey)\n          [\"pov\", \"p\", \"\", \"<subscriber_pubkey>\"],\n          // `W.ranking` SHOULD reference a known filter or preset\n          // from which a service can provide rankings (on any subject type)\n          // which MAY be used by assertions to limit the set of candidate events\n          [\"ranking\", \"identifier\", \"\", \"\"]\n        ],\n\n        // Assertion presets SHOULD use these (lowercase) `w` plugins\n        // `w.assertion` advertizes the preset's `d` tag value in generated events\n        // AND makes it available for string replacement in the presets filters\n        [\"w\", \"assertion\", \"\", \"<assertion_preset_id>\"],\n      ]\n    },\n    {\n      // any number of additional filters MAY collect events from the network\n      // and transform these into `IO` data for assertions output\n      \"plugins\": [\n        // Assertions presets MAY call `ranked` plugin\n        // to have user rankings available for assertion calculations\n        [\"ranked\", [\"${W.pov}\", \"${W.ranking}\"]]\n      ]\n    },\n    {\n      \"plugins\": [\n        // Assertions presets SHOULD render assertions ONLY to the `IO:#` namespace\n        // Keyed by the preset's `d` tag value in this format:\n        // `[\"<assertion_preset_id>\", \"<value>\"]`\n        [\"#\", \n          // This will render a basic assertions tag \n          // using the preset's `d` tag value from `IO:w.assertion`\n          [\"${w.assertion}\", \"<value>\", \"#\"],\n        ],\n        // Any (conventional) transformation plugins can also be used\n        // to output assertions directly to `IO:#` namespace \n        // (by using \"#\" for the `namespace` param)\n        [\"<any_transformation_plugin>\", \n          [\"${w.assertion}\", \"<any_param>\", ..., \"#\"],\n        ],\n        // The above format (outputting ONLY to `IO:#` namespace)\n        // will result in assertions tags rendering properly \n        // when assertion event presets are executed 'indirectly' \n        // (by requesting the event kind and W tags in a TRUST message)\n      ]\n    }\n  ]\n}\n```\n\n\n## `ranked` Plugin\n\n`ranked` is a **Transformation** plugin. It requests ranked subjects from the service provider and stores them in `IO` at `ranked` (or any writable namespace). This MAY be used within any filter to request subject rankings directly from the provider based on a specific point of view and context.\n\n**Functions:**\n\n```jsonc\n{\n  \"plugins\": [\n    [\"ranked\", [\"<pov>\", \"<ranking>\", \"<tagletter?>\", \"<namespace?>\"]]\n  ]\n}\n```\n\n**Arguments:**\n\n0. `<pov>` : `pubkey` : (required) : Point of view pubkey from which rankings are calculated\n1. `<ranking>` : `string` : (required) : An identifier for the algorithm (preset `d` tag value) to use for ranking\n2. `<tagletter>` : `tagletter` : (optional) : Tag letter for subject type (defaults to `p`)\n3. `<namespace>` : `string` : (optional) : Namespace in `IO` to store the ranked subject tags (defaults to `ranked`)\n\n\n**IO:**\n- **Outputs:** an array of ranked subject tags in format `[\"<subject_type>\", \"<subject>\", \"<rank>\"]`\n- **Writes to:** `IO` at `ranked`, or any writable namespace as specified in the namespace argument.\n- **Write Access:** Any plugin may append ranked subjects tags to the `ranked:<plugin>` namespace.\n\n**Behavior:**\n\n- Requests ranked subjects from service provider using `<pov>` and `<ranking>`.\n- Stores ranked subjects in `IO`, at `ranked` as an array of tag arrays.\n- Each ranked subject is stored as `[\"<tagletter>\", \"<subject>\", \"<rank>\"]`.\n- If `<tagletter>` is omitted, the ranking preset should determine the tag letter to use.\n- Allows other plugins to append their own ranked subjects to `ranked:<plugin>` namespace.","sig":"49f87f161b83d269d6f945fb2d3cc4c28e1b98ec081fd9348ecef55fcb31e5b69f66202df7fc5f1585d35b3a85489aca5706c797ab049682e6a994104202944b"}