nostrlsps5

README

nostr-lsps5: LSPS5 Webhooks over Nostr

A library for delivering LSPS5 compliant webhook notifications over Nostr.

This library follows the LSPS5 (bLIP-55) specification for push notifications, but uses the nostr+lsps5:// protocol to deliver webhook events via Nostr relays instead of traditional HTTPS endpoints.

Features

• Standardized Kind: Uses Kind 31055 specifically for LSPS5 notifications.
• Encryption: Built-in support for NIP-04 encrypted direct messages (to be updated to NIP-44 in the future).
• JSON-RPC 2.0: Handles standard LSPS5 notification payloads.
• Easy Integration: Simple API to create, sign, and parse notification events.

Usage

Create a Notification (LSP side)

import "github.com/flowgate-lsp/nostr-lsps5"

sdk := nostrlsps5.NewSDK(lspHexPrivateKey)

// Create a signed and encrypted Nostr event
event, err := sdk.CreateNotificationEvent(
    clientHexPubKey, 
    "lsps5.payment_incoming", 
    nil,
)

// Publish 'event' to your preferred relays...

Parse a Notification (Client side)

import "github.com/flowgate-lsp/nostr-lsps5"

sdk := nostrlsps5.NewSDK(clientHexPrivateKey)

// Parse an incoming Nostr event
notification, err := sdk.ParseNotificationEvent(event, lspHexPubKey)

if err == nil {
    fmt.Printf("Received method: %s\n", notification.Method)
}

Protocol Details

• Event Kind: 31055
• Tags:
  • ["p", <recipient-pubkey>]
  • ["t", "lsps5"]
• Content: Encrypted JSON-RPC 2.0 Notification Object.

Documentation

Index

• Constants
• func ParseLsp5Uri(uriStr string) (string, []string, error)
• type LSPS5
  • func NewLSPS5(privKey string) *LSPS5
  • func (s *LSPS5) CreateNotificationEvent(recipientPubKey string, method string, params interface{}) (*nostr.Event, error)
  • func (s *LSPS5) GenerateLsp5Uri(relays []string) (string, error)
  • func (s *LSPS5) ParseNotificationEvent(ev *nostr.Event, senderPubKey string) (*Notification, error)
• type Notification
  • func NewNotification(method string, params interface{}) *Notification

Constants

const (
	// KindLSPS5 is the dedicated Nostr kind for LSPS5 notifications
	KindLSPS5 = 31055

	// TagLSPS5 is the tag used to identify LSPS5 events
	TagLSPS5 = "lsps5"
)

Functions

func ParseLsp5Uri

func ParseLsp5Uri(uriStr string) (string, []string, error)

ParseLsp5Uri parses a nostr+lsps5 URI Format: nostr+lsps5://<pubkey>?relay=<relay1>&relay=<relay2>

Types

type LSPS5

type LSPS5 struct {
	// contains filtered or unexported fields
}

LSPS5 handles creation and parsing of LSPS5 notifications.

func NewLSPS5

func NewLSPS5(privKey string) *LSPS5

NewLSPS5 creates a new LSPS5 Nostr instance

func (*LSPS5) CreateNotificationEvent

func (s *LSPS5) CreateNotificationEvent(recipientPubKey string, method string, params interface{}) (*nostr.Event, error)

CreateNotificationEvent creates a signed kind 31055 Nostr event containing an encrypted LSPS5 notification.

func (*LSPS5) GenerateLsp5Uri

func (s *LSPS5) GenerateLsp5Uri(relays []string) (string, error)

GenerateLsp5Uri generates a nostr+lsps5 URI Format: nostr+lsps5://<pubkey>?relay=<relay1>&relay=<relay2>

func (*LSPS5) ParseNotificationEvent

func (s *LSPS5) ParseNotificationEvent(ev *nostr.Event, senderPubKey string) (*Notification, error)

ParseNotificationEvent decrypts and parses an LSPS5 notification from a Nostr event.

type Notification

type Notification struct {
	JsonRpc string      `json:"jsonrpc"`
	Method  string      `json:"method"`
	Params  interface{} `json:"params,omitempty"`
}

Notification represents a JSON-RPC 2.0 notification object

func NewNotification

func NewNotification(method string, params interface{}) *Notification

NewNotification creates a new JSON-RPC 2.0 notification