bchwallet: github.com/gcash/bchwallet/wtxmgr Index | Examples | Files

package wtxmgr

import "github.com/gcash/bchwallet/wtxmgr"

Package wtxmgr provides an implementation of a transaction database handling spend tracking for a bitcoin wallet. Its primary purpose is to save transactions with outputs spendable with wallet keys and transactions that are signed by wallet keys in memory, handle spend tracking for unspent outputs and newly-inserted transactions, and report the spendable balance from each unspent transaction output. It uses walletdb as the backend for storing the serialized transaction objects in buckets.

Transaction outputs which are spendable by wallet keys are called credits (because they credit to a wallet's total spendable balance). Transaction inputs which spend previously-inserted credits are called debits (because they debit from the wallet's spendable balance).

Spend tracking is mostly automatic. When a new transaction is inserted, if it spends from any unspent credits, they are automatically marked spent by the new transaction, and each input which spent a credit is marked as a debit. However, transaction outputs of inserted transactions must manually marked as credits, as this package has no knowledge of wallet keys or addresses, and therefore cannot determine which outputs may be spent.

Details regarding individual transactions and their credits and debits may be queried either by just a transaction hash, or by hash and block. When querying for just a transaction hash, the most recent transaction with a matching hash will be queried. However, because transaction hashes may collide with other transaction hashes, methods to query for specific transactions in the chain (or unmined) are provided as well.

Code:

// Open the database.
db, dbTeardown, err := testDB()
defer dbTeardown()
if err != nil {
    fmt.Println(err)
    return
}

// Open a read-write transaction to operate on the database.
dbtx, err := db.BeginReadWriteTx()
if err != nil {
    fmt.Println(err)
    return
}
defer dbtx.Commit()

// Create a bucket for the transaction store.
b, err := dbtx.CreateTopLevelBucket([]byte("txstore"))
if err != nil {
    fmt.Println(err)
    return
}

// Create and open the transaction store in the provided namespace.
err = Create(b)
if err != nil {
    fmt.Println(err)
    return
}
s, err := Open(b, &chaincfg.TestNet3Params)
if err != nil {
    fmt.Println(err)
    return
}

// Insert an unmined transaction that outputs 10 BCH to a wallet address
// at output 0.
err = s.InsertTx(b, exampleTxRecordA, nil)
if err != nil {
    fmt.Println(err)
    return
}
err = s.AddCredit(b, exampleTxRecordA, nil, 0, false)
if err != nil {
    fmt.Println(err)
    return
}

// Insert a second transaction which spends the output, and creates two
// outputs.  Mark the second one (5 BCH) as wallet change.
err = s.InsertTx(b, exampleTxRecordB, nil)
if err != nil {
    fmt.Println(err)
    return
}
err = s.AddCredit(b, exampleTxRecordB, nil, 1, true)
if err != nil {
    fmt.Println(err)
    return
}

// Mine each transaction in a block at height 100.
err = s.InsertTx(b, exampleTxRecordA, &exampleBlock100)
if err != nil {
    fmt.Println(err)
    return
}
err = s.InsertTx(b, exampleTxRecordB, &exampleBlock100)
if err != nil {
    fmt.Println(err)
    return
}

// Print the one confirmation balance.
bal, err := s.Balance(b, 1, 100)
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println(bal)

// Fetch unspent outputs.
utxos, err := s.UnspentOutputs(b)
if err != nil {
    fmt.Println(err)
}
expectedOutPoint := wire.OutPoint{Hash: exampleTxRecordB.Hash, Index: 1}
for _, utxo := range utxos {
    fmt.Println(utxo.OutPoint == expectedOutPoint)
}

Output:

5 BCH
true

Index

Examples

Package Files

db.go doc.go error.go kahnsort.go log.go migrations.go query.go tx.go unconfirmed.go

func Create Uses

func Create(ns walletdb.ReadWriteBucket) error

Create creates a new persistent transaction store in the walletdb namespace. Creating the store when one already exists in this namespace will error with ErrAlreadyExists.

func DependencySort Uses

func DependencySort(txs map[chainhash.Hash]*wire.MsgTx) []*wire.MsgTx

DependencySort topologically sorts a set of transactions by their dependency order. It is implemented using Kahn's algorithm.

func DisableLog Uses

func DisableLog()

DisableLog disables all library log output. Logging output is disabled by default until either UseLogger or SetLogWriter are called.

func IsNoExists Uses

func IsNoExists(err error) bool

IsNoExists returns whether an error is a Error with the ErrNoExists error code.

func UseLogger Uses

func UseLogger(logger bchlog.Logger)

UseLogger uses a specified Logger to output package logging info. This should be used in preference to SetLogWriter if the caller is also using bchlog.

