Nostr Event Builder

Overview

Construct correct Nostr event structures from natural language descriptions. This skill handles the non-obvious parts: choosing the right kind, building proper tag arrays with correct markers, enforcing NIP-10 vs NIP-22 threading rules, and producing valid event JSON ready for signing.

When to Use

• Developer describes what they want to publish on Nostr
• Building reply threads (NIP-10 kind:1 replies)
• Commenting on non-note content (NIP-22 kind:1111 comments)
• Creating or updating user profiles (kind:0 metadata)
• Constructing any Nostr event and unsure about tag structure
• Debugging malformed events (wrong markers, missing tags)

Do NOT use when:

• Implementing relay WebSocket logic (that's relay protocol, not event building)
• Working with NIP-19 encoding/decoding (bech32 concerns, not event structure)
• Building subscription filters (REQ messages, not EVENT messages)

Workflow

1. Identify the Event Kind

Ask: "What is the developer trying to publish?"

Intent	Kind	Category	Key NIP
Post a short text note	1	Regular	NIP-10
Reply to a kind:1 note	1	Regular	NIP-10
Comment on non-kind:1 content	1111	Regular	NIP-22
Set/update user profile	0	Replaceable	NIP-01
Update follow list	3	Replaceable	NIP-02
Delete events	5	Regular	NIP-09
Repost a note	6	Regular	NIP-18
React to an event	7	Regular	NIP-25
Publish a long-form article	30023	Addressable	NIP-23

See references/event-kinds.md for full kind-to-structure mapping.

Critical routing rule:

Is the target a kind:1 note?
  YES → Use kind:1 reply with NIP-10 e-tag markers
  NO  → Use kind:1111 comment with NIP-22 uppercase/lowercase tags

2. Build the Tag Array

Tags are the hardest part. Follow the tag guide for your kind:

For kind:1 replies (NIP-10):

Direct reply to root (no intermediate replies):

{
  "kind": 1,
  "tags": [
    ["e", "<root-event-id>", "<relay-url>", "root", "<root-author-pubkey>"],
    ["p", "<root-author-pubkey>"]
  ],
  "content": "Your reply text"
}

Reply to a reply in a thread:

{
  "kind": 1,
  "tags": [
    ["e", "<root-event-id>", "<relay-url>", "root", "<root-author-pubkey>"],
    [
      "e",
      "<parent-event-id>",
      "<relay-url>",
      "reply",
      "<parent-author-pubkey>"
    ],
    ["p", "<root-author-pubkey>"],
    ["p", "<parent-author-pubkey>"]
  ],
  "content": "Your reply text"
}

For kind:1111 comments (NIP-22):

Top-level comment on a regular event:

{
  "kind": 1111,
  "tags": [
    ["E", "<root-event-id>", "<relay-url>", "<root-author-pubkey>"],
    ["K", "<root-event-kind>"],
    ["P", "<root-author-pubkey>", "<relay-url>"],
    ["e", "<root-event-id>", "<relay-url>", "<root-author-pubkey>"],
    ["k", "<root-event-kind>"],
    ["p", "<root-author-pubkey>", "<relay-url>"]
  ],
  "content": "Your comment text"
}

Top-level comment on an addressable event (kind 30000-39999):

{
  "kind": 1111,
  "tags": [
    ["A", "<kind>:<pubkey>:<d-tag>", "<relay-url>"],
    ["K", "<root-event-kind>"],
    ["P", "<root-author-pubkey>", "<relay-url>"],
    ["a", "<kind>:<pubkey>:<d-tag>", "<relay-url>"],
    ["e", "<event-id>", "<relay-url>"],
    ["k", "<root-event-kind>"],
    ["p", "<root-author-pubkey>", "<relay-url>"]
  ],
  "content": "Your comment text"
}

Comment on a URL or external identifier:

{
  "kind": 1111,
  "tags": [
    ["I", "<url-or-identifier>"],
    ["K", "<identifier-type>"],
    ["i", "<url-or-identifier>"],
    ["k", "<identifier-type>"]
  ],
  "content": "Your comment text"
}

Reply to an existing comment:

{
  "kind": 1111,
  "tags": [
    ["E", "<original-root-event-id>", "<relay-url>", "<root-author-pubkey>"],
    ["K", "<original-root-kind>"],
    ["P", "<root-author-pubkey>"],
    [
      "e",
      "<parent-comment-id>",
      "<relay-url>",
      "<parent-comment-author-pubkey>"
    ],
    ["k", "1111"],
    ["p", "<parent-comment-author-pubkey>"]
  ],
  "content": "Your reply to the comment"
}

See references/tag-guide.md for complete tag semantics.

3. Set the Content Field

Content format depends on the kind:

Kind	Content Format
0	Stringified JSON: {"name":"...","about":"...","picture":"..."}
1	Plaintext (no markdown, no HTML)
5	Optional deletion reason text
6	Stringified JSON of the reposted event
7	+ (like), - (dislike), or emoji
1111	Plaintext comment
30023	Markdown-formatted article body

4. Construct the Complete Event

Assemble the unsigned event object:

{
  "pubkey": "<32-bytes-lowercase-hex-public-key>",
  "created_at": "<unix-timestamp-seconds>",
  "kind": "<integer>",
  "tags": [["..."]],
  "content": "<string>"
}

The id is computed as SHA-256 of the serialized form:

[0, "<pubkey>", <created_at>, <kind>, <tags>, "<content>"]

Serialization rules:

• UTF-8 encoding, no whitespace/formatting
• Escape in content: \n, \", \\, \r, \t, \b, \f
• All other characters verbatim

The sig is a Schnorr signature (secp256k1) of the id.

5. Validate Before Signing

Checklist before the event is ready:

• [ ] kind is correct for the intent
• [ ] All required tags present for this kind
• [ ] e tags have correct markers (root/reply for kind:1)
• [ ] p tags include ALL participants in the thread
• [ ] NIP-10 kind:1 replies only target other kind:1 events
• [ ] NIP-22 kind:1111 comments do NOT target kind:1 events
• [ ] K and k tags present for kind:1111 comments
• [ ] Uppercase tags (E/A/I/K/P) point to root scope in kind:1111
• [ ] Lowercase tags (e/a/i/k/p) point to parent item in kind:1111
• [ ] content format matches the kind's requirements
• [ ] created_at is a Unix timestamp in seconds (not milliseconds)
• [ ] All hex values are 32-byte lowercase

Common Mistakes

Mistake	Why It Breaks	Fix
Using kind:1 to reply to a kind:30023 article	NIP-10 kind:1 replies MUST only reply to other kind:1 events	Use kind:1111 (NIP-22 comment) for non-kind:1 targets
Using kind:1111 to reply to a kind:1 note	NIP-22 comments MUST NOT reply to kind:1	Use kind:1 with NIP-10 e-tag markers
Missing root marker on e tags in kind:1	Clients can't reconstruct the thread tree	Always use marked e tags: ["e", "<id>", "<relay>", "root"]
Only one e tag with reply marker (no root)	Direct replies to root need root marker, not reply	Single e tag = use root marker only
Missing p tags for thread participants	Users don't get notified of replies	Include p tags for ALL pubkeys in the thread
Lowercase e/k/p tags for root scope in kind:1111	Root scope MUST use uppercase E/K/P tags	Uppercase = root scope, lowercase = parent item
Missing K or k tags in kind:1111	Both are REQUIRED by NIP-22	Always include ["K", "<root-kind>"] and ["k", "<parent-kind>"]
created_at in milliseconds	Nostr uses seconds, not milliseconds	Use Math.floor(Date.now() / 1000)
Content as object instead of string for kind:0	Content must be stringified JSON	Use JSON.stringify({name: "...", ...})
Missing d tag on addressable events (30000-39999)	Relay can't address the event properly	Always include ["d", "<identifier>"]
Positional e tags without markers	Deprecated; creates ambiguity in thread reconstruction	Always use marked e tags with root/reply

Kind Category Quick Reference

Range	Category	Behavior
1000-9999, 4-44, 1, 2	Regular	Stored by relays, all kept
10000-19999, 0, 3	Replaceable	Latest per pubkey+kind kept
20000-29999	Ephemeral	Not stored by relays
30000-39999	Addressable	Latest per pubkey+kind+d-tag kept

Example: Complete Event Construction

User says: "I want to reply to my friend's note in an existing thread"

Step 1 — Identify kind: Replying to a kind:1 note → use kind:1 (NIP-10)

Step 2 — Determine thread position: This is a reply to a reply (not the root), so we need both root and reply e tags.

Step 3 — Build the event:

{
  "pubkey": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
  "created_at": 1709827200,
  "kind": 1,
  "tags": [
    ["e", "aaa111...", "wss://relay.example.com", "root", "f7234bd4..."],
    ["e", "bbb222...", "wss://relay.example.com", "reply", "93ef2eba..."],
    ["p", "f7234bd4...", "wss://relay.example.com"],
    ["p", "93ef2eba...", "wss://relay.example.com"]
  ],
  "content": "Great point! I totally agree with this take."
}

Step 4 — Validate: Root e tag has root marker ✓, reply e tag has reply marker ✓, p tags include both the root author and the parent author ✓, content is plaintext ✓.