Struct EventBuilder 

#[non_exhaustive]
pub struct EventBuilder { /* private fields */ }

Fluent builder for UnsignedEvent / Event.

The four constituents — kind, content, tags, created_at — are private by design: callers must go through the builder methods to mutate them. The reason is twofold:

1. NIP-46 / NIP-59 (gift wrap) compose builders that produce encrypted content derived from a particular (kind, tags) snapshot. Letting outer code reach in and rewrite, say, kind after the inner ciphertext was sealed would silently corrupt the event without the type system noticing.
2. Keeping the surface fluent (builder.kind(K).tag(t).content(c)) means downstream code never has to know whether a field is String vs Cow<'_, str> vs &str — we can change the storage type freely without breaking callers.

The struct is #[non_exhaustive] so future versions may add configuration fields (PoW search budget, dedup toggles, mining-aux nonce cache, …) without breaking downstream pattern matches.

Implementations

impl EventBuilder

pub fn new<S>(kind: Kind, content: S) -> Self

where S: Into<String>,

Construct a builder with the given kind and content.

pub fn text_note<S>(content: S) -> Self

where S: Into<String>,

Build a Kind::TEXT_NOTE event (NIP-01) with the supplied content.

pub const fn current_kind(&self) -> Kind

Read-only accessor for the event kind.

pub fn current_content(&self) -> &str

Read-only accessor for the event content.

pub const fn current_tags(&self) -> &Tags

Read-only accessor for the event tags.

pub const fn current_created_at(&self) -> Option<Timestamp>

Read-only accessor for the explicitly pinned created_at.

None means “use the wall clock at sign time”.

pub const fn tags_mut(&mut self) -> &mut Tags

Mutable accessor for the in-progress tag list.

Use this when a tag insertion needs custom logic (deduplication, uniqueness, replace-or-push) that the fluent Self::tag / Self::tags helpers do not cover. The fluent methods remain the preferred surface for plain appends.

pub const fn kind(self, kind: Kind) -> Self

Set the event kind (overrides any previously set value).

pub fn content<S>(self, content: S) -> Self

where S: Into<String>,

Replace the event content.

pub fn tag(self, tag: Tag) -> Self

Append a single tag.

pub fn tags<I>(self, tags: I) -> Self

where I: IntoIterator<Item = Tag>,

Append several tags from any iterator.

pub const fn created_at(self, ts: Timestamp) -> Self

Pin a custom created_at.

Useful when re-signing historical events or backfilling fixtures.

pub fn build_unsigned( self, pubkey: PublicKey, ) -> Result<UnsignedEvent, EventBuilderError>

Build the UnsignedEvent but do not sign it.

pubkey becomes the pubkey field. The created_at field is taken from the builder if set, otherwise from the system clock.

Errors

Returns EventBuilderError::Clock if the wall clock could not be read.

pub fn sign_with_keys(self, keys: &Keys) -> Result<Event, EventBuilderError>

Build and sign with keys in one shot.

Errors

Returns EventBuilderError::Clock if the wall clock could not be read or EventBuilderError::Signer if signing fails (it cannot, in the local-keys case).

impl EventBuilder

pub fn metadata(metadata: &Metadata) -> Result<Self, Error>

Construct an EventBuilder for a kind: 0 profile event whose content is the JSON serialization of metadata.

Errors

Returns a serde_json error if metadata cannot be serialized.

impl EventBuilder

pub fn contact_list(list: &ContactList) -> Self

Build a kind: 3 contact list event from list.

The event’s content is empty per the modern interpretation of NIP-02 (the legacy relay JSON is replaced by NIP-65).

impl EventBuilder

pub fn deletion(request: &DeletionRequest) -> Self

Build a kind: 5 deletion event from the given DeletionRequest.

impl EventBuilder

pub fn note_with_context<S: Into<String>>( content: S, context: &ThreadContext, ) -> Self

Build a kind: 1 text note carrying the supplied ThreadContext (i.e. a NIP-10 reply or mention).

impl EventBuilder

pub fn repost(target: &Event, relay: &RelayUrl) -> Result<Self, RepostError>

Build a NIP-18 repost (Kind::REPOST) for a kind: 1 note.