type Block Uses

type Block struct {
    Hash   chainhash.Hash
    Height int32
}

Block contains the minimum amount of data to uniquely identify any block on either the best or side chain.

type BlockMeta Uses

type BlockMeta struct {
    Block
    Time time.Time
}

BlockMeta contains the unique identification for a block and any metadata pertaining to the block. At the moment, this additional metadata only includes the block time from the block header.

type Credit Uses

type Credit struct {
    wire.OutPoint
    BlockMeta
    Amount       bchutil.Amount
    PkScript     []byte
    Received     time.Time
    FromCoinBase bool
}

Credit is the type representing a transaction output which was spent or is still spendable by wallet. A UTXO is an unspent Credit, but not all Credits are UTXOs.

type CreditRecord Uses

type CreditRecord struct {
    Amount bchutil.Amount
    Index  uint32
    Spent  bool
    Change bool
}

CreditRecord contains metadata regarding a transaction credit for a known transaction. Further details may be looked up by indexing a wire.MsgTx.TxOut with the Index field.

type DebitRecord Uses

type DebitRecord struct {
    Amount bchutil.Amount
    Index  uint32
}

DebitRecord contains metadata regarding a transaction debit for a known transaction. Further details may be looked up by indexing a wire.MsgTx.TxIn with the Index field.

type Error Uses

type Error struct {
    Code ErrorCode // Describes the kind of error
    Desc string    // Human readable description of the issue
    Err  error     // Underlying error, optional
}

Error provides a single type for errors that can happen during Store operation.

func (Error) Error Uses

func (e Error) Error() string

Error satisfies the error interface and prints human-readable errors.

type ErrorCode Uses

type ErrorCode uint8

ErrorCode identifies a category of error.

const (
    // ErrDatabase indicates an error with the underlying database.  When
    // this error code is set, the Err field of the Error will be
    // set to the underlying error returned from the database.
    ErrDatabase ErrorCode = iota

    // ErrData describes an error where data stored in the transaction
    // database is incorrect.  This may be due to missing values, values of
    // wrong sizes, or data from different buckets that is inconsistent with
    // itself.  Recovering from an ErrData requires rebuilding all
    // transaction history or manual database surgery.  If the failure was
    // not due to data corruption, this error category indicates a
    // programming error in this package.
    ErrData

    // ErrInput describes an error where the variables passed into this
    // function by the caller are obviously incorrect.  Examples include
    // passing transactions which do not serialize, or attempting to insert
    // a credit at an index for which no transaction output exists.
    ErrInput

    // ErrAlreadyExists describes an error where creating the store cannot
    // continue because a store already exists in the namespace.
    ErrAlreadyExists

    // ErrNoExists describes an error where the store cannot be opened due to
    // it not already existing in the namespace.  This error should be
    // handled by creating a new store.
    ErrNoExists

    // ErrNeedsUpgrade describes an error during store opening where the
    // database contains an older version of the store.
    ErrNeedsUpgrade

    // ErrUnknownVersion describes an error where the store already exists
    // but the database version is newer than latest version known to this
    // software.  This likely indicates an outdated binary.
    ErrUnknownVersion
)

These constants are used to identify a specific Error.

func (ErrorCode) String Uses

func (e ErrorCode) String() string

String returns the ErrorCode as a human-readable name.

type MigrationManager Uses

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

MigrationManager is an implementation of the migration.Manager interface that will be used to handle migrations for the address manager. It exposes the necessary parameters required to successfully perform migrations.

func NewMigrationManager Uses

func NewMigrationManager(ns walletdb.ReadWriteBucket) *MigrationManager

NewMigrationManager creates a new migration manager for the transaction manager. The given bucket should reflect the top-level bucket in which all of the transaction manager's data is contained within.

func (*MigrationManager) CurrentVersion Uses

func (m *MigrationManager) CurrentVersion(ns walletdb.ReadBucket) (uint32, error)

CurrentVersion returns the current version of the service's database.

NOTE: This method is part of the migration.Manager interface.

func (*MigrationManager) Name Uses

func (m *MigrationManager) Name() string

Name returns the name of the service we'll be attempting to upgrade.

NOTE: This method is part of the migration.Manager interface.

func (*MigrationManager) Namespace Uses

func (m *MigrationManager) Namespace() walletdb.ReadWriteBucket

Namespace returns the top-level bucket of the service.

NOTE: This method is part of the migration.Manager interface.

func (*MigrationManager) SetVersion Uses

func (m *MigrationManager) SetVersion(ns walletdb.ReadWriteBucket,
    version uint32) error

SetVersion sets the version of the service's database.

NOTE: This method is part of the migration.Manager interface.

func (*MigrationManager) Versions Uses

