TSM Assertion Services

Published Mar 2, 2026

kind 37574kind 37575kind 37576

TSM Assertion Services

tsm-assertion-services

draft

extends tsm-trust-service-machines

kind 37574 "TSM Assertions Set"

kind 37575 "TSM Subject Assertions"

kind 37576 "TSM Network Assertions"

In a distributed network without a clear authority (such as Nostr), facts are notoriously hard to come by. Trusted assertions are a means by which users can request specific facts from known sources, and compare these facts across sources.

This NIP extends the tsm-trust-service-machines NIP with a standard for Assertion Services that can be implemented and extended by any provider. An assertion service is one that determines (or collects) one or more facts from a specified "point of view" of the network, either about a given subject discoverable from that PoV or about the network itself, and outputs these facts as assertion tags in one of these Assertions Output event kinds:

TSM Assertions Set (kind 37574) outputs the results from a single assertion algorithm run on each of the subjects from a given network PoV.

TSM Subject Assertions (kind 37575) outputs the results from any number of assertion algorithms run on a single subject from a given network PoV.

TSM Network Assertions (kind 37576) outputs network-scoped assertions calculated across all subjects from a given network PoV.

Service Expectations

Service announcements SHOULD:

Declare at least ONE supported kind as k tags
Declare BOTH type and pov as config tags
Declare ALL implemented assertion algo specs as a tags (with optional labels)
Declare ALL of the V tags required for output events

Service providers SHOULD respond to Service Request (kind 37572) events by:

Publishing Service Feedback events (kind 7000) to inform on request status
Parsing the pov and type values to result in a set of subjects
Calculating ALL declared subject assertions for EVERY pov subject
Calculating ALL declared network assertions for the pov
Rendering results as requested, in the declared output event kinds
Updating output events according to requested schedule (if supported)

Service Announcement Events

Providers implementing assertion services SHOULD publish a standard TSM Service Announcement event (kind 37570), with the following tags:

{
  "kind": 37570,
  "pubkey": "<service_pubkey>",
  "tags": [
    // ... OPTIONAL and REQUIRED tags as specified by TSM
    
    // REQUIRED one or more of these output event kinds
    ["k", "37574"], // Assertions Set
    ["k", "37575"], // Subject Assertions (optional)
    ["k", "37576"], // Network Assertions (optional)


    // REQUIRED `type` config 
    // A tag letter identifying the type of subjects expected from PoV 
    // (e.g., "p" for pubkeys, "e" for event ids, "u" for urls, etc.)
    ["config", "type", "tagletter", "<description?>", "<default?>", "<allowed?>"],
    
    // REQUIRED `pov` config 
    // One or more subject(s) on which to calculate assertions. 
    // This may be a single subject (any value from a tag of `type`) 
    // or a `naddr` reference to any event with `type` tags. 
    // If the referenced event has a `page` keyed `v` tag, 
    // the provider SHOULD make sure to get ALL the subject tags 
    // from ALL of the paginated events.
    ["config", "pov", "subject|naddr", "<description?>", "<default?>", "<allowed?>"],
    
    // REQUIRED reference(s) to assertion output standards
    // Providers SHOULD announce their implementation of (and compatibility with)
    // assertions output standards, by referencing at least ONE `a` tag 
    // referencing an output standard event (kind `37571`) for each assertion.
    // Output standards MAY be published separately for each output kind (via `k` tag).
    // Rendered assertion tag names SHOULD be reflected in the `a` tag reference,
    // EITHER in the `d` tag of referenced event (when referencing only one standard),
    // OR in the label of `a` tag itself (when compatible standards are referenced).
    ["a", "37571:<pubkey>:<d_tag>", "<relay_hint?>", "<label?>"],

    // CONDITIONAL declare v tags for output events
    ["V", "type", "tagletter", "Type of subjects in output"],
    ["V", "pov", "subject|naddr", "Point of view reference"],
    ["V", "assertion", "string", "Assertion key (used in kind 37574 to identify which assertion algorithm)"],
    
  ],
  "content": "<optional_service_details_markdown>"
}

