documentation comments for apputil, auth and bech32encoding

also removed relay.damus.io which is a dumpster fire of spammers and trolls

apputil/apputil.go

@@ -5,7 +5,8 @@ import (
 	"path/filepath"
 )
 
-// EnsureDir checks a file could be written to a path, creates the directories as needed
+// EnsureDir checks a file could be written to a path, creates the directories
+// as needed
 func EnsureDir(fileName string) {
 	dirName := filepath.Dir(fileName)
 	if _, serr := os.Stat(dirName); serr != nil {

auth/doc.go

@@ -0,0 +1,2 @@
+// Package auth implements NIP-42 authentication.
+package auth

bech32encoding/doc.go

@@ -0,0 +1,6 @@
+// Package bech32encoding implements NIP-19 entities, which are bech32 encoded
+// data that describes nostr data types.
+//
+// These are not just identifiers of events and users, but also include things
+// like relay hints where to find events.
+package bech32encoding

bech32encoding/keys.go

@@ -14,12 +14,16 @@ const (
 	// MinKeyStringLen is 56 because Bech32 needs 52 characters plus 4 for the HRP,
 	// any string shorter than this cannot be a nostr key.
 	MinKeyStringLen = 56
-	HexKeyLen       = 64
+	// HexKeyLen is the length of a nostr key in hexadecimal.
-	Bech32HRPLen    = 4
+	HexKeyLen = 64
+	// Bech32HRPLen is the length of the standard nostr keys, nsec and npub.
+	Bech32HRPLen = 4
 )
 
 var (
+	// SecHRP is the standard Human Readable Prefix (HRP) for a nostr secret key in bech32 encoding - nsec
 	SecHRP = []byte("nsec")
+	// PubHRP is the standard Human Readable Prefix (HRP) for a nostr public key in bech32 encoding - nsec
 	PubHRP = []byte("npub")
 )
 
@@ -59,6 +63,7 @@ func NsecToSecretKey(encoded []byte) (sk *secp256k1.SecretKey, err error) {
 	return
 }
 
+// NsecToBytes converts a nostr bech32 encoded secret key to raw bytes.
 func NsecToBytes(encoded []byte) (sk []byte, err error) {
 	var b5, hrp []byte
 	if hrp, b5, err = bech32.Decode(encoded); chk.E(err) {
@@ -76,6 +81,7 @@ func NsecToBytes(encoded []byte) (sk []byte, err error) {
 	return
 }
 
+// NpubToBytes converts a bech32 encoded public key to raw bytes.
 func NpubToBytes(encoded []byte) (pk []byte, err error) {
 	var b5, hrp []byte
 	if hrp, b5, err = bech32.Decode(encoded); chk.E(err) {
@@ -151,6 +157,8 @@ func HexToSecretKey(sk []byte) (s *btcec.SecretKey, err error) {
 	return
 }
 
+// HexToNpub converts a raw 64 character hex encoded public key (as used in
+// standard nostr json events) to a bech32 encoded npub.
 func HexToNpub(publicKeyHex []byte) (s []byte, err error) {
 	b := make([]byte, schnorr.PubKeyBytesLen)
 	if _, err = hex.DecBytes(b, publicKeyHex); chk.D(err) {
@@ -164,6 +172,7 @@ func HexToNpub(publicKeyHex []byte) (s []byte, err error) {
 	return bech32.Encode(NpubHRP, bits5)
 }
 
+// BinToNpub converts a raw 32 byte public key to nostr bech32 encoded npub.
 func BinToNpub(b []byte) (s []byte, err error) {
 	var bits5 []byte
 	if bits5, err = bech32.ConvertBits(b, 8, 5, true); chk.D(err) {
@@ -200,6 +209,8 @@ func SecretKeyToHex(sk *btcec.SecretKey) (hexSec []byte) {
 	return
 }
 
+// NsecToHex converts a bech32 encoded nostr secret key to a raw hexadecimal
+// string.
 func NsecToHex(nsec []byte) (hexSec []byte, err error) {
 	var sk *secp256k1.SecretKey
 	if sk, err = NsecToSecretKey(nsec); chk.E(err) {

bech32encoding/nip19.go

@@ -3,7 +3,6 @@ package bech32encoding
 import (
 	"bytes"
 	"encoding/binary"
-	"reflect"
 
 	"realy.lol/bech32encoding/pointers"
 	"realy.lol/ec/bech32"
@@ -15,28 +14,24 @@ import (
 )
 
 var (
-	NoteHRP     = []byte("note")
+	// NoteHRP is the Human Readable Prefix (HRP) for a nostr note (kind 1)
-	NsecHRP     = []byte("nsec")
+	NoteHRP = []byte("note")
-	NpubHRP     = []byte("npub")
+	// NsecHRP is the Human Readable Prefix (HRP) for a nostr secret key
+	NsecHRP = []byte("nsec")
+	// NpubHRP is the Human Readable Prefix (HRP) for a nostr public key
+	NpubHRP = []byte("npub")
+	// NprofileHRP is the Human Readable Prefix (HRP) for a nostr profile metadata
+	// event (kind 0)
 	NprofileHRP = []byte("nprofile")
-	NeventHRP   = []byte("nevent")
+	// NeventHRP is the Human Readable Prefix (HRP) for a nostr event, which may
-	NentityHRP  = []byte("naddr")
+	// include relay hints to find the event, and the author's npub.
+	NeventHRP = []byte("nevent")
+	// NentityHRP is the Human Readable Prefix (HRP) for a nostr is a generic nostr entity, which may include relay hints to find the event, and the author's npub.
+	NentityHRP = []byte("naddr")
 )
 
-func DecodeToString(bech32String []byte) (prefix, value []byte, err error) {
+// Decode a nostr bech32 encoded entity, return the prefix, and the decoded
-	var s any
+// value, and any error if one occurred in the process of decoding.
-	if prefix, s, err = Decode(bech32String); chk.D(err) {
-		return
-	}
-	var ok bool
-	if value, ok = s.([]byte); ok {
-		return
-	}
-	err = log.E.Err("value was not decoded to a string, found type %s",
-		reflect.TypeOf(s))
-	return
-}
-
 func Decode(bech32string []byte) (prefix []byte, value any, err error) {
 	var bits5 []byte
 	if prefix, bits5, err = bech32.DecodeNoLimit(bech32string); chk.D(err) {
@@ -153,6 +148,8 @@ func Decode(bech32string []byte) (prefix []byte, value any, err error) {
 	return prefix, data, errorf.E("unknown tag %s", prefix)
 }
 
+// EncodeNote encodes a standard nostr NIP-19 note entity (mostly meaning a
+// nostr kind 1 short text note)
 func EncodeNote(eventIDHex []byte) (s []byte, err error) {
 	var b []byte
 	if _, err = hex.DecBytes(b, eventIDHex); chk.D(err) {
@@ -166,6 +163,8 @@ func EncodeNote(eventIDHex []byte) (s []byte, err error) {
 	return bech32.Encode(NoteHRP, bits5)
 }
 
+// EncodeProfile encodes a pubkey and a set of relays into a bech32 encoded
+// entity.
 func EncodeProfile(publicKeyHex []byte, relays [][]byte) (s []byte, err error) {
 	buf := &bytes.Buffer{}
 	pb := make([]byte, schnorr.PubKeyBytesLen)
@@ -185,6 +184,7 @@ func EncodeProfile(publicKeyHex []byte, relays [][]byte) (s []byte, err error) {
 	return bech32.Encode(NprofileHRP, bits5)
 }
 
+// EncodeEvent encodes an event, including relay hints and author pubkey.
 func EncodeEvent(eventIDHex *eventid.T, relays [][]byte, author []byte) (s []byte, err error) {
 	buf := &bytes.Buffer{}
 	id := make([]byte, sha256.Size)
@@ -211,6 +211,7 @@ func EncodeEvent(eventIDHex *eventid.T, relays [][]byte, author []byte) (s []byt
 	return bech32.Encode(NeventHRP, bits5)
 }
 
+// EncodeEntity encodes a pubkey, kind, event Id, and relay hints.
 func EncodeEntity(pk []byte, k *kind.T, id []byte, relays [][]byte) (s []byte, err error) {
 	buf := &bytes.Buffer{}
 	writeTLVEntry(buf, TLVDefault, []byte(id))

bech32encoding/pointers/pointers.go

@@ -5,11 +5,13 @@ import (
 	"realy.lol/kind"
 )
 
+// Profile pointer is a combination of pubkey and relay list.
 type Profile struct {
 	PublicKey []byte   `json:"pubkey"`
 	Relays    [][]byte `json:"relays,omitempty"`
 }
 
+// Event pointer is the combination of an event Id, relay hints, author pubkey and kind.
 type Event struct {
 	ID     *eventid.T `json:"id"`
 	Relays [][]byte   `json:"relays,omitempty"`
@@ -17,6 +19,7 @@ type Event struct {
 	Kind   *kind.T    `json:"kind,omitempty"`
 }
 
+// Entity is the combination of a pubkey, kind, arbitrary identifier, and relay hints.
 type Entity struct {
 	PublicKey  []byte   `json:"pubkey"`
 	Kind       *kind.T  `json:"kind,omitempty"`

ws/subscription_test.go

@@ -15,7 +15,7 @@ import (
 	"realy.lol/tags"
 )
 
-const RELAY = "wss://relay.damus.io"
+const RELAY = "wss://mleku.realy.lol"
 
 // test if we can fetch a couple of random events
 func TestSubscribeBasic(t *testing.T) {