func (m *MigrationManager) Versions() []migration.Version

Versions returns all of the available database versions of the service.

NOTE: This method is part of the migration.Manager interface.

type Store Uses

type Store struct {

    // Event callbacks.  These execute in the same goroutine as the wtxmgr
    // caller.
    NotifyUnspent func(hash *chainhash.Hash, index uint32)
    // contains filtered or unexported fields
}

Store implements a transaction store for storing and managing wallet transactions.

func Open Uses

func Open(ns walletdb.ReadBucket, chainParams *chaincfg.Params) (*Store, error)

Open opens the wallet transaction store from a walletdb namespace. If the store does not exist, ErrNoExist is returned.

func (*Store) AddCredit Uses

func (s *Store) AddCredit(ns walletdb.ReadWriteBucket, rec *TxRecord, block *BlockMeta, index uint32, change bool) error

AddCredit marks a transaction record as containing a transaction output spendable by wallet. The output is added unspent, and is marked spent when a new transaction spending the output is inserted into the store.

TODO(jrick): This should not be necessary. Instead, pass the indexes that are known to contain credits when a transaction or merkleblock is inserted into the store.

func (*Store) Balance Uses

func (s *Store) Balance(ns walletdb.ReadBucket, minConf int32, syncHeight int32) (bchutil.Amount, error)

Balance returns the spendable wallet balance (total value of all unspent transaction outputs) given a minimum of minConf confirmations, calculated at a current chain height of curHeight. Coinbase outputs are only included in the balance if maturity has been reached.

Balance may return unexpected results if syncHeight is lower than the block height of the most recent mined transaction in the store.

This example demonstrates reporting the Store balance given an unmined and mined transaction given 0, 1, and 6 block confirmations.

Code:

s, db, teardown, err := testStore()
defer teardown()
if err != nil {
    fmt.Println(err)
    return
}

// Prints balances for 0 block confirmations, 1 confirmation, and 6
// confirmations.
printBalances := func(syncHeight int32) {
    dbtx, err := db.BeginReadTx()
    if err != nil {
        fmt.Println(err)
        return
    }
    defer dbtx.Rollback()
    ns := dbtx.ReadBucket(namespaceKey)
    zeroConfBal, err := s.Balance(ns, 0, syncHeight)
    if err != nil {
        fmt.Println(err)
        return
    }
    oneConfBal, err := s.Balance(ns, 1, syncHeight)
    if err != nil {
        fmt.Println(err)
        return
    }
    sixConfBal, err := s.Balance(ns, 6, syncHeight)
    if err != nil {
        fmt.Println(err)
        return
    }
    fmt.Printf("%v, %v, %v\n", zeroConfBal, oneConfBal, sixConfBal)
}

// Insert a transaction which outputs 10 BCH unmined and mark the output
// as a credit.
err = walletdb.Update(db, func(tx walletdb.ReadWriteTx) error {
    ns := tx.ReadWriteBucket(namespaceKey)
    err := s.InsertTx(ns, exampleTxRecordA, nil)
    if err != nil {
        return err
    }
    return s.AddCredit(ns, exampleTxRecordA, nil, 0, false)
})
if err != nil {
    fmt.Println(err)
    return
}
printBalances(100)

// Mine the transaction in block 100 and print balances again with a
// sync height of 100 and 105 blocks.
err = walletdb.Update(db, func(tx walletdb.ReadWriteTx) error {
    ns := tx.ReadWriteBucket(namespaceKey)
    return s.InsertTx(ns, exampleTxRecordA, &exampleBlock100)
})
if err != nil {
    fmt.Println(err)
    return
}
printBalances(100)
printBalances(105)

Output:

10 BCH, 0 BCH, 0 BCH
10 BCH, 10 BCH, 0 BCH
10 BCH, 10 BCH, 10 BCH

func (*Store) InsertTx Uses

func (s *Store) InsertTx(ns walletdb.ReadWriteBucket, rec *TxRecord, block *BlockMeta) error

InsertTx records a transaction as belonging to a wallet's transaction history. If block is nil, the transaction is considered unspent, and the transaction's index must be unset.

func (*Store) PreviousPkScripts Uses

func (s *Store) PreviousPkScripts(ns walletdb.ReadBucket, rec *TxRecord, block *Block) ([][]byte, error)

PreviousPkScripts returns a slice of previous output scripts for each credit output this transaction record debits from.

func (*Store) RangeTransactions Uses

func (s *Store) RangeTransactions(ns walletdb.ReadBucket, begin, end int32,
    f func([]TxDetails) (bool, error)) error

RangeTransactions runs the function f on all transaction details between blocks on the best chain over the height range [begin,end]. The special height -1 may be used to also include unmined transactions. If the end height comes before the begin height, blocks are iterated in reverse order and unmined transactions (if any) are processed first.