Assertion Output Standards

Providers implementing assertion services SHOULD refer to published output standard events (kind 37571) in service announcements AND output events, for each assertion they implement in their services. Labels in these references MAY be used to group compatible assertions standards and to specify assertion tags and other output values.

Assertion Labels:

Default assertion labels for output events (tag names ect...) SHOULD match the d tags of the assertion output standards events (kind 37571) referenced in the service announcement.
Service announcements MAY use the a tag label (third argument) to specify a custom assertion label for one or more (compatible) assertion output standards event references.
When multiple a tags share the same label, this indicates that the provider implements multiple compatible output standards that produce the SAME assertion tag in output events. This allows providers to signal compatibility with multiple standards while producing a single unified output value.
Output events SHOULD include an a keyed v tag representing EVERY (a tag) referenced output standard in the service announcement that was used to calculate the assertions.

Output Standards Event Tags:

ONE or more k tags matching at least ONE of the output event kinds specified in this NIP.
Exactly ONE summary tag describing the assertion that SHOULD be calculated by implementors.
Exactly ONE assertion keyed V tag specifying the type of data returned by this assertion.
Zero or more type keyed V tags specifying the subject type(s) suitable for this assertion.

{
  "kind": 37571,
  "pubkey": "<pubkey>",
  "tags": [
    // REQUIRED identifier for this algo spec
    ["d", "<assertion_id>"],
    
    // REQUIRED one or more assertion output kinds this standard applies to
    ["k", "37574"], // Assertions Set
    ["k", "37575"], // Subject Assertions
    ["k", "37576"], // Network Assertions
    
    // REQUIRED plain text application summary 
    // What SHOULD implementors of this standard be asserting,
    // and how might this assertion be used by providers and clients?
    ["summary", "<output_application_summary>"],
    
    // REQUIRED assertion output type
    // Assertion standards SHOULD specify the expected data type 
    // to be returned by implementors.
    ["V", "assertion", "<NostrType>"],
    
    // CONDITIONAL assertion subject type(s)
    // Output standards SHOULD specify the assertion subject type(s)
    // (matching the `type` config in an assertions service announcement)
    // for which this assertion output MAY be calculated by implementors.
    // Zero or more `type` keyed `V` tags MAY be specified.
    // Network Assertions (kind `37576`) do not need a `type` specified.
    ["V", "type", "<tagletter>"],
    
    // OPTIONAL output standard compatibility
    // Specifications MAY indicate compatibility with other specifications
    ["a", "37571:<pubkey>:<d_tag>", "<relay_hint?>"],
  ],
  "content": "<optional_assertion_details>"
}

Service Request Events

Users may request assertion services from a provider by publishing a standard TSM Service Request event (kind 37572), with the following tags:

{
  "kind": 37572,
  "pubkey": "<request_author_pubkey>",
  "tags": [
    // ... OPTIONAL and REQUIRED tags as specified by service announcement
    
    // REQUIRED one or more expected output kinds for this request
    ["k", "37574"], // want Assertions Sets
    ["k", "37575"], // want Subject Assertions (optional)
    ["k", "37576"], // want Network Assertions (optional)
    
    // CONDITIONAL config tags (as defined by provider)
    // Must match the allowed values from the service announcement
    ["config", "type", "<tagletter>"],
    ["config", "pov", "<subject> | <naddr>"],
  ],
  "content": "" // empty or encrypted tags array
}

Service Output : TSM Assertions Set (kind `37574`)

If supported and requested, assertion services SHOULD publish Assertions Sets for every supported assertion output standard, as addressable events of kind 37574. An Assertions Set outputs the results of ONE assertion output standard run on ALL subjects from the given pov.