The repost’s content is the canonical JSON of the reposted note (or empty when target carries the NIP-70 ["-"] protected marker). The mandatory e tag includes the relay URL at index 2 — NIP-18 elevates the relay hint from “SHOULD” to “MUST” specifically for reposts.

Errors

• RepostError::NotATextNote when target.kind != Kind::TEXT_NOTE.
• RepostError::Serialize if serde_json cannot serialise target (in practice impossible because every signed Event round-trips through serde_json already).

pub fn generic_repost( target: &Event, relay: &RelayUrl, ) -> Result<Self, RepostError>

Build a NIP-18 generic repost (Kind::GENERIC_REPOST) for a non-kind: 1 event.

Carries a k tag with the original kind. For replaceable / addressable events, an a tag is added with the (kind, author, d-tag) coordinate and the content is left empty per spec; for regular events the full JSON is stuffed into content so the original is recoverable even if the referenced relays drop it.

Errors

Returns RepostError::Serialize if serde_json cannot serialise target.

impl EventBuilder

pub fn comment(comment: &Comment) -> Self

Build a kind: 1111 event from comment.

impl EventBuilder

pub fn long_form_article(article: Article) -> Self

Author a published NIP-23 kind: 30023 article.

pub fn long_form_draft(article: Article) -> Self

Author a NIP-23 kind: 30024 draft.

impl EventBuilder

pub fn reaction(target: &ReactionTarget, reaction: &Reaction) -> Self

Build a Kind::REACTION event for target carrying reaction as its content.

The builder pre-populates every NIP-25 SHOULD / MUST tag:

• ["e", <event_id>, <relay>?, <author>] — pubkey hint at the end matches the spec’s example (tags.append(["e", liked.id, hint, liked.pubkey])).
• ["p", <author>, <relay>?].
• ["k", <kind>] when target.kind is set.
• ["a", <coordinate>, <relay>?] when target.coordinate is set.

Callers are free to add an ["emoji", <shortcode>, <url>] tag for Reaction::CustomEmoji payloads, but this method does not synthesise one because the URL is policy-dependent and lives in higher-level NIP-30 code.

impl EventBuilder

pub fn channel_create(metadata: &ChannelMetadata) -> Result<Self, Error>

Author a NIP-28 channel creation event (kind: 40).

Errors

Forwarded from ChannelMetadata::to_json.

pub fn channel_metadata_update( metadata: &ChannelMetadata, channel: EventId, relay: Option<&RelayUrl>, ) -> Result<Self, Error>

Author a NIP-28 channel metadata update (kind: 41).

channel is the kind 40 event id; relay is an optional recommended-relay hint placed in the e tag per NIP-10.

Errors

Forwarded from ChannelMetadata::to_json.

pub fn channel_message_root( channel: EventId, relay: Option<&RelayUrl>, content: impl Into<String>, ) -> Self

Author a root channel message (kind: 42 with a single e tag marked "root").

pub fn channel_message_reply( channel: EventId, channel_relay: Option<&RelayUrl>, parent_message: EventId, parent_relay: Option<&RelayUrl>, parent_author: PublicKey, author_relay: Option<&RelayUrl>, content: impl Into<String>, ) -> Self

Author a reply channel message (kind: 42 with a "root" tag pointing at the channel and a "reply" tag pointing at the parent message; a p tag references the replied-to author).

pub fn channel_hide_message( target: EventId, reason: Option<&HideReason>, ) -> Self

Author a hide-message moderation event (kind: 43).

reason is optional; pass None for a bare hide signal.

pub fn channel_mute_user(target: PublicKey, reason: Option<&HideReason>) -> Self

Author a mute-user moderation event (kind: 44).

reason is optional.

impl EventBuilder

pub fn group_join_request(req: &JoinRequest) -> Self

Author a NIP-29 kind: 9021 join request.

pub fn group_leave_request(req: &LeaveRequest) -> Self

Author a NIP-29 kind: 9022 leave request.

pub fn group_moderation(action: &ModerationAction) -> Self

Author a NIP-29 moderation event.

pub fn group_metadata(metadata: &GroupMetadata) -> Self

