NOSTR Event Anatomy

The expected form of all NOSTR events transferred from, to, and within the wallet provider is as follows (re. NIP-01: Basic Protocol Flow Description (opens in a new tab)):

{
  "id": "{32-bytes lowercase hex-encoded event ID}",
  "pubkey": "{32-bytes lowercase hex-encoded public key of the event's SIGNER}",
  "created_at": {UNIX timestamp in seconds},
  "kind": {1111|21111|31111},
  "tags": [
    [
      "k",
      "{event sub-kind}"
    ],
    [
      "p",
      "{32-bytes lowercase hex-encoded public key of the event's TARGET}"
    ],
    [
      "alt",
      "{human-readable description of the event}"
    ],
    [
      "delegation",
      "{32-bytes lowercase hex-encoded public key of the event's AUTHOR}",
      "{conditions query string: 'kind={.kind}&created_at>{UNIX timestamp lower limit in seconds}&created_at<{UNIX timestamp upper limit in seconds}'}",
      "{delegation token: 64-byte lowercase hex-encoded Schnorr signature of the SHA256 hash of 'nostr:delegation:{value of the .pubkey field}:{conditions query string}' using the AUTHOR's secret key}"
    ],
    [
      "d",
      "{event sub-kind}:{identifier}"
    ],
    {additional tags may follow}
  ],
  "content": "{stringified JSON content}",
  "sig": "{64-byte lowercase hex-encoded Schnorr signature of the event's .id field using the SIGNER's secret key}"
}

The .created_at timestamp MUST be within 10 seconds of the Local NOSTR Relay's current timestamp (cf. NIP-22: Event created_at Limits (opens in a new tab)).

The "k" tag marks what specific event sub-kind this event refers to. Note how a single .kind is reserved, multiplexing sub-kinds based off of the value of the "k" tag. The actual value of the "k" tag need not be an "integer string" and may instead be an arbitrary string (hopefully bearing some mnemonic meaning itself). This tag is REQUIRED and MUST NOT be repeated.

At least one "p" tag MUST be provided, and these tags SHOULD NOT be repeated.

The "alt" tag is prescribed in accordance to NIP-31: Dealing with Unknown Event Kinds (opens in a new tab). This tag is OPTIONAL and MUST NOT be repeated.

The "delegation" tag follows the guidelines exposed in NIP-26: Delegated Event Signing (opens in a new tab). This tag is OPTIONAL and MUST NOT be repeated.

The "d" tag MUST ONLY be present when the event's .kind is 31111. If present, it must consist of the event sub-kind (ie. the value associated to the "k" tag), followed by a colon (ie. :), followed by whatever the actual identifier is to be (this is so that we can keep using a single kind to refer to all parameterized replaceable events).

The "d" and "delegation" tags are mutually exclusive. This directly implies that no event with a .kind of 31111 may be delegated.

The .content field MUST be a (properly escaped) stringified JSON object itself.

Kinds and Sub-Kinds

Notice how we reserve just 3 event kinds for usage:

• 1111: this is a regular event, expected ot be stored by relays.
• 21111: this is an ephemeral event, not expected to be actually stored by relays.
• 31111: this is a parameterized replaceable event, expected to replace any other event with the same kind (ie. 31111), .pubkey, and "d" tag value (notice how, because our "d" tag values are prescribed to contain the {event sub-kind}: prefix, event sub-kinds are also taken into consideration).

Event's AUTHOR, SIGNER, and TARGETs

A NOSTR event is expected to define three related entities:

• The event's SIGNER: is the entity actually signing the NOSTR event proper, filling in the .pubkey and .signature fields.
• The event's AUTHOR: is the entity on behalf of whom the NOSTR event is being created, found on index 1 of the "delegation" tag's content. If there's no "delegation" tag, then the event's AUTHOR is the event's SIGNER.
• The event's TARGETs: are the entities to which the NOSTR event should be routed, these are found on index 1of each "p" tag.

In what follows we'll simply refer to an event's AUTHOR, SIGNER, and TARGETs as defined above, and refrain from referring to specific event fields or tag values or indices.