{
  "kind": 37574,
  "pubkey": "<service_pubkey> | <subscription_pubkey> | <request_pubkey>",
  "tags": [
    // REQUIRED identifier
    ["d", "<assertions_set_id>"],
    
    // REQUIRED `v` tags for discovery and indexing
    ["v", "pov:<pov>"],
    ["v", "type:<type>"],
    
    // REQUIRED assertion output standard reference(s)
    // SHOULD include a v tag for EVERY output standard from service announcement
    // that was used to calculate this assertion output
    // Labels MUST match the labels from service announcement `a` tags
    ["v", "a:37571:<pubkey>:<d_tag>", "<relay_hint?>", "<label?>"],
    
    // OPTIONAL `v` tags to help with discovery of request event
    ["v", "p:<request_author_pubkey>"],
    ["v", "d:<request_id>"],
    
    // CONDITIONAL pagination tags (if paginated)
    ["v", "page:<pagenum>", "[<request_id>:<assertion_key>, <request_id>:<assertion_key>:2, ...]"],
    ["v", "total:<count>"],
    
    // REQUIRED multiple subject tags with assertion values
    // <type> is the tag letter (config `type`)
    // <subject> is the identifier for the subject
    // <assertion_value> is the value calculated for this subject
    // The assertion tag name SHOULD match the label from the `v:a` tag above.
    // When multiple `v:a` tags share the same label (indicating compatible standards),
    // only ONE assertion tag with that label is rendered per subject.
    ["<type>", "<subject>", "<assertion_value>"],
    // ... more subjects
  ]
}

Example Assertions Set Event:

{
  "kind": 37574,
  "pubkey": "provider123...",
  "tags": [
    ["d", "my_analysis:follower_count"],
    ["v", "pov:naddr1..."],
    ["v", "type:p"],
    ["v", "a:37571:alice:follower_count", "wss://relay.example.com"],
    ["v", "p:alice123..."],
    ["v", "d:my_analysis"],
    ["v", "page:1", "[\"my_analysis:follower_count\", \"my_analysis:follower_count:2\"]"],
    ["v", "total:1500"],
    ["p", "bob123...", "500"],
    ["p", "carol123...", "1200"],
    ["p", "dave123...", "87"]
    // ... 997 more subjects (1000 per page)
  ]
}

Service Output : TSM Subject Assertions (kind `37575`)

If supported and requested, assertion services SHOULD publish a Subject Assertions event for every subject in the given pov, as addressable events of kind 37575. Subject Assertions run ALL SUPPORTED assertion output standards on a SINGLE subject, and output these as tags in a single event.

{
  "kind": 37575,
  "pubkey": "<service_pubkey> | <subscription_pubkey> | <request_pubkey>",
  "tags": [
    // REQUIRED identifier
    ["d", "<subject_assertions_id>"],
    
    // REQUIRED `v` tags for discovery and indexing
    ["v", "pov:<pov>"],
    ["v", "type:<type>"],
    
    // REQUIRED output standard reference(s)
    // SHOULD include a v tag for EVERY output standard from service announcement
    // that was used to calculate the assertions in this output event
    // Labels MUST match the labels from service announcement `a` tags
    ["v", "a:37571:<pubkey>:<d_tag>", "<relay_hint?>", "<label?>"],
    
    // OPTIONAL `v` tags to help with discovery of request event
    ["v", "p:<request_author_pubkey>"],
    ["v", "d:<request_id>"],
    
    // REQUIRED single subject being asserted on
    // <type> is the tag letter (config `type`) for this subject
    // <subject> is a unique identifier for this subject
    // <rank> is the rank value for this subject, if available.
    // (if `pov` is a reference to a kind `37573` event, 
    // then this subject tag SHOULD be rendered with it's rank value)
    ["<type>", "<subject>", "<rank?>"],
    
    // REQUIRED assertion outputs (key-value pairs)
    // Each assertion is a tag with the assertion tag name and value.
    // Assertion tag names SHOULD match the labels from the `v:a` tags above.
    // When multiple `v:a` tags share the same label (indicating compatible standards),
    // only ONE assertion tag with that label is rendered.
    // Each unique label from `v:a` tags produces exactly ONE assertion tag in the output.
    ["<assertion_label>", "<assertion_value>"],
    // ... more assertions about this subject
  ]
}

