nip90

Documentation

Overview

Package nip90 implements NIP-90: Data Vending Machines, a marketplace flow where customers announce compute jobs and service providers compete to fulfill them. NIP-90 reserves kinds 5000-5999 for job requests, 6000-6999 for job results, and 7000 for job feedback; job-kind-specific input/output schemas are defined by separate, per-job-type specs and are intentionally out of scope here — only the common envelope (tags shared by every job type) is modeled.

Index

• Constants
• Variables
• func IsJobRequestKind(kind int) bool
• func IsJobResultKind(kind int) bool
• func JobResultKindFor(requestKind int) int
• func NewJobFeedback(p JobFeedbackParams) *nip01.Event
• func NewJobRequest(p JobRequestParams) (*nip01.Event, error)
• func NewJobResult(p JobResultParams) (*nip01.Event, error)
• func ValidateJobFeedback(event *nip01.Event) error
• func ValidateJobRequest(event *nip01.Event) error
• func ValidateJobResult(event *nip01.Event) error
• type JobFeedback
  • func ParseJobFeedback(event *nip01.Event) (*JobFeedback, error)
• type JobFeedbackParams
• type JobInput
• type JobRequest
  • func ParseJobRequest(event *nip01.Event) (*JobRequest, error)
• type JobRequestParams
• type JobResult
  • func ParseJobResult(event *nip01.Event) (*JobResult, error)
• type JobResultParams

Constants

const (
	KindJobRequest  = 5000 // lower bound of the 5000-5999 job request range
	KindJobResult   = 6000 // lower bound of the 6000-6999 job result range
	KindJobFeedback = 7000
)

const (
	InputTypeURL   = "url"
	InputTypeEvent = "event"
	InputTypeJob   = "job"
	InputTypeText  = "text"
)

Input types for the "i" tag's second element.

const (
	StatusPaymentRequired = "payment-required"
	StatusProcessing      = "processing"
	StatusError           = "error"
	StatusSuccess         = "success"
	StatusPartial         = "partial"
)

Job feedback status values for the "status" tag.

Variables

var (
	ErrWrongKind          = errors.New("nip90: wrong kind")
	ErrInvalidInputTag    = errors.New("nip90: invalid i tag")
	ErrInvalidInputType   = errors.New("nip90: invalid i tag input-type")
	ErrInvalidBid         = errors.New("nip90: invalid bid amount")
	ErrInvalidRelayURL    = errors.New("nip90: invalid relay url")
	ErrInvalidRelayScheme = errors.New("nip90: relay url must use ws or wss scheme")
	ErrInvalidProviderTag = errors.New("nip90: invalid p tag")
	ErrInvalidParamTag    = errors.New("nip90: invalid param tag")
	ErrInvalidSignature   = errors.New("nip90: invalid signature")
	ErrInvalidEventTag    = errors.New("nip90: invalid e tag")
	ErrMissingEventTag    = errors.New("nip90: missing e tag referencing the job request")
	ErrInvalidAmount      = errors.New("nip90: invalid amount")
	ErrInvalidStatus      = errors.New("nip90: invalid status")
	ErrMissingStatus      = errors.New("nip90: job feedback must have a status tag")
)

Failure modes for the Parse*/Validate*/New* functions below, for callers that need to distinguish them (e.g. via errors.Is) rather than match on message text.

Functions

func IsJobRequestKind

func IsJobRequestKind(kind int) bool

IsJobRequestKind reports whether kind falls in the 5000-5999 job request range.

func IsJobResultKind

func IsJobResultKind(kind int) bool

IsJobResultKind reports whether kind falls in the 6000-6999 job result range.

func JobResultKindFor

func JobResultKindFor(requestKind int) int

JobResultKindFor returns the job-result kind for a given job-request kind: results always use a kind 1000 higher than the request they answer.

func NewJobFeedback

func NewJobFeedback(p JobFeedbackParams) *nip01.Event

NewJobFeedback builds an unsigned kind 7000 feedback event about p.RequestEvent.

func NewJobRequest

