NIP-32: 標籤系統

概述

NIP-32 定義了一套標籤系統，允許用戶為事件、人物、中繼器、地址和主題添加結構化的分類標籤。 這個系統支援多種命名空間，讓不同的應用場景（如內容審核、分類、評級等）可以使用統一的標籤機制。

標籤事件結構

標籤事件使用 kind 1985，包含命名空間和標籤值：

命名空間

命名空間用於區分不同來源和用途的標籤。建議使用明確的標識符：

使用範例

標記事件語言

{
  "kind": 1985,
  "tags": [
    ["L", "ISO-639-1"],
    ["l", "zh", "ISO-639-1"],
    ["e", "<event-id>", "wss://relay.example.com"]
  ],
  "content": ""
}

內容分類標籤

{
  "kind": 1985,
  "tags": [
    ["L", "com.example.content-type"],
    ["l", "news", "com.example.content-type"],
    ["l", "technology", "com.example.content-type"],
    ["e", "<event-id>", "wss://relay.example.com"]
  ],
  "content": "這是一篇科技新聞相關的貼文"
}

用戶生成標籤（UGC）

{
  "kind": 1985,
  "tags": [
    ["L", "ugc"],
    ["l", "有趣", "ugc"],
    ["l", "推薦", "ugc"],
    ["e", "<event-id>", "wss://relay.example.com"]
  ],
  "content": ""
}

標記用戶（身份標籤）

{
  "kind": 1985,
  "tags": [
    ["L", "com.example.trust"],
    ["l", "verified", "com.example.trust"],
    ["p", "<pubkey>", "wss://relay.example.com"]
  ],
  "content": "此用戶已通過身份驗證"
}

標記中繼器

{
  "kind": 1985,
  "tags": [
    ["L", "com.example.relay-type"],
    ["l", "paid", "com.example.relay-type"],
    ["l", "fast", "com.example.relay-type"],
    ["r", "wss://premium.relay.example.com"]
  ],
  "content": ""
}

自我標記

除了使用 kind 1985 標籤事件外，也可以在其他事件中直接添加 L 和 l 標籤進行自我標記：

// 自我標記的貼文（kind 1）
{
  "kind": 1,
  "tags": [
    ["L", "ISO-639-1"],
    ["l", "en", "ISO-639-1"],
    ["L", "#t"],
    ["l", "bitcoin", "#t"],
    ["t", "bitcoin"]
  ],
  "content": "Bitcoin is the future of money!"
}

TypeScript 實作

import { finalizeEvent, generateSecretKey, getPublicKey } from 'nostr-tools'

// 標籤命名空間常量
const NAMESPACES = {
  UGC: 'ugc',
  LANGUAGE: 'ISO-639-1',
  CONTENT_TYPE: 'com.example.content-type',
  TRUST: 'com.example.trust',
} as const

interface LabelTarget {
  type: 'event' | 'pubkey' | 'relay' | 'address' | 'topic'
  value: string
  relayHint?: string
}

interface LabelData {
  namespace: string
  labels: string[]
  target: LabelTarget
  content?: string
}

// 創建標籤事件
function createLabelEvent(
  data: LabelData,
  secretKey: Uint8Array
): object {
  const tags: string[][] = []

  // 添加命名空間
  tags.push(['L', data.namespace])

  // 添加標籤值
  for (const label of data.labels) {
    tags.push(['l', label, data.namespace])
  }

  // 添加目標
  switch (data.target.type) {
    case 'event':
      tags.push(['e', data.target.value, data.target.relayHint || ''])
      break
    case 'pubkey':
      tags.push(['p', data.target.value, data.target.relayHint || ''])
      break
    case 'relay':
      tags.push(['r', data.target.value])
      break
    case 'address':
      tags.push(['a', data.target.value])
      break
    case 'topic':
      tags.push(['t', data.target.value])
      break
  }

  const event = {
    kind: 1985,
    created_at: Math.floor(Date.now() / 1000),
    tags,
    content: data.content || '',
  }

  return finalizeEvent(event, secretKey)
}

// 標記事件語言
function labelEventLanguage(
  eventId: string,
  languageCode: string,
  relayHint: string,
  secretKey: Uint8Array
): object {
  return createLabelEvent({
    namespace: NAMESPACES.LANGUAGE,
    labels: [languageCode],
    target: {
      type: 'event',
      value: eventId,
      relayHint,
    },
  }, secretKey)
}

// 標記用戶信任等級
function labelUserTrust(
  pubkey: string,
  trustLevel: string,
  relayHint: string,
  secretKey: Uint8Array
): object {
  return createLabelEvent({
    namespace: NAMESPACES.TRUST,
    labels: [trustLevel],
    target: {
      type: 'pubkey',
      value: pubkey,
      relayHint,
    },
  }, secretKey)
}

