pushdrop

Documentation

Overview

Package pushdrop is the key derivation an application locks its PushDrop outputs under, and the tagged PushDrop those outputs carry: a leading tag field, the application's own fields, and the wallet's signature over them.

Every derivation here is counterparty Anyone with forSelf=true. Measured at go-sdk v1.5.2, that is the only setting under which a reader holding just the identity key can recompute the locking key AND the embedded signature verifies under it, so a reader checks an output without asking its producer anything.

A Derivation is frozen at an application's first mint: the protocol and key id are hashed into every derived key (BRC-43), so changing either orphans every output ever locked under it. The application owns its Derivation and its tags; nothing here names one.

Index

• Variables
• func Anyone() wallet.Counterparty
• type Derivation
  • func (d Derivation) ExpectedLockingKey(identity *ec.PublicKey) (*ec.PublicKey, error)
  • func (d Derivation) Lock(ctx context.Context, w wallet.Interface, originator string, fields [][]byte, ...) (*script.Script, error)
  • func (d Derivation) Unlocker(ctx context.Context, w wallet.Interface, originator string) Template
  • func (d Derivation) Validate() error
• type Tagged
  • func DecodeTagged(s *script.Script, tag []byte, nfields int) (*Tagged, error)
  • func (t *Tagged) Signed() []byte
  • func (t *Tagged) VerifySignature() bool
• type Template
  • func (t Template) EstimateLength(_ *transaction.Transaction, _ uint32) uint32
  • func (t Template) Sign(tx *transaction.Transaction, inputIndex uint32) (*script.Script, error)

Variables

var ErrDerivation = errors.New("pushdrop: invalid derivation")

ErrDerivation is what Validate refuses a derivation with.

var ErrNotTagged = errors.New("pushdrop: not a tagged PushDrop")

ErrNotTagged reports a script that is not the tagged PushDrop DecodeTagged was asked for.

Functions

func Anyone

func Anyone() wallet.Counterparty

Anyone is the counterparty every derivation here uses. A zero-value Counterparty is not the same thing (the SDK's GetPublicKey and CreateSignature default it differently) and is never passed.

Types

type Derivation

type Derivation struct {
	Protocol wallet.Protocol
	KeyID    string
}

Derivation is one key under an application's BRC-43 protocol: the protocol (security level and name) and the key id within it, which together give the invoice number "<level>-<name>-<key id>".

func (Derivation) ExpectedLockingKey

func (d Derivation) ExpectedLockingKey(identity *ec.PublicKey) (*ec.PublicKey, error)

ExpectedLockingKey is the reader's side of the derivation: from the anyone root, identity's key under d. It equals what identity's own wallet produces with counterparty Anyone and forSelf=true, which is the key Lock locks to.

func (Derivation) Lock

func (d Derivation) Lock(ctx context.Context, w wallet.Interface, originator string, fields [][]byte, sign bool) (*script.Script, error)

Lock builds a lock-before PushDrop of fields through the wallet, locked to the wallet's key under d with counterparty Anyone and forSelf=true. With sign, the wallet's signature over the fields concatenated follows them as one more field; without it the output carries the fields alone.

The fields slice is freshly allocated on every call because the SDK appends the signature into whatever capacity it is handed, and a reused buffer would carry one output's signature into the next. The field bytes are copied too, so the SDK is never handed a buffer the caller still holds.

func (Derivation) Unlocker

func (d Derivation) Unlocker(ctx context.Context, w wallet.Interface, originator string) Template

Unlocker returns the template that spends an output Lock locked under d, through the wallet, signing all outputs. The SDK's pushdrop.Unlocker does not satisfy transaction.UnlockingScriptTemplate on its own (its Sign takes an int and its EstimateLength takes nothing), so Template adapts it.

func (Derivation) Validate

func (d Derivation) Validate() error

Validate applies the BRC-43 rules go-sdk v1.5.2's key deriver applies to a protocol and key id, in the SDK's order, so an application can refuse a derivation that will never produce a key when it builds one rather than at its first mint. The SDK stays the authority: no method here calls Validate, and each derivation still meets the SDK's own check.

The name is measured as the SDK measures it, trimmed and lower-cased, so " Sample " passes here because the SDK derives it as "sample".

type Tagged

type Tagged struct {
	// Fields are the fields Lock was given, tag first. The signature is not
	// one of them.
	Fields [][]byte
	// LockingKey is the key the output is locked to.
	LockingKey *ec.PublicKey
	// Signature is Lock's DER signature over sha256 of Fields concatenated.
	Signature []byte
}

Tagged is a decoded signed PushDrop whose first field is a tag.

func DecodeTagged

func DecodeTagged(s *script.Script, tag []byte, nfields int) (*Tagged, error)

DecodeTagged parses what Lock writes with sign set: nfields fields, tag included, the first equal to tag, then the signature. Only the lock-before layout decodes, which is the layout Lock writes; a lock-after script from some other producer is refused rather than guessed at. What the fields after the tag must hold is the caller's to check.

func (*Tagged) Signed

func (t *Tagged) Signed() []byte

Signed returns the bytes Lock signed: the fields concatenated.

func (*Tagged) VerifySignature

func (t *Tagged) VerifySignature() bool

VerifySignature checks the embedded signature under the locking key. The wallet signs sha256 of the concatenated fields, so that is what is verified.

type Template

type Template struct {
	U *sdkpushdrop.Unlocker
}

Template adapts the SDK's pushdrop.Unlocker to transaction.UnlockingScriptTemplate.

func (Template) EstimateLength

func (t Template) EstimateLength(_ *transaction.Transaction, _ uint32) uint32

EstimateLength is the unlocker's own estimate: one DER signature push.

func (Template) Sign

func (t Template) Sign(tx *transaction.Transaction, inputIndex uint32) (*script.Script, error)

Sign signs input inputIndex of tx through the wallet.