nip13

Documentation

Overview

Package nip13 implements NIP-13: Proof of Work, letting an event embed a nonce tag whose event ID has a target number of leading zero bits. It operates on plain event fields (Fields) rather than a concrete event type, so it has no dependency on nip01 — nip01 depends on nip13 (to validate PoW during Event.Verify), and a dependency back the other way would be a cycle.

Index

• Constants
• func Difficulty(id string) (int, error)
• func Mine(ctx context.Context, ev Fields, targetDifficulty int, opts ...MineOption) (id string, nonceTag []string, err error)
• func ValidatePow(ev Fields) (nonce string, difficulty int, err error)
• type Fields
• type MineOption
  • func WithProgress(interval time.Duration, fn func(Progress)) MineOption
  • func WithWorkers(n int) MineOption
• type Progress

Constants

const (
	POWTagName = "nonce"
)

Functions

func Difficulty

func Difficulty(id string) (int, error)

Difficulty returns the number of leading zero bits in a 32-byte hex event ID -- the event's actual NIP-13 proof-of-work difficulty, independent of whatever a nonce tag claims. Unlike ValidatePow (which checks a nonce tag's declared difficulty against reality and requires one to be present), Difficulty works for any event ID, nonce tag or not, which is what a relay needs to enforce a minimum difficulty across all incoming events rather than just validate self-reported ones.

func Mine

func Mine(ctx context.Context, ev Fields, targetDifficulty int, opts ...MineOption) (id string, nonceTag []string, err error)

Mine finds a nonce tag that gives ev an ID with at least targetDifficulty leading zero bits, per NIP-13. It returns the new ID and the nonce tag to append; the caller applies both to its own event (Mine has no event type to mutate). ev must be unsigned — mining after signing would invalidate the signature, since it changes the ID.

func ValidatePow

func ValidatePow(ev Fields) (nonce string, difficulty int, err error)

ValidatePow checks ev's nonce tag against its actual ID: that the nonce tag is well-formed, that ev.ID has at least as many leading zero bits as the tag's declared difficulty, and that ev.ID is in fact the correct hash of ev's other fields (i.e. the nonce wasn't just copied from a different event).

Types

type Fields

type Fields struct {
	ID        string
	PubKey    string
	CreatedAt uint64
	Kind      int
	Tags      [][]string
	Content   string
	Sig       string
}

Fields is the minimal set of event fields nip13 needs to mine or validate a proof-of-work nonce. ID is required by ValidatePow (the value being checked) and ignored by Mine (which produces one instead); Sig is required by Mine's must-be-unsigned guard and ignored by ValidatePow.

type MineOption

type MineOption func(*mineConfig)

MineOption configures Mine's search strategy (parallelism, progress reporting). The zero value of every option is "off" -- Mine with no options behaves exactly as it did before options existed.

func WithProgress

func WithProgress(interval time.Duration, fn func(Progress)) MineOption

WithProgress calls fn roughly every interval (default 3s if interval<=0) with the hash count and elapsed time aggregated across all workers, until Mine returns.

func WithWorkers

func WithWorkers(n int) MineOption

WithWorkers searches for a valid nonce across n goroutines in parallel, each covering a disjoint stride of the nonce space (worker i tries nonce=i, i+n, i+2n, ...). n<=0 means 1, which reproduces the original single-threaded search (nonce=0,1,2,...) exactly -- Mine's default with no options at all.

type Progress

type Progress struct {
	HashesTried uint64
	Elapsed     time.Duration
	Workers     int
}

Progress reports mining progress aggregated across every worker, for a caller that registered WithProgress.