TRUSTed Ranking of Users

TRUSTed Ranking of Users

nip-trusted-users

draft

extends nip-trusted-filters

extends nip-trusted-events

This NIP specifies the rank_interpret and rank_calculate plugins, as a drop-in replacement for the rank plugin (specified in nip-trusted-events) for calculating pubkey ranks based on interpreted user interactions from across the network. These two plugins work together as a two-stage ranking system, enabling sophisticated ranking algorithms that consider multiple types of interactions with configurable weights and conditions.

Required W Plugin inputs:

These inputs are required (in ONE filter) for all requests that use the rank_interpret and rank_calculate plugins.

• pov:<pov_pubkey> : pubkey from which rankings are calculated
• context:<context_string> : identifier for this ranked list
• type:<tag_letter> : tag type for subjects being ranked (usually "p")

Rank Interpret Plugin

**rank_interpret* - Interprets any user interactions* (follows, mutes, reports, etc.) from a single set of filtered events. Multiple filters in a request may be used to interpret different types of interactions, each with an instance of rank_interpret plugin.

Terminology:

• actor - The user who initiated the interaction (usually the event author)
• subject - The user being interacted with (extracted from event tags)
• weight - A numeric (-1 to 1) value for interpreting each interaction
• if - A condition of the event that must be met for the interpretation to be applied

Function Signature:

{
  "plugins": [
    ["rank_interpret", 
      ["<actor>", "<subject>", "<weight>", "<if_path?>", "<if_value?>"]
      // ... multiple interpretation rules
    ]
  ]
}

Function Arguments:

1. <actor> : EventPath : (required) : An EventPath to extract the actor pubkey from the interaction event (eg: "pubkey" for event author)
2. <subject> : EventPath : (required) : An EventPath to extract the subject pubkey from the interaction event (eg: "#p[][1]" for pubkeys in all p tags)
3. <weight> : +-0-1 : (required) : A float from -1 to 1 representing interaction weight
4. Positive values (0 to 1): favorable interactions (eg : for follows, zaps, etc.)
5. Negative values (-1 to 0): unfavorable interactions (eg : for mutes, reports, etc.)
6. <if_path> : EventPath : (optional) : An EventPath from which to extract the if_value of the condition (MAY be specified in relation to subject path. eg: #[3] == #[p][][3])
7. <if_value> : string : (optional) : A value for condition which must be met to apply this interpretation.

Plugin Behavior:

1. For each filtered event, extracts actor and subject using specified EventPaths
2. Interpretation only applies when <if_path> matches <if_value> (if specified)
3. Stores interpretation data in IO.rank_interpret namespace accessible ONLY to rank_calculate plugins in the same request.
4. Accumulates ALL interpretations across ALL rank_interpret calls in the request.
5. Data is passed to rank_calculate plugins in the same request.

Rank Calculate Plugin

**rank_calculate** - Aggregates all interpretations from all rank_interpret plugins in previous filters (of a single request) and calculates final rank values (0-100) for each user that was interacted with. The calculated ranks are stored in the IO.#.p namespace as an array of value arrays : ["<pubkey>", "<relay_hint>", "", "<rank>"].

Function Signature:

{
  "plugins": [
    // just including the calculate plugin 
    // SHOULD trigger calculation of ranks
    ["rank_calculate", 
    // any number of calculator params may be added
    // as specified by the service provider
      ["<param_key>","<param_value>"],
      // ...  
    ]
  ]
}

Plugin Behavior:

1. Aggregates ALL interpretation data from ALL rank_interpret calls in the request
2. Applies ranking algorithm to calculate final rank values (0-100 integer) for each user
3. Reads io.W value of type key (provided by W input)
4. Adds ["<subject>", "<relay_hint>", "", "<rank>"] to io["#<type>"][] for each ranked user
5. The # prefix indicates preference for rendering as tags
6. outputs to io namespace

Complete Example

Request:

["TRUST", "<subscription_pubkey>", "<session_id>", 
  // Filter 1: Collect follows (positive weight)
  {
    "kinds": [3],
    "authors": ["${pov}"],
    "plugins": [
      ["rank_interpret", ["pubkey", "#p[][1]", "1"]]
    ]
  },
  // Filter 2: Collect mutes (negative weight)
  {
    "kinds": [10000],
    "authors": "${follows_network}",
    "plugins": [
      ["rank_interpret", ["pubkey", "#p[][1]", "-1"]]
    ]
  },
  // Filter 3: Collect reports (conditional negative weights)
  {
    "kinds": [1984],
    "authors": "${follows_network}",
    "plugins": [
      ["rank_interpret", 
        ["pubkey", "#p[][1]", "-1", "#[2]", "impersonation"],
        ["pubkey", "#p[][1]", "-0.5", "#[2]", "spam"]
      ]
    ]
  },
  // Filter 4: Calculate and publish rankings
  {
    "W": [
      ["pov", "<alice_pubkey>"],
      ["context", "follows_network"],
      ["type", "p"]
    ],
    "transformers": [
      ["rank_calculate", 
        ["rigor", "0.8"]
      ],
      ["sort", ["#p", "#[3]", "desc"]],
      ["publish", ["37573"]]
    ]
  }
]

Generated Event:

{
  "kind": 37573,
  "pubkey": "<subscription_pubkey>",
  "tags": [
    ["d", "<service_generated_id>"],
    ["W", "pov:<alice_pubkey>"],
    ["W", "context:follows_network"],
    ["W", "type:p"],
    ["p", "user_pubkey_1", "", "", "95"],
    ["p", "user_pubkey_2", "", "", "87"],
    ["p", "user_pubkey_3", "", "", "73"]
  ]
}

Relationship to TRUSTed Assertions

The rank_interpret and rank_calculate plugins provide an advanced implementation pattern for the rank plugin specified in nip-trusted-assertions. While nip-trusted-assertions defines a simple rank plugin for basic ranking, this NIP provides a sophisticated two-stage system for complex network-based rankings.

Service providers MAY support either or both patterns depending on their use cases.