// 用戶生成標籤
function createUGCLabel(
  eventId: string,
  labels: string[],
  relayHint: string,
  secretKey: Uint8Array
): object {
  return createLabelEvent({
    namespace: NAMESPACES.UGC,
    labels,
    target: {
      type: 'event',
      value: eventId,
      relayHint,
    },
  }, secretKey)
}

// 為自己的貼文添加自我標記
function createSelfLabeledNote(
  content: string,
  language: string,
  topics: string[],
  secretKey: Uint8Array
): object {
  const tags: string[][] = []

  // 語言標籤
  tags.push(['L', NAMESPACES.LANGUAGE])
  tags.push(['l', language, NAMESPACES.LANGUAGE])

  // 主題標籤
  if (topics.length > 0) {
    tags.push(['L', '#t'])
    for (const topic of topics) {
      tags.push(['l', topic, '#t'])
      tags.push(['t', topic])
    }
  }

  const event = {
    kind: 1,
    created_at: Math.floor(Date.now() / 1000),
    tags,
    content,
  }

  return finalizeEvent(event, secretKey)
}

// 使用範例
const sk = generateSecretKey()

// 標記事件語言為中文
const languageLabel = labelEventLanguage(
  'abc123...',
  'zh',
  'wss://relay.example.com',
  sk
)

// 標記用戶為已驗證
const trustLabel = labelUserTrust(
  'pubkey123...',
  'verified',
  'wss://relay.example.com',
  sk
)

// 用戶生成標籤
const ugcLabel = createUGCLabel(
  'event456...',
  ['有趣', '推薦', '必讀'],
  'wss://relay.example.com',
  sk
)

// 創建帶自我標記的貼文
const selfLabeledNote = createSelfLabeledNote(
  'Bitcoin 是未來的貨幣！',
  'zh',
  ['bitcoin', 'cryptocurrency'],
  sk
)

查詢標籤

import { SimplePool } from 'nostr-tools'

const pool = new SimplePool()
const relays = ['wss://relay.example.com']

// 查詢特定事件的所有標籤
async function getLabelsForEvent(eventId: string) {
  const labels = await pool.querySync(relays, {
    kinds: [1985],
    '#e': [eventId],
  })
  return labels
}

// 查詢特定命名空間的標籤
async function getLabelsByNamespace(namespace: string) {
  const labels = await pool.querySync(relays, {
    kinds: [1985],
    '#L': [namespace],
  })
  return labels
}

// 查詢特定標籤值
async function getEventsByLabel(label: string, namespace?: string) {
  const filter: any = {
    kinds: [1985],
    '#l': [label],
  }

  if (namespace) {
    filter['#L'] = [namespace]
  }

  const labels = await pool.querySync(relays, filter)
  return labels
}

// 查詢某用戶的所有標籤
async function getLabelsForUser(pubkey: string) {
  const labels = await pool.querySync(relays, {
    kinds: [1985],
    '#p': [pubkey],
  })
  return labels
}

// 查詢中文內容
async function getChineseContent() {
  const labels = await pool.querySync(relays, {
    kinds: [1985],
    '#L': ['ISO-639-1'],
    '#l': ['zh'],
  })

  // 提取被標記的事件 ID
  const eventIds = labels
    .flatMap(l => l.tags.filter(t => t[0] === 'e').map(t => t[1]))

  // 獲取實際事件
  if (eventIds.length > 0) {
    return await pool.querySync(relays, {
      ids: eventIds,
    })
  }

  return []
}

// 解析標籤事件
function parseLabels(event: any): {
  namespace: string
  labels: string[]
  targets: { type: string; value: string }[]
} {
  const namespaceTags = event.tags.filter((t: string[]) => t[0] === 'L')
  const labelTags = event.tags.filter((t: string[]) => t[0] === 'l')

  const namespace = namespaceTags[0]?.[1] || 'ugc'
  const labels = labelTags.map((t: string[]) => t[1])

  const targets: { type: string; value: string }[] = []
  for (const tag of event.tags) {
    if (tag[0] === 'e') targets.push({ type: 'event', value: tag[1] })
    if (tag[0] === 'p') targets.push({ type: 'pubkey', value: tag[1] })
    if (tag[0] === 'r') targets.push({ type: 'relay', value: tag[1] })
    if (tag[0] === 'a') targets.push({ type: 'address', value: tag[1] })
    if (tag[0] === 't') targets.push({ type: 'topic', value: tag[1] })
  }

  return { namespace, labels, targets }
}

應用場景

最佳實踐

相關 NIP

總結