HyperQube Events

This Go module provides standard event definitions and validation logic for the custom Nostr events used by HyperQube. It ensures that communication between HyperCore One developers and HyperQube nodes (via Nostr) adheres to the specified protocols.

For a detailed specification of the event definitions, fields, and behaviors, please refer to the HyperQube Event Definitions.

Installation

go get github.com/hypercore-one/hyperqube-events

Usage

Validating HyperSignal Events (Kind 33321)

// event is *nostr.Event
if err := events.ValidateHyperSignalEvent(event, []string{"authorized_developer_pubkey"}); err != nil {
    log.Printf("Validation failed: %v", err)
}

Validating Action Acknowledgements (Kind 3333)

// event is *nostr.Event
if err := events.ValidateActionAckEvent(event); err != nil {
    log.Printf("Validation failed: %v", err)
}

Helper Functions

The package provides several utility functions for working with Nostr events.

ValidateKind

Checks if the event kind is either HyperSignal (33321) or ActionAck (3333).

func ValidateKind(event *nostr.Event) error

HasTag

Checks if an event has a specific tag.

func HasTag(event *nostr.Event, name string) bool

HasUniqueTag

Checks if an event has a specific tag exactly once.

func HasUniqueTag(event *nostr.Event, name string) bool

HasTagWithValue

Checks if an event has a tag with a specific value.

func HasTagWithValue(event *nostr.Event, name string, value string) bool

GetTagValue

Retrieves the first value (index 1) of the first occurrence of a specific tag. For tags with multiple occurrences or multiple values, use GetTags.

func GetTagValue(event *nostr.Event, name string) string

GetTags

Retrieves all values (index 1+) from all tags with the specified name. A Nostr tag can appear multiple times, and each occurrence can contain multiple values (e.g. ["p", "pubkey1", "relay1"] and ["p", "pubkey2", "relay2"]).

func GetTags(event *nostr.Event, name string) [][]string

IsValidHex

Validates if a string is a valid hex string of a specific length.

func IsValidHex(s string, length int) bool

Constants

The package exports the following constants for event kinds, tags, and values:

Kinds

• KindHyperSignal (33321)
• KindActionAck (3333)

Tag Names

• TagD ("d")
• TagVersion ("version")
• TagHash ("hash")
• TagNetwork ("network")
• TagAction ("action")
• TagGenesisURL ("genesis_url")
• TagRequiredBy ("required_by")
• TagA ("a")
• TagP ("p")
• TagStatus ("status")
• TagNodeID ("node_id")
• TagActionAt ("action_at")
• TagError ("error")

Action Values

• ActionUpgrade ("upgrade")
• ActionReboot ("reboot")

Status Values

• StatusSuccess ("success")
• StatusFailure ("failure")

Identifiers

• IdentifierHyperqube ("hyperqube")

Event Specifications

For a deep dive into the structure of these events, including all required tags and their meanings, see the HyperQube Event Definitions file.

Testing

Run the test suite with go test -v.