Author a NIP-29 kind: 39000 group-metadata event.

pub fn group_admins(admins: &GroupAdmins) -> Self

Author a NIP-29 kind: 39001 group-admins event.

pub fn group_members(members: &GroupMembers) -> Self

Author a NIP-29 kind: 39002 group-members event.

pub fn group_roles(roles: &GroupRoles) -> Self

Author a NIP-29 kind: 39003 group-roles event.

impl EventBuilder

pub fn label(label: &Label) -> Self

Author a NIP-32 kind: 1985 label event.

Tag layout follows the spec’s example order: namespaces first (paired with their l value tag), then targets, then any caller-provided extras.

impl EventBuilder

pub fn git_repository(repo: &Repository) -> Self

Author a NIP-34 repository announcement (kind: 30617).

pub fn git_repository_state(state: &RepositoryState) -> Self

Author a NIP-34 repository state event (kind: 30618).

pub fn git_patch(patch: &Patch) -> Self

Author a NIP-34 patch event (kind: 1617).

pub fn git_pull_request(pr: &PullRequest) -> Self

Author a NIP-34 pull request event (kind: 1618).

pub fn git_pull_request_update(update: &PullRequestUpdate) -> Self

Author a NIP-34 pull request update event (kind: 1619).

pub fn git_issue(issue: &Issue) -> Self

Author a NIP-34 issue event (kind: 1621).

pub fn git_status(event: &StatusEvent) -> Self

Author a NIP-34 status event (kind: 1630..=1633).

pub fn git_grasp_servers(list: &GraspServerList) -> Self

Author a NIP-34 grasp-server list event (kind: 10317).

impl EventBuilder

pub fn torrent_comment<S>(content: S, torrent: &Event) -> Self

where S: Into<String>,

Build a NIP-35 torrent comment (kind: 2004) replying to torrent.

Per the spec a torrent comment “works exactly like a kind: 1” and follows NIP-10, so this attaches a root e marker pointing at the torrent and a p tag crediting its author.

impl EventBuilder

pub fn draft_wrap(draft: &DraftWrap) -> Self

Available on crate feature nip44 only.

Author a NIP-37 kind: 31234 draft wrap.

pub fn private_storage_relays(list: &PrivateStorageRelays) -> Self

Available on crate feature nip44 only.

Author a NIP-37 kind: 10013 private storage relay list.

impl EventBuilder

pub fn user_status(status: UserStatus) -> Self

Author a NIP-38 user-status event.

The builder pins kind = 30315 and always emits the d tag carrying the status-type identifier. The NIP-40 expiration tag is attached through the existing EventBuilder::expiration path when UserStatus::expires_at is set, so callers that also chain .expiration(ts) manually will get a single consolidated tag.

impl EventBuilder

pub fn expiration(self, ts: Timestamp) -> Self

Attach a NIP-40 expiration deadline.

Subsequent calls replace any earlier deadline so the resulting event always carries at most one expiration tag.

impl EventBuilder

pub fn nwc_info(info: &InfoEvent) -> Self

Available on crate feature nip44 only.

Author a NIP-47 info event from a typed bundle. The author SHOULD be the wallet service’s pubkey.

pub fn nwc_request( client_secret: &SecretKey, wallet_public: &PublicKey, request: &Request, encryption: Encryption, expiration: Option<Timestamp>, ) -> Result<Self, NwcError>

Available on crate feature nip44 only.

Build a NIP-47 request event with encrypted body.

client_secret is the URI’s secret; wallet_public is the URI’s host. expiration populates a NIP-40 expiration tag when set — spec §“Request and Response Events” treats the timestamp as a hard cut-off the wallet service may use to drop late requests.

Errors

• NwcError::InvalidJson when request cannot be serialised.
• NwcError::Nip44 / NwcError::Nip04 from the underlying encryption primitives.

pub fn nwc_response( wallet_secret: &SecretKey, client_public: &PublicKey, request_event_id: EventId, response: &Response, encryption: Encryption, ) -> Result<Self, NwcError>

Available on crate feature nip44 only.

Build a NIP-47 response event with encrypted body.

Errors

See Self::nwc_request.