Example Subject Assertions Event:

{
  "kind": 37575,
  "pubkey": "provider123...",
  "tags": [
    ["d", "my_analysis:p:bob123..."],
    ["v", "pov:naddr1..."],
    ["v", "type:p"],
    ["v", "a:37571:alice:follower_count", "wss://relay.example.com", "follower_count"],
    ["v", "a:37571:alice:followers", "wss://relay.example.com", "follower_count"],
    ["v", "a:37571:bob:note_count", "wss://relay.example.com"],
    ["v", "a:37571:bob:engagement_rate", "wss://relay.example.com"],
    ["v", "p:alice123..."],
    ["v", "d:my_analysis"],
    ["p", "bob123...", "83"],
    ["follower_count", "500"],
    ["note_count", "1250"],
    ["engagement_rate", "0.45"]
  ]
}

Service Output : TSM Network Assertions (kind `37576`)

If supported and requested, assertion services SHOULD run all supported Network Assertions output standards (as defined in service announcement) and publish these results to tags in a single addressable event of kind 37576.

{
  "kind": 37576,
  "pubkey": "<service_pubkey> | <subscription_pubkey> | <request_pubkey>",
  "tags": [
    // REQUIRED identifier in format <request_id>:network
    ["d", "<network_assertion_id>"],
    
    // REQUIRED `v` tags for discovery and indexing
    ["v", "pov:<pov>"],
    ["v", "type:<type>"],
    
    // REQUIRED output standard reference(s)
    // SHOULD include `a` keyed `v` tags for EVERY `a` tag in the service announcement
    // that was used to calculate the network assertions in this output event
    // Labels MUST match the labels from service announcement `a` tags
    ["v", "a:37571:<pubkey>:<d_tag>", "<relay_hint?>", "<label?>"],
    
    // OPTIONAL `v` tags to help with discovery of request event
    ["v", "p:<request_author_pubkey>"],
    ["v", "d:<request_id>"],
    
    // REQUIRED network assertion outputs (key-value pairs)
    // Each assertion is a network-wide aggregate value.
    // Assertion tag names SHOULD match the labels from the `a` keyed `v` tags above.
    // When multiple `v:a` tags share the same label (indicating compatible standards),
    // only ONE assertion tag with that label is rendered.
    // Each unique label from `v:a` tags produces exactly ONE assertion tag in the output.
    ["<assertion_label>", "<assertion_value>"],
    // ... more network assertions
  ]
}

Example Network Assertions Event:

{
  "kind": 37576,
  "pubkey": "provider123...",
  "tags": [
    ["d", "my_analysis"],
    ["v", "pov:naddr1..."],
    ["v", "type:p"],
    ["v", "p:alice123..."],
    ["v", "d:my_analysis"],
    ["v", "a:37571:alice:total_users", "wss://relay.example.com", "total_users"],
    ["v", "a:37571:alice:avg_follower_count", "wss://relay.example.com", "avg_follower_count"],
    ["v", "a:37571:bob:median_engagement", "wss://relay.example.com", "median_engagement"],

    
    // Network assertions (provider-defined aggregates)
    ["total_users", "1500"],
    ["avg_follower_count", "287"],
    ["median_engagement_rate", "0.32"]
  ]
}

Appendix 1: Example Implementations

The following are example assertion service implementations that providers MAY offer. Each example shows a Service Announcement with standard configs and provider-specific options.

Example Social Metrics Assertions

This service calculates social metrics (follower counts, engagement rates, etc.) and supports all three output kinds.

Service Announcement:

