wallet

Documentation

Overview

Package wallet implements Bitcoin 09's durable key store and offline transaction preparation. Wallet files are independent of chain data and every key-file operation is serialized by one OS advisory lock.

Index

• Constants
• Variables
• func SubmitPayment(c *core.Chain, tx *core.Tx) (core.TxAcceptanceResult, error)
• type PreparedPayment
• type Snapshot
• type SnapshotOutpoint
• type Wallet
  • func Load(path string) (*Wallet, error)
  • func LoadForNetwork(path, network string) (*Wallet, error)
  • func LoadOrCreateForNetwork(path, network string) (w *Wallet, err error)
  • func Open(path, network string) (*Wallet, error)
  • func (w *Wallet) Addresses() []string
  • func (w *Wallet) AddressesE() (addresses []string, err error)
  • func (w *Wallet) Balance(c *core.Chain) int64
  • func (w *Wallet) BalanceE(c *core.Chain) (balance int64, err error)
  • func (w *Wallet) BuildPayment(c *core.Chain, toAddr string, amount, fee int64, ...) (prepared *PreparedPayment, err error)
  • func (w *Wallet) NewAddress() (address string, err error)
  • func (w *Wallet) PKHs() [][20]byte
  • func (w *Wallet) PKHsE() (pkhs [][20]byte, err error)
  • func (w *Wallet) PrepareAt(c *core.Chain, expected core.ChainTipSnapshot, toAddr string, ...) (snapshot Snapshot, prepared *PreparedPayment, err error)
  • func (w *Wallet) PrimaryPKH() [20]byte
  • func (w *Wallet) PrimaryPKHE() (primary [20]byte, err error)
  • func (w *Wallet) Send(c *core.Chain, to string, amount, fee int64) (*core.Tx, error)
  • func (w *Wallet) SnapshotAt(c *core.Chain, expected core.ChainTipSnapshot) (snapshot Snapshot, err error)

Constants

const (
	SchemaVersion          = 1
	MaxRestrictedOutpoints = 4_096
	MaxWalletKeys          = 10_000
	MaxWalletFileBytes     = 1 << 20
	MaxPaymentCandidates   = 10_000
	MaxPaymentInputs       = 10_000
	MaxSignedTxBytes       = 10_000
)

Variables

var ErrWalletNotFound = errors.New("wallet file not found")

Functions

func SubmitPayment

func SubmitPayment(c *core.Chain, tx *core.Tx) (core.TxAcceptanceResult, error)

SubmitPayment validates and admits already-signed bytes without rebuilding.

Types

type PreparedPayment

type PreparedPayment struct {
	Tx                *core.Tx
	SelectedOutpoints []core.OutPoint
}

type Snapshot

type Snapshot struct {
	SchemaVersion      int                   `json:"schema_version"`
	Network            string                `json:"network"`
	Tip                core.ChainTipSnapshot `json:"-"`
	PrimaryAddress     string                `json:"primary_address"`
	Addresses          []string              `json:"addresses"`
	Outpoints          []SnapshotOutpoint    `json:"outpoints"`
	SpendableUnits     int64                 `json:"spendable_units"`
	WalletSnapshotHash string                `json:"wallet_snapshot_hash"`
}

type SnapshotOutpoint

type SnapshotOutpoint struct {
	Outpoint          string        `json:"outpoint"`
	AmountUnits       int64         `json:"amount_units"`
	Address           string        `json:"address"`
	OutpointRef       core.OutPoint `json:"-"`
	TxID              core.Hash32   `json:"-"`
	Vout              uint32        `json:"-"`
	OwnerPKH          [20]byte      `json:"-"`
	OwnerAddressIndex uint32        `json:"-"`
	KeyIndex          int           `json:"-"`
}

type Wallet

type Wallet struct {
	// contains filtered or unexported fields
}

Wallet retains only the canonical file identity. Private keys are loaded into a short-lived slice under the interprocess lock for each operation.

func Load

func Load(path string) (*Wallet, error)

Load preserves the original library entry point as a read-only operation. The filename selects the canonical network; a missing wallet returns ErrWalletNotFound and is never implicitly created.

func LoadForNetwork

func LoadForNetwork(path, network string) (*Wallet, error)

LoadForNetwork read-locks a wallet using an explicit canonical network. It accepts exact pre-V1 {"keys":...} files without rewriting them.

func LoadOrCreateForNetwork

func LoadOrCreateForNetwork(path, network string) (w *Wallet, err error)

LoadOrCreateForNetwork is the explicit human upgrade boundary. Missing wallets are created with exactly one key; exact legacy wallets are migrated under the same lock without changing their key order or material.

func Open

func Open(path, network string) (*Wallet, error)

Open validates a dedicated V1 wallet if it exists. It never creates a key.

func (*Wallet) Addresses

func (w *Wallet) Addresses() []string

Addresses is the compatibility accessor used by human node flows.

func (*Wallet) AddressesE

func (w *Wallet) AddressesE() (addresses []string, err error)

AddressesE returns all wallet addresses in file order.

func (*Wallet) Balance

func (w *Wallet) Balance(c *core.Chain) int64

Balance is retained for source compatibility. Production paths use BalanceE and must handle errors explicitly.

func (*Wallet) BalanceE

func (w *Wallet) BalanceE(c *core.Chain) (balance int64, err error)

BalanceE returns one checked balance from an atomic multi-owner chain snapshot while the strict wallet key view remains locked.

func (*Wallet) BuildPayment

func (w *Wallet) BuildPayment(c *core.Chain, toAddr string, amount, fee int64, excluded map[core.OutPoint]struct{}) (prepared *PreparedPayment, err error)

BuildPayment selects and signs only. It never submits, starts networking, or performs any peer write. excluded is bounded to prevent hostile memory amplification and excluded outpoints are never selected.

func (*Wallet) NewAddress

func (w *Wallet) NewAddress() (address string, err error)

NewAddress creates and durably persists a new key before returning its address. It rereads the complete wallet only after taking the OS lock.

func (*Wallet) PKHs

func (w *Wallet) PKHs() [][20]byte

func (*Wallet) PKHsE

func (w *Wallet) PKHsE() (pkhs [][20]byte, err error)

func (*Wallet) PrepareAt

func (w *Wallet) PrepareAt(c *core.Chain, expected core.ChainTipSnapshot, toAddr string, amount, fee int64, excluded map[core.OutPoint]struct{}) (snapshot Snapshot, prepared *PreparedPayment, err error)

PrepareAt derives the snapshot anchor and signs using one lock-scoped key view, preventing concurrent wallet mutation from mismatching the returned snapshot hash and transaction.

func (*Wallet) PrimaryPKH

func (w *Wallet) PrimaryPKH() [20]byte

func (*Wallet) PrimaryPKHE

func (w *Wallet) PrimaryPKHE() (primary [20]byte, err error)

PrimaryPKHE strictly reloads the wallet under its OS lock and returns the first reward PKH. Missing, corrupt, unreadable, hard-linked, empty, and all-zero identities fail closed.

func (*Wallet) Send

func (w *Wallet) Send(c *core.Chain, to string, amount, fee int64) (*core.Tx, error)

Send is the legacy human wrapper. Machine flows use BuildPayment followed by a separately controlled SubmitPayment/broadcast boundary.

func (*Wallet) SnapshotAt

func (w *Wallet) SnapshotAt(c *core.Chain, expected core.ChainTipSnapshot) (snapshot Snapshot, err error)

SnapshotAt locks the wallet and derives a deterministic spendable snapshot at the exact expected persisted chain tip.