pub fn nwc_notification( wallet_secret: &SecretKey, client_public: &PublicKey, notification: &Notification, encryption: Encryption, ) -> Result<Self, NwcError>

Available on crate feature nip44 only.

Build a NIP-47 notification event with encrypted body.

kind should be KIND_NOTIFICATION for NIP-44 or KIND_NOTIFICATION_LEGACY for NIP-04.

Errors

See Self::nwc_request.

impl EventBuilder

pub fn list(list: &List) -> Self

Author a NIP-51 list event from a List bundle (no encryption applied).

The resulting event has empty .content. Use Self::list_with_private_items to encrypt private items in one shot.

pub fn list_with_private_items( list: &List, owner_secret: &SecretKey, owner_public: &PublicKey, ) -> Result<Self, ListEncryptionError>

Available on crate feature nip44 only.

Author a NIP-51 list event with encrypted private items.

owner_secret / owner_public MUST belong to the same keypair (NIP-51 §“Encryption process pseudocode”).

Errors

Forwarded from List::encrypt_private.

impl EventBuilder

pub fn calendar_date_event(event: &DateCalendarEvent) -> Self

Author a NIP-52 kind: 31922 date-based calendar event.

pub fn calendar_time_event(event: &TimeCalendarEvent) -> Self

Author a NIP-52 kind: 31923 time-based calendar event.

pub fn calendar(calendar: &Calendar) -> Self

Author a NIP-52 kind: 31924 calendar event.

pub fn calendar_rsvp(rsvp: &Rsvp) -> Self

Author a NIP-52 kind: 31925 RSVP event.

impl EventBuilder

pub fn live_stream(stream: &LiveStream) -> Self

Author a NIP-53 kind: 30311 live streaming event.

pub fn meeting_space(space: &MeetingSpace) -> Self

Author a NIP-53 kind: 30312 meeting space event.

pub fn meeting_room(room: &MeetingRoom) -> Result<Self, LiveError>

Author a NIP-53 kind: 30313 meeting room event.

Errors

Returns LiveError::MissingAddress when MeetingRoom::space is None.

pub fn live_chat_message(msg: &LiveChatMessage) -> Self

Author a NIP-53 kind: 1311 live chat message.

pub fn room_presence(presence: &RoomPresence) -> Self

Author a NIP-53 kind: 10312 room presence signal.

impl EventBuilder

pub fn wiki_article(article: &WikiArticle) -> Self

Author a NIP-54 kind: 30818 wiki article event.

pub fn wiki_redirect(redirect: &WikiRedirect) -> Self

Author a NIP-54 kind: 30819 wiki redirect event.

pub fn wiki_merge_request(merge: &MergeRequest) -> Self

Author a NIP-54 kind: 818 merge request event.

Tag order matches spec example: destination a, base e, destination p, then source e with the source marker.

impl EventBuilder

pub fn report(report: &Report) -> Self

Author a NIP-56 kind: 1984 report event.

Tag order matches the spec examples:

1. Primary target tag (p, e, or x).
2. Secondary tags (the p author for an e report or the host e for an x report).
3. server URL hints, if any.
4. Caller-supplied Report::extra_tags.

impl EventBuilder

pub fn zap_request(request: &ZapRequest) -> Self

Author a NIP-57 zap-request event from a typed bundle.

pub fn zap_receipt(receipt: &ZapReceipt) -> Self

Author a NIP-57 zap-receipt event from a typed bundle.

impl EventBuilder

pub fn badge_definition(definition: &BadgeDefinition) -> Self

Author a NIP-58 badge definition (kind: 30009).

pub fn badge_award(award: &BadgeAward) -> Self

Author a NIP-58 badge award (kind: 8).

pub fn profile_badges(badges: &ProfileBadges) -> Self

Author a NIP-58 profile-badges list (kind: 10008).

impl EventBuilder

pub fn cashu_wallet(info: &WalletInfo, owner: &Keys) -> Result<Self, Nip60Error>

Available on crate feature nip44 only.

Author a NIP-60 wallet event (kind: 17375) from a typed WalletInfo.

The bundle is NIP-44 self-encrypted to owner before being stamped on the new event’s .content.