The function f may return an error which, if non-nil, is propagated to the caller. Additionally, a boolean return value allows exiting the function early without reading any additional transactions early when true.

All calls to f are guaranteed to be passed a slice with more than zero elements. The slice may be reused for multiple blocks, so it is not safe to use it after the loop iteration it was acquired.

func (*Store) RemoveUnminedTx Uses

func (s *Store) RemoveUnminedTx(ns walletdb.ReadWriteBucket, rec *TxRecord) error

RemoveUnminedTx attempts to remove an unmined transaction from the transaction store. This is to be used in the scenario that a transaction that we attempt to rebroadcast, turns out to double spend one of our existing inputs. This function we remove the conflicting transaction identified by the tx record, and also recursively remove all transactions that depend on it.

func (*Store) Rollback Uses

func (s *Store) Rollback(ns walletdb.ReadWriteBucket, height int32) error

Rollback removes all blocks at height onwards, moving any transactions within each block to the unconfirmed pool.

Code:

s, db, teardown, err := testStore()
defer teardown()
if err != nil {
    fmt.Println(err)
    return
}

err = walletdb.Update(db, func(tx walletdb.ReadWriteTx) error {
    ns := tx.ReadWriteBucket(namespaceKey)

    // Insert a transaction which outputs 10 BCH in a block at height 100.
    err := s.InsertTx(ns, exampleTxRecordA, &exampleBlock100)
    if err != nil {
        return err
    }

    // Rollback everything from block 100 onwards.
    err = s.Rollback(ns, 100)
    if err != nil {
        return err
    }

    // Assert that the transaction is now unmined.
    details, err := s.TxDetails(ns, &exampleTxRecordA.Hash)
    if err != nil {
        return err
    }
    if details == nil {
        return fmt.Errorf("no details found")
    }
    fmt.Println(details.Block.Height)
    return nil
})
if err != nil {
    fmt.Println(err)
    return
}

Output:

-1

func (*Store) TxDetails Uses

func (s *Store) TxDetails(ns walletdb.ReadBucket, txHash *chainhash.Hash) (*TxDetails, error)

TxDetails looks up all recorded details regarding a transaction with some hash. In case of a hash collision, the most recent transaction with a matching hash is returned.

Not finding a transaction with this hash is not an error. In this case, a nil TxDetails is returned.

func (*Store) UniqueTxDetails Uses

func (s *Store) UniqueTxDetails(ns walletdb.ReadBucket, txHash *chainhash.Hash,
    block *Block) (*TxDetails, error)

UniqueTxDetails looks up all recorded details for a transaction recorded mined in some particular block, or an unmined transaction if block is nil.

Not finding a transaction with this hash from this block is not an error. In this case, a nil TxDetails is returned.

func (*Store) UnminedTxHashes Uses

func (s *Store) UnminedTxHashes(ns walletdb.ReadBucket) ([]*chainhash.Hash, error)

UnminedTxHashes returns the hashes of all transactions not known to have been mined in a block.

func (*Store) UnminedTxs Uses

func (s *Store) UnminedTxs(ns walletdb.ReadBucket) ([]*wire.MsgTx, error)

UnminedTxs returns the underlying transactions for all unmined transactions which are not known to have been mined in a block. Transactions are guaranteed to be sorted by their dependency order.

func (*Store) UnspentOutputs Uses

func (s *Store) UnspentOutputs(ns walletdb.ReadBucket) ([]Credit, error)

UnspentOutputs returns all unspent received transaction outputs. The order is undefined.

type TxDetails Uses

type TxDetails struct {
    TxRecord
    Block   BlockMeta
    Credits []CreditRecord
    Debits  []DebitRecord
}

TxDetails is intended to provide callers with access to rich details regarding a relevant transaction and which inputs and outputs are credit or debits.

type TxRecord Uses

type TxRecord struct {
    MsgTx        wire.MsgTx
    Hash         chainhash.Hash
    Received     time.Time
    SerializedTx []byte // Optional: may be nil
}

TxRecord represents a transaction managed by the Store.

func NewTxRecord Uses

func NewTxRecord(serializedTx []byte, received time.Time) (*TxRecord, error)

NewTxRecord creates a new transaction record that may be inserted into the store. It uses memoization to save the transaction hash and the serialized transaction.

func NewTxRecordFromMsgTx Uses

func NewTxRecordFromMsgTx(msgTx *wire.MsgTx, received time.Time) (*TxRecord, error)

NewTxRecordFromMsgTx creates a new transaction record that may be inserted into the store.

Package wtxmgr imports 12 packages (graph) and is imported by 6 packages. Updated 2019-09-04. Refresh now. Tools for package owners.