func NewJobRequest(p JobRequestParams) (*nip01.Event, error)

NewJobRequest builds an unsigned job request event. JobKind must be in the 5000-5999 range. Caller must sign it.

func NewJobResult

func NewJobResult(p JobResultParams) (*nip01.Event, error)

NewJobResult builds an unsigned job result event answering p.RequestEvent.

func ValidateJobFeedback

func ValidateJobFeedback(event *nip01.Event) error

ValidateJobFeedback checks the signature and structure of a feedback event.

func ValidateJobRequest

func ValidateJobRequest(event *nip01.Event) error

ValidateJobRequest checks the signature and structure of a job request event.

func ValidateJobResult

func ValidateJobResult(event *nip01.Event) error

ValidateJobResult checks the signature and structure of a job result event.

Types

type JobFeedback

type JobFeedback struct {
	*nip01.Event
	Status           string
	StatusExtra      string
	RequestEventID   string
	RequestRelayHint string
	CustomerPubkey   string
	AmountMloki      int64
	Bolt11           string
}

JobFeedback is a parsed kind 7000 job feedback event.

func ParseJobFeedback

func ParseJobFeedback(event *nip01.Event) (*JobFeedback, error)

ParseJobFeedback parses and structurally validates a job feedback event.

type JobFeedbackParams

type JobFeedbackParams struct {
	ProviderPubkey string
	RequestEvent   *nip01.Event
	Status         string
	StatusExtra    string
	Content        string
	AmountMloki    int64
}

JobFeedbackParams describes a NIP-90 job feedback event. ProviderPubkey, RequestEvent, and Status are required; StatusExtra, Content, and AmountMloki are optional.

type JobInput

type JobInput struct {
	Data   string
	Type   string
	Relay  string
	Marker string
}

JobInput is one ["i", data, type, relay, marker] tag.

type JobRequest

type JobRequest struct {
	*nip01.Event
	Inputs          []JobInput
	Output          string
	BidMloki        int64
	Relays          []string
	TargetProviders []string
	Params          map[string][]string
	// Encrypted is true if the request carries an "encrypted" tag, meaning
	// its i/param tags were moved into an encrypted Content payload (see
	// NIP-90's "Encrypted Params" section). Decrypting that payload is the
	// caller's responsibility (NIP-04, using the customer's private key and
	// the target provider's public key).
	Encrypted bool
}

JobRequest is a parsed kind 5000-5999 job request event.

func ParseJobRequest

func ParseJobRequest(event *nip01.Event) (*JobRequest, error)

ParseJobRequest parses and structurally validates a job request event.

type JobRequestParams

type JobRequestParams struct {
	Pubkey          string
	JobKind         int
	Inputs          []JobInput
	Output          string
	BidMloki        int64
	Relays          []string
	TargetProviders []string
	Params          map[string]string
}

JobRequestParams describes a NIP-90 job request. Pubkey, JobKind, and Inputs are required; Output, BidMloki, Relays, TargetProviders, and Params are optional.

type JobResult

type JobResult struct {
	*nip01.Event
	RequestEventID   string
	RequestRelayHint string
	RequestJSON      string
	CustomerPubkey   string
	AmountMloki      int64
	Bolt11           string
	// Encrypted is true if the result carries an "encrypted" tag; Content is
	// then a NIP-04 encrypted payload the caller must decrypt.
	Encrypted bool
}

JobResult is a parsed kind 6000-6999 job result event.

func ParseJobResult

func ParseJobResult(event *nip01.Event) (*JobResult, error)

ParseJobResult parses and structurally validates a job result event.

type JobResultParams

type JobResultParams struct {
	ProviderPubkey string
	// ResultKind should normally be JobResultKindFor(RequestEvent.Kind).
	ResultKind   int
	RequestEvent *nip01.Event
	Content      string
	AmountMloki  int64
	Bolt11       string
}

JobResultParams describes a NIP-90 job result. ProviderPubkey, ResultKind, and RequestEvent are required; Content, AmountMloki, and Bolt11 are optional.