Errors

Forwards every error from WalletInfo::encrypt.

pub fn cashu_token( token: &TokenContent, owner: &Keys, ) -> Result<Self, Nip60Error>

Available on crate feature nip44 only.

Author a NIP-60 token event (kind: 7375) from a typed TokenContent.

Errors

Forwards every error from TokenContent::encrypt.

pub fn cashu_history( entry: &HistoryEntry, owner: &Keys, ) -> Result<Self, Nip60Error>

Available on crate feature nip44 only.

Author a NIP-60 spending-history event (kind: 7376) from a typed HistoryEntry.

The encrypted half — the direction, amount, unit, and the created plus destroyed references — goes into .content; the public redeemed references are stamped as cleartext e tags so nutzap recipients can match them without decryption.

Errors

Forwards every error from HistoryEntry::encrypt.

pub fn cashu_quote(quote: &QuoteState, owner: &Keys) -> Result<Self, Nip60Error>

Available on crate feature nip44 only.

Author a NIP-60 quote-state event (kind: 7374) from a typed QuoteState.

The quote id is encrypted into .content; the mint and NIP-40 expiration tags are stamped in cleartext per spec.

Errors

Forwards every error from QuoteState::encrypt.

impl EventBuilder

pub fn nutzap_info(info: &NutzapInfo) -> Result<Self, Nip61Error>

Available on crate feature nip44 only.

Author a NIP-61 informational event (kind: 10019) from a typed NutzapInfo.

Errors

Forwards every error from NutzapInfo::to_tags.

pub fn nutzap(zap: &Nutzap) -> Result<Self, Nip61Error>

Available on crate feature nip44 only.

Author a NIP-61 nutzap event (kind: 9321) from a typed Nutzap bundle.

Errors

Forwards every error from Nutzap::to_tags.

impl EventBuilder

pub fn request_to_vanish(req: &RequestToVanish) -> Result<Self, VanishError>

Author a NIP-62 kind: 62 request-to-vanish event.

Errors

Returns VanishError::MissingTarget when RequestToVanish::targets is empty.

impl EventBuilder

pub fn relay_discovery(discovery: &RelayDiscovery) -> Self

Author a NIP-66 kind: 30166 relay discovery event.

pub fn relay_monitor(monitor: &RelayMonitor) -> Self

Author a NIP-66 kind: 10166 relay monitor announcement.

impl EventBuilder

pub fn picture_post(post: &PicturePost) -> Result<Self, PictureError>

Author a NIP-68 kind: 20 picture event.

Errors

Propagates MediaAttachmentError from any malformed PicturePost::pictures entry.

impl EventBuilder

pub fn protected(self) -> Self

Attach the NIP-70 protected marker.

The marker is idempotent: the builder skips the operation if a - tag is already present, so chaining .protected() multiple times produces exactly one tag.

impl EventBuilder

pub fn video(video: &Video) -> Result<Self, VideoError>

Author a NIP-71 video event.

Errors

Propagates MediaAttachmentError when any variant in Video::media violates NIP-92 invariants (missing URL or no other field). Also returns VideoError::MissingIdentifier when the variant is addressable but Video::identifier is None.

impl EventBuilder

pub fn community_definition(definition: &CommunityDefinition) -> Self

Author a NIP-72 community definition (kind: 34550).

pub fn community_post_approval(approval: &PostApproval) -> Self

Author a NIP-72 post approval (kind: 4550).

pub fn community_top_level_post( community: Coordinate, community_relay: Option<RelayUrl>, community_author: PublicKey, content: impl Into<String>, ) -> Self

Author a top-level community post (kind: 1111 per NIP-22

• NIP-72 §“Top-level posts”).

Internally builds a Comment whose root and parent are the community coordinate.

pub fn community_nested_reply( community: Coordinate, community_relay: Option<RelayUrl>, community_author: PublicKey, parent_post: EventId, parent_relay: Option<RelayUrl>, parent_kind: Kind, parent_author: PublicKey, content: impl Into<String>, ) -> Self

Author a nested community reply (kind: 1111 per NIP-22

• NIP-72 §“Nested replies”).