{
  "kind": 37570,
  "pubkey": "provider123...",
  "tags": [
    ["d", "social_metrics"],
    ["title", "Social Metrics Assertions"],
    ["summary", "Calculates follower counts, engagement rates, and network statistics"],
    ["n", "./tsm-assertion-services.md"],
    
    // Supports all three output kinds
    ["k", "37574"], // Assertions Set
    ["k", "37575"], // Subject Assertions
    ["k", "37576"], // Network Assertions
    
    ["r", "wss://relay.example.com"],
    
    // type is fixed at 'p'
    ["config", "type", "tagletter", "Type of subjects analyzed (fixed at 'p')", "p", "[\"p\"]"],
    // pov is required
    ["config", "pov", "subject|naddr", "Point of view for analysis"],
    
    // provider-specific options
    ["option", "since", "timestamp", "Only consider events after this timestamp", "0"],
    
    // Declare output v tags
    ["V", "type", "tagletter", "Type of subjects in this output"],
    ["V", "pov", "subject|naddr", "Point of view reference"],
    
    // Declare implemented assertion output standards with label grouping
    ["a", "37571:alice:follower_count", "wss://relay.example.com", "follower_count"],
    ["a", "37571:alice:following_count", "wss://relay.example.com", "follower_count"],
    ["a", "37571:bob:note_count", "wss://relay.example.com", "note_count"],
    ["a", "37571:bob:engagement_rate", "wss://relay.example.com", "engagement_rate"],
    
    // Network assertion output standards
    ["a", "37571:alice:total_users", "wss://relay.example.com", "total_users"],
    ["a", "37571:alice:avg_follower_count", "wss://relay.example.com", "avg_follower_count"],
    ["a", "37571:bob:median_engagement", "wss://relay.example.com", "median_engagement"],
    
    // Pagination support for kind 37574
    ["V", "page", "integer", "Page number for paginated Assertions Set"],
    ["info", "pagesize", "1000", "Max subjects per Assertions Set event"],
    
    // Limit on kind 37575 outputs
    ["info", "subject_limit", "1000", "Max subjects for kind 37575 outputs per request"]
  ]
}

Request: All Three Output Kinds

This request demonstrates a single request generating multiple output events of different kinds.

{
  "kind": 37572,
  "pubkey": "alice123...",
  "tags": [
    ["d", "my_analysis"],
    ["k", "37574"], // want Assertions Sets
    ["k", "37575"], // want Subject Assertions
    ["k", "37576"], // want Network Assertions
    ["p", "provider123..."],
    ["a", "37570:provider123...:social_metrics"],
    ["r", "wss://myrelay.example.com"],
    ["config", "pov", "alice123..."]
  ]
}

Output: Assertions Set for follower_count (kind 37574)

{
  "kind": 37574,
  "pubkey": "provider123...",
  "tags": [
    ["d", "my_analysis:follower_count"],
    ["v", "pov:naddr1..."],
    ["v", "type:p"],
    ["v", "a:37571:alice:follower_count", "wss://relay.example.com", "follower_count"],
    ["v", "a:37571:alice:following_count", "wss://relay.example.com", "follower_count"],
    ["v", "p:alice123..."],
    ["v", "d:my_analysis"],
    ["v", "page:1", "[\"my_analysis:follower_count\", \"my_analysis:follower_count:2\"]"],
    ["v", "total:1500"],
    ["p", "bob123...", "500"],
    ["p", "carol123...", "1200"],
    ["p", "dave123...", "87"]
    // ... 997 more subjects (1000 per page)
  ]
}

Output: Subject Assertions for bob (kind 37575)

{
  "kind": 37575,
  "pubkey": "provider123...",
  "tags": [
    ["d", "my_analysis:p:bob123..."],
    ["v", "pov:naddr1..."],
    ["v", "type:p"],
    ["v", "p:alice123..."],
    ["v", "d:my_analysis"],
    ["p", "bob123...", "83"],
    ["follower_count", "500"],
    ["following_count", "320"],
    ["note_count", "1250"],
    ["engagement_rate", "0.45"]
  ]
}

Output: Network Assertions (kind 37576)

{
  "kind": 37576,
  "pubkey": "provider123...",
  "tags": [
    ["d", "my_analysis:network"],
    ["v", "pov:naddr1..."],
    ["v", "type:p"],
    ["v", "a:37571:alice:total_users", "wss://relay.example.com", "total_users"],
    ["v", "a:37571:alice:avg_follower_count", "wss://relay.example.com", "avg_follower_count"],
    ["v", "a:37571:bob:median_engagement", "wss://relay.example.com", "median_engagement"],
    ["v", "p:alice123..."],
    ["v", "d:my_analysis"],
    
    // Network assertions (provider-defined aggregates)
    ["total_users", "1500"],
    ["avg_follower_count", "287"],
    ["median_engagement_rate", "0.32"]
  ]
}

Example Re-Ranking Assertion

This service aggregates ranking from multiple (kind 37573) events and outputs a single assertions set with ranks averaged across all sources. It only outputs kind 37574 events.

Service Announcement:

{
  "kind": 37570,
  "pubkey": "provider456...",
  "tags": [
    ["d", "rerank"],
    ["title", "A Re-Ranking Service"],
    ["summary", "This service aggregates ranking from multiple (kind 37573) events and outputs a single assertions set with ranks averaged across all sources."],
    ["n", "./tsm-assertion-services.md"],
    
    // Only outputs Assertions Set
    ["k", "37574"],
    
    ["r", "wss://relay.example.com"],
    
    // type is fixed at 'p' (pubkeys from ranking outputs)
    ["config", "type", "tagletter", "Type of subjects (fixed at 'p')", "p", "[\"p\"]"],
    
    // pov is required and must be a kind 37573 reference
    ["config", "pov", "naddr", "Reference to kind 37573 ranking output"],
    
    // provider-specific option to accept multiple ranking references
    ["option", "pov", "naddr", "Additional kind 37573 ranking references", ""],
    
    // Declare output v tags
    ["V", "type", "tagletter", "Type of subjects in output"],
    ["V", "pov", "naddr", "Primary ranking reference"],
    
    // Declare implemented output standard for re-ranking
    ["a", "37571:provider456:rerank", "wss://relay.example.com", "rerank"]
  ]
}

Service Request:

{
  "kind": 37572,
  "pubkey": "alice123...",
  "tags": [
    ["d", "my_aggregate_ranks"],
    ["k", "37574"],
    ["p", "provider456..."],
    ["a", "37570:provider456...:rerank"],
    ["r", "wss://myrelay.example.com"],
    
    // Primary ranking reference (required)
    ["config", "pov", "naddr1...ranking_output_1"],
    
    // Additional ranking references (optional)
    ["option", "pov", "naddr1...ranking_output_2"],
    ["option", "pov", "naddr1...ranking_output_3"]
  ]
}

Output: Assertions Set (kind 37574)

{
  "kind": 37574,
  "pubkey": "provider456...",
  "tags": [
    ["d", "my_aggregate_ranks:rerank"],
    ["v", "pov:naddr1...ranking_output_1"],
    ["v", "type:p"],
    ["v", "a:37571:provider456:rerank", "wss://relay.example.com", "rerank"],
    ["v", "p:alice123..."],
    ["v", "d:my_aggregate_ranks"],
    
    // Re-Ranked from multiple kind 37573 sources
    // Assertion tag name matches the label from v:a tag above
    ["p", "bob123...", "95"],
    ["p", "carol123...", "87"],
    ["p", "dave123...", "72"],
    ["p", "eve123...", "68"]
    // ... more subjects with compiled ranks
  ]
}

TSM Assertion Services

TSM Assertion Services

Service Expectations

Service Announcement Events

Assertion Output Standards

Service Request Events

Service Output : TSM Assertions Set (kind 37574)

Service Output : TSM Subject Assertions (kind 37575)

Service Output : TSM Network Assertions (kind 37576)

Appendix 1: Example Implementations

Example Social Metrics Assertions

Example Re-Ranking Assertion

Service Output : TSM Assertions Set (kind `37574`)

Service Output : TSM Subject Assertions (kind `37575`)

Service Output : TSM Network Assertions (kind `37576`)