TRUSTed Filter Presets

TRUSTed Filter Presets

nip-trusted-filter-presets

draft

extends nip-trusted-filters

kind 37570 "TRUSTed Filter Preset" d

This NIP defines a "TRUSTed Filter Preset" event kind and additional specifications to allow TRUSTed Filters to be saved as and executed from published Nostr events.

It specifies how :

• users may publish their own presets to be shared across services
• presets MAY be encrypted for private or restricted access
• users may embed a referenced preset event in a TRUST message.
• services may indicate specific supported presets in their TRUST ping responses

Preset Events

TRUSTed Filter Preset events MAY be published by any (subscriber) pubkey as a public or restricted (encrypted) preset, OR by trust providers (via subscription pubkey) as a default preset (encrypted or not). Encrypted presets SHOULD be able to be decrypted by BOTH of a subscriber's subscriber_pubkey and subscription_pubkey (using NIP-04), and MUST have an r tag indicating the provider relay(s) where this preset can be decrypted and executed.

Format:

{
  "kind": 37570,
  "pubkey": "<subscriber_pubkey> | <subscription_pubkey>",
  // content is a JSON array of filter configs
  // content MAY be encrypted using the NIP-04 standard, 
  // with either the `subscriber` or `subscription` pubkey as the sender
  // and the other as the recipient.
  "content": "[<trusted_filter_json>, ...]",
  "tags": [
    // Required d tag identifies this filter preset
    ["d", "<preset_id>"],
    // Optional uppercase `W` tags in the preset event
    // MAY advertise input parameters from the request's `W` namespace
    // These SHOULD each contain a key, a TypeDescriptor, and an optional required flag
    ["W", "<key>", "<TypeDescriptor>", "<required?>"],
    // Optional lowercase `w` tags in the preset event
    // MAY advertise output values from the request's `w` namespace
    ["w", "<key>"],
    // Optional `k` tag(s) advertise a single event kind returned by this filter
    ["k", "<event_kind>"],
    // Optional `r` tag(s) indicate a single relay where this preset MAY be executed 
    // which MAY be useful if the content is encrypted.
    ["r", "<relay_url>", ...],
  ]
}

Direct Execution by Reference in TRUST Requests

Trust Services supporting this NIP SHOULD allow presets to be executed directly via TRUST request messages. These presets SHOULD be referenced in JSON stringified arrays, where the first element is a NIP-19 event reference (naddr or nevent) pointing to a published kind 37570 preset filter event. Additional (optional) elements are <key>:<value> strings that provide input values for any W namespace parameters expected by the TRUSTed Filter(s) in this preset event.

Format:

["TRUST", "<subscription_pubkey>", "<session_id>", 
 // Preset References are JSON stringified arrays 
  [ 
    "<naddr_to_preset_event>",
    "<key>:<value>", 
    ...
  ],
  // any number of TRUSTed Filters or Preset References may be added
  // ...
]

Execution:

Filters referenced in this manner MAY be grouped with other filters, which SHOULD ALL be considered part of the same TRUST request. As such,

• Referenced filters SHOULD be executed in order with other filters in the same request.
• If a referenced filter has plugins NOT supported by the service provider, the ENTIRE request SHOULD be rejected.
• The scope of W and w namespaces SHOULD be preserved across ALL (referenced and specific) filters in this request.

Indirect Execution by Requesting TRUSTed Events

Trust Services supporting this NIP MAY allow presets to be executed indirectly via TRUSTed Event requests. Such filters SHOULD include (uppercase) W tags to reference the preset event and to specify input parameters. In order to trigger event generation when requesting any ONE kind of TRUSTed Event, EXACTLY ONE W tag MUST be a NIP-19 reference (naddr or nevent) pointing to a published kind 37570 preset filter event. ANY NUMBER OF additional W tags MAY specify a <key>:<value> string as input value for any W namespaced key specified in the preset event.

Format:

[ "TRUST", "<subscription_pubkey>", "<session_id>",
  // TRUSTed Filters are JSON stringified objects
  {
    "kind": [<trusted_event_kind>],
    "#W": [
      "<naddr_to_preset_event>",
      "<key>:<value>",
      ...
    ]
  }
  // any number of TRUSTed Filters or Preset References may be added
  // ...
]

Execution:

• Indirect execution SHOULD be attempted (if supported by provider/subscription) WHENEVER #W tags are present in a filter requesting a supported kind.
• Filters executed in this manner SHOULD return a single kind of TRUSTed Event, or no results.

Service Provider Support

Service providers supporting this NIP MAY add a presets key to their TRUST ping responses AND Relay Information Document sent to connected clients. This MAY prove useful for service providers who ONLY want to support their own presets (not arbitrary filters) in TRUST messages. (in this case plugins would be an empty array)

The presets key SHOULD contain an array with ONE of the following:

• a single string "none", indicating that presets are NOT supported OR
• a single string "any", indicating that ANY preset is supported for direct execution OR
• one or more NIP-19 event references (naddr or nevent) pointing to supported kind 37570 preset filter events.

The kinds key SHOULD contain an array with ONE of the following:

• a single string "none", indicating that indirect execution is NOT supported OR
• a single string "any", indicating that ANY event kind is supported for indirect execution OR
• one or more TRUSTed Event kind numbers supported for indirect execution.

**Updated format for TRUST ping response:**

{
  "TRUST" : {
    "plugins?": [...],
    "only?": [...],
    "not?": [...],
    // Services MAY specify presets supported by this service
    // Array contains EITHER "none", "any", OR one or more naddr/nevent references
    "presets?": ["none"] | ["any"] | ["<naddr_to_preset_event>", ...],
    // Services MAY specify supported TRUSTed Event kinds 
    // for requesting *indirect* execution of presets
    // Array contains EITHER "none", "any", OR one or more kind numbers
    "kinds?": ["none"] | ["any"] | [<trusted_event_kind>, ...],
  },
  },
}