parent_post is the parent kind 1111 reply (or another post). The community coordinate stays at the root scope while parent_post lives at the parent scope.

impl EventBuilder

pub fn zap_goal(goal: &ZapGoal) -> Self

Author a NIP-75 kind: 9041 zap goal event.

Panics

Cannot panic in practice: the assembled relays tag always includes its head before the relay URLs, so Tag::new’s non-empty invariant always holds.

impl EventBuilder

pub fn application_data(data: &ApplicationData) -> Self

Author a NIP-78 kind: 30078 application-data event.

The d tag is pinned at the head of the tag list; any extra tags follow in the order they were attached to the bundle.

impl EventBuilder

pub fn thread(thread: &Thread) -> Self

Author a NIP-7D kind: 11 thread root.

impl EventBuilder

pub fn highlight(highlight: &Highlight) -> Self

Author a NIP-84 kind: 9802 highlight event.

impl EventBuilder

pub fn poll(poll: &Poll) -> Self

Author a NIP-88 kind: 1068 poll event.

pub fn poll_response(response: &PollResponse) -> Self

Author a NIP-88 kind: 1018 poll-response event.

impl EventBuilder

pub fn handler_recommendation(rec: &HandlerRecommendation) -> Self

Author a NIP-89 kind: 31989 recommendation event.

pub fn handler_information(handler: &HandlerInformation) -> Self

Author a NIP-89 kind: 31990 handler event.

impl EventBuilder

pub fn dvm_job_request(request: &JobRequest) -> Self

Author a NIP-90 job-request event from a typed JobRequest.

pub fn dvm_job_result(result: &JobResult) -> Self

Author a NIP-90 job-result event from a typed JobResult.

pub fn dvm_job_feedback(feedback: &JobFeedback) -> Self

Author a NIP-90 job-feedback event from a typed JobFeedback.

impl EventBuilder

pub fn file_metadata( caption: impl Into<String>, metadata: &FileMetadata, ) -> Result<Self, FileMetadataError>

Author a NIP-94 file-metadata event.

caption becomes the event’s .content. The bundle’s required fields (url, mime_type, hash) must be set, or the call returns Err(FileMetadataError::Missing*).

Errors

Forwards FileMetadataError from the bundle-to-tags step.

impl EventBuilder

pub fn nip96_file_servers(list: &FileServerList) -> Self

Author a NIP-96 kind: 10096 user file-server list event from a typed FileServerList.

impl EventBuilder

pub fn http_auth(request: &HttpAuthRequest) -> Self

Author a NIP-98 HTTP-auth event from a typed bundle.

impl EventBuilder

pub fn classified_listing(listing: &Listing, kind: Kind) -> Self

Author a NIP-99 listing event of kind.

Use KIND_CLASSIFIED_LISTING for active listings or KIND_CLASSIFIED_LISTING_DRAFT for drafts; both share the same schema.

impl EventBuilder

pub fn voice_message(msg: &VoiceMessage) -> Result<Self, VoiceMessageError>

Author a NIP-A0 voice message.

Errors

Propagates MediaAttachmentError when the optional VoiceMessage::media bundle violates NIP-92 invariants.

impl EventBuilder

pub fn public_message(msg: &PublicMessage) -> Result<Self, PublicMessageError>

Author a NIP-A4 kind: 24 public message.

Errors

Returns PublicMessageError::MissingRecipient when PublicMessage::recipients is empty.

impl EventBuilder

pub fn web_bookmark(bookmark: &WebBookmark) -> Self

Author a NIP-B0 kind: 39701 web-bookmark event.

impl EventBuilder

pub fn blossom_servers(list: &BlossomServerList) -> Self

Author a NIP-B7 / BUD-03 kind: 10063 user-server list event from a typed BlossomServerList.

impl EventBuilder

pub fn code_snippet(snippet: &CodeSnippet) -> Self

Author a NIP-C0 kind: 1337 code-snippet event.

impl EventBuilder

pub fn chat_message(msg: &ChatMessage) -> Self

Author a NIP-C7 kind: 9 chat message.

Trait Implementations

impl Clone for EventBuilder

fn clone(&self) -> EventBuilder

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for EventBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.