Documentation
¶
Overview ¶
Package funding keeps a producer's funding tree between runs, and the transactions it published before they mined.
A carrier is never mined, but it still spends a real output: one output of a funding tree, a mined transaction of equal-valued outputs set aside for carriers. Tree is what an application writes down about that tree so the next carrier knows which output is still unspent and can rebuild the tree to spend it.
A transaction spent before it mines has to carry its ancestry, or no one can verify its spender. KeepBEEF, Rebuild and BumpHex are the three pure steps of that bookkeeping: what to keep while a transaction is unproven, how to rebuild it from what was kept, and the proof's form once it mines. BEEF, which KeepBEEF writes with, refuses an ancestry holding a placeholder parent, so what is kept always reads back.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrPlaceholder = errors.New("funding: placeholder parent in a BEEF")
ErrPlaceholder is BEEF refusing an ancestry that holds a placeholder: a transaction of no inputs standing in for a parent whose bytes were not held, such as producer.Payer builds for a coinbase coin (coinbase: only on a regtest chain you run, development and tests) when it has no node to fetch the real one from. A placeholder is enough to sign against, but its bytes are not the transaction its txid names, so written into a BEEF it is a false record that no reader, package guard first, accepts.
Functions ¶
func BEEF ¶ added in v0.5.1
func BEEF(tx *transaction.Transaction) ([]byte, error)
BEEF is tx's Atomic BEEF, carrying the ancestry back to each proof, after checking that ancestry holds no placeholder. Every real transaction, coinbase included, has at least one input, so a transaction with none is a placeholder, and BEEF refuses it with ErrPlaceholder, naming its txid, rather than writing a BEEF that fails only when it is read back. A mined tx carries no ancestry, so it is never refused.
func BumpHex ¶
func BumpHex(mp *transaction.MerklePath) string
BumpHex is a proof's hex, or empty for no proof.
func KeepBEEF ¶
func KeepBEEF(tx *transaction.Transaction, mp *transaction.MerklePath) (string, error)
KeepBEEF is the BEEF to keep for a transaction published before it mined, or empty once it has a proof. It is BEEF's, so an ancestry holding a placeholder is refused with ErrPlaceholder.
func Rebuild ¶
func Rebuild(rawHex, bumpHex, beefHex string) (*transaction.Transaction, error)
Rebuild rebuilds a transaction an application published: from its raw bytes and proof when it has mined, or from the BEEF kept while it had not, which carries its unproven ancestry. A proof wins over a kept BEEF, which is then not read at all: a proven transaction needs no ancestry. Each is walked by package guard before the SDK parses it.
Types ¶
type Tree ¶
type Tree struct {
// IdentityKeyHex is the identity whose derived key locks the outputs. A
// successor cannot spend a predecessor's tree, so a rotation implies a
// new tree.
IdentityKeyHex string `json:"identityKey,omitempty"`
Txid string `json:"txid"`
RawHex string `json:"rawHex"`
// BumpHex is the tree's proof; empty until it mined.
BumpHex string `json:"bumpHex,omitempty"`
// BeefHex is the tree's full BEEF while it is unmined, so a carrier
// spending it can carry the tree's ancestry. Cleared once BumpHex is set,
// because a proven tree needs nothing behind it.
BeefHex string `json:"beefHex,omitempty"`
Height uint32 `json:"height,omitempty"`
// Sats is the value of each funding output.
Sats uint64 `json:"sats"`
// Count is the number of funding outputs (indices 0..Count-1).
Count uint32 `json:"count"`
// Next is the first unspent funding output index.
Next uint32 `json:"next"`
// Funder is how this tree was paid for, in the application's own words.
// Nothing here reads it. An application that can fund a tree either from
// a wallet or from coin of its own needs it to know whether a wallet
// holds the outputs, so it is kept with the tree it describes.
Funder string `json:"funder,omitempty"`
}
Tree is a funding tree and how much of it is unspent. Its JSON form is part of an application's state file, so a tag or the field order changing changes every state written after it.
Source Files