database

package
v0.0.1-ppc Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 9, 2015 License: ISC Imports: 6 Imported by: 0

README

database

[Build Status] (https://travis-ci.org/ppcsuite/ppcd) ![ISC License] (http://img.shields.io/badge/license-ISC-blue.svg)

Package database provides a database interface for the bitcoin block chain and transactions.

Please note that this package is intended to enable btcd to support different database backends and is not something that a client can directly access as only one entity can have the database open at a time (for most database backends), and that entity will be btcd.

When a client wants programmatic access to the data provided by btcd, they'll likely want to use the btcrpcclient package which makes use of the [JSON-RPC API] (https://github.com/ppcsuite/ppcd/tree/master/docs/json_rpc_api.md).

Documentation

[GoDoc] (http://godoc.org/github.com/ppcsuite/ppcd/database)

Full go doc style documentation for the project can be viewed online without installing this package by using the GoDoc site here.

You can also view the documentation locally once the package is installed with the godoc tool by running godoc -http=":6060" and pointing your browser to http://localhost:6060/pkg/github.com/ppcsuite/ppcd/database

Installation

$ go get github.com/ppcsuite/ppcd/database

Examples

TODO

  • Increase test coverage to 100%

GPG Verification Key

All official release tags are signed by Conformal so users can ensure the code has not been tampered with and is coming from the btcsuite developers. To verify the signature perform the following:

  • Download the public key from the Conformal website at https://opensource.conformal.com/GIT-GPG-KEY-conformal.txt

  • Import the public key into your GPG keyring:

    gpg --import GIT-GPG-KEY-conformal.txt

  • Verify the release tag with the following command where TAG_NAME is a placeholder for the specific tag:

    git tag -v TAG_NAME

License

Package database is licensed under the copyfree ISC License.

Documentation

Overview

Package database provides a database interface for the Bitcoin block chain.

As of July 2014, there are over 309,000 blocks in the Bitcoin block chain and and over 42 million transactions (which turns out to be over 21GB of data). This package provides a database layer to store and retrieve this data in a fairly simple and efficient manner. The use of this should not require specific knowledge of the database backend.

Basic Design

The basic design of this package is to provide two classes of items in a database; blocks and transactions (tx) where the block number increases monotonically. Each transaction belongs to a single block although a block can have a variable number of transactions. Along with these two items, several convenience functions for dealing with the database are provided as well as functions to query specific items that may be present in a block or tx.

Usage

At the highest level, the use of this packages just requires that you import it, setup a database, insert some data into it, and optionally, query the data back. The first block inserted into the database will be treated as the genesis block. Every subsequent block insert requires the referenced parent block to already exist.

Index

Examples

Constants

View Source 
const AddrIndexKeySize = ripemd160.Size

AddrIndexKeySize is the number of bytes used by keys into the BlockAddrIndex.

View Source 
const AllShas = int64(^uint64(0) >> 1)

AllShas is a special value that can be used as the final sha when requesting a range of shas by height to request them all.

Variables

View Source 
var (
	ErrAddrIndexDoesNotExist  = errors.New("address index hasn't been built or is an older version")
	ErrUnsupportedAddressType = errors.New("address type is not supported " +
		"by the address-index")
	ErrPrevShaMissing  = errors.New("previous sha missing from database")
	ErrTxShaMissing    = errors.New("requested transaction does not exist")
	ErrBlockShaMissing = errors.New("requested block does not exist")
	ErrDuplicateSha    = errors.New("duplicate insert attempted")
	ErrDbDoesNotExist  = errors.New("non-existent database")
	ErrDbUnknownType   = errors.New("non-existent database type")
	ErrNotImplemented  = errors.New("method has not yet been implemented")
)

Errors that the various database functions may return.

Functions

func AddDBDriver 

func AddDBDriver(instance DriverDB)

AddDBDriver adds a back end database driver to available interfaces.

func DisableLog 

func DisableLog()

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

func GetLog 

func GetLog() btclog.Logger

GetLog returns the currently active logger.

func SetLogWriter 

func SetLogWriter(w io.Writer, level string) error

SetLogWriter uses a specified io.Writer to output package logging info. This allows a caller to direct package logging output without needing a dependency on seelog. If the caller is also using btclog, UseLogger should be used instead.

func SupportedDBs 

func SupportedDBs() []string

SupportedDBs returns a slice of strings that represent the database drivers that have been registered and are therefore supported.

func UseLogger 

func UseLogger(logger btclog.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 btclog.

Types

type BlockAddrIndex 

type BlockAddrIndex map[[AddrIndexKeySize]byte][]*wire.TxLoc

BlockAddrIndex represents the indexing structure for addresses. It maps a hash160 to a list of transaction locations within a block that either pays to or spends from the passed UTXO for the hash160.

type Db 

type Db interface {
	// Close cleanly shuts down the database and syncs all data.
	Close() (err error)

	// DropAfterBlockBySha will remove any blocks from the database after
	// the given block.  It terminates any existing transaction and performs
	// its operations in an atomic transaction which is commited before
	// the function returns.
	DropAfterBlockBySha(*wire.ShaHash) (err error)

	// ExistsSha returns whether or not the given block hash is present in
	// the database.
	ExistsSha(sha *wire.ShaHash) (exists bool, err error)

	// FetchBlockBySha returns a btcutil Block.  The implementation may
	// cache the underlying data if desired.
	FetchBlockBySha(sha *wire.ShaHash) (blk *btcutil.Block, err error)

	// FetchBlockHeightBySha returns the block height for the given hash.
	FetchBlockHeightBySha(sha *wire.ShaHash) (height int64, err error)

	// FetchBlockHeaderBySha returns a wire.BlockHeader for the given
	// sha.  The implementation may cache the underlying data if desired.
	FetchBlockHeaderBySha(sha *wire.ShaHash) (bh *wire.BlockHeader, bm *wire.Meta, err error)

	// FetchBlockShaByHeight returns a block hash based on its height in the
	// block chain.
	FetchBlockShaByHeight(height int64) (sha *wire.ShaHash, err error)

	// FetchHeightRange looks up a range of blocks by the start and ending
	// heights.  Fetch is inclusive of the start height and exclusive of the
	// ending height. To fetch all hashes from the start height until no
	// more are present, use the special id `AllShas'.
	FetchHeightRange(startHeight, endHeight int64) (rshalist []wire.ShaHash, err error)

	// ExistsTxSha returns whether or not the given tx hash is present in
	// the database
	ExistsTxSha(sha *wire.ShaHash) (exists bool, err error)

	// FetchTxBySha returns some data for the given transaction hash. The
	// implementation may cache the underlying data if desired.
	FetchTxBySha(txsha *wire.ShaHash) ([]*TxListReply, error)

	// FetchTxByShaList returns a TxListReply given an array of transaction
	// hashes.  The implementation may cache the underlying data if desired.
	// This differs from FetchUnSpentTxByShaList in that it will return
	// the most recent known Tx, if it is fully spent or not.
	//
	// NOTE: This function does not return an error directly since it MUST
	// return at least one TxListReply instance for each requested
	// transaction.  Each TxListReply instance then contains an Err field
	// which can be used to detect errors.
	FetchTxByShaList(txShaList []*wire.ShaHash) []*TxListReply

	// FetchUnSpentTxByShaList returns a TxListReply given an array of
	// transaction hashes.  The implementation may cache the underlying
	// data if desired. Fully spent transactions will not normally not
	// be returned in this operation.
	//
	// NOTE: This function does not return an error directly since it MUST
	// return at least one TxListReply instance for each requested
	// transaction.  Each TxListReply instance then contains an Err field
	// which can be used to detect errors.
	FetchUnSpentTxByShaList(txShaList []*wire.ShaHash) []*TxListReply

	// InsertBlock inserts raw block and transaction data from a block
	// into the database.  The first block inserted into the database
	// will be treated as the genesis block.  Every subsequent block insert
	// requires the referenced parent block to already exist.
	InsertBlock(block *btcutil.Block) (height int64, err error)

	// NewestSha returns the hash and block height of the most recent (end)
	// block of the block chain.  It will return the zero hash, -1 for
	// the block height, and no error (nil) if there are not any blocks in
	// the database yet.
	NewestSha() (sha *wire.ShaHash, height int64, err error)

	// FetchAddrIndexTip returns the hash and block height of the most recent
	// block which has had its address index populated. It will return
	// ErrAddrIndexDoesNotExist along with a zero hash, and -1 if the
	// addrindex hasn't yet been built up.
	FetchAddrIndexTip() (sha *wire.ShaHash, height int64, err error)

	// UpdateAddrIndexForBlock updates the stored addrindex with passed
	// index information for a particular block height. Additionally, it
	// will update the stored meta-data related to the curent tip of the
	// addr index. These two operations are performed in an atomic
	// transaction which is commited before the function returns.
	// Addresses are indexed by the raw bytes of their base58 decoded
	// hash160.
	UpdateAddrIndexForBlock(blkSha *wire.ShaHash, height int64,
		addrIndex BlockAddrIndex) error

	// FetchTxsForAddr looks up and returns all transactions which either
	// spend a previously created output of the passed address, or create
	// a new output locked to the passed address. The, `limit` parameter
	// should be the max number of transactions to be returned.
	// Additionally, if the caller wishes to skip forward in the results
	// some amount, the 'seek' represents how many results to skip.
	// NOTE: Values for both `seek` and `limit` MUST be positive.
	FetchTxsForAddr(addr btcutil.Address, skip int, limit int) ([]*TxListReply, error)

	// DeleteAddrIndex deletes the entire addrindex stored within the DB.
	DeleteAddrIndex() error

	// RollbackClose discards the recent database changes to the previously
	// saved data at last Sync and closes the database.
	RollbackClose() (err error)

	// Sync verifies that the database is coherent on disk and no
	// outstanding transactions are in flight.
	Sync() (err error)
}

Db defines a generic interface that is used to request and insert data into the bitcoin block chain. This interface is intended to be agnostic to actual mechanism used for backend data storage. The AddDBDriver function can be used to add a new backend data storage method.

Example (NewestSha)

This example demonstrates querying the database for the most recent best block height and hash. 

package main

import (
	"fmt"
	"github.com/ppcsuite/btcutil"
	"github.com/ppcsuite/ppcd/chaincfg"
	"github.com/ppcsuite/ppcd/database"

	_ "github.com/ppcsuite/ppcd/database/memdb"
)

// exampleLoadDB is used in the example to elide the setup code.
func exampleLoadDB() (database.Db, error) {
	db, err := database.CreateDB("memdb")
	if err != nil {
		return nil, err
	}

	genesis := btcutil.NewBlock(chaincfg.MainNetParams.GenesisBlock)
	_, err = db.InsertBlock(genesis)
	if err != nil {
		return nil, err
	}

	return db, err
}

func main() {
	// Load a database for the purposes of this example and schedule it to
	// be closed on exit.  See the CreateDB example for more details on what
	// this step is doing.
	db, err := exampleLoadDB()
	if err != nil {
		fmt.Println(err)
		return
	}
	defer db.Close()

	latestHash, latestHeight, err := db.NewestSha()
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println("Latest hash:", latestHash)
	fmt.Println("Latest height:", latestHeight)

}

Output:

Latest hash: 0000000032fe677166d54963b62a4677d8957e87c508eaa4fd7eb1c880cd27e3
Latest height: 0

func CreateDB 

func CreateDB(dbtype string, args ...interface{}) (pbdb Db, err error)

CreateDB intializes and opens a database.

Example

This example demonstrates creating a new database and inserting the genesis block into it. 

package main

import (
	"fmt"
	"github.com/ppcsuite/btcutil"
	"github.com/ppcsuite/ppcd/chaincfg"
	"github.com/ppcsuite/ppcd/database"

	_ "github.com/ppcsuite/ppcd/database/memdb"
)

func main() {
	// Notice in these example imports that the memdb driver is loaded.
	// Ordinarily this would be whatever driver(s) your application
	// requires.
	// import (
	//	"github.com/ppcsuite/ppcd/database"
	// 	_ "github.com/ppcsuite/ppcd/database/memdb"
	// )

	// Create a database and schedule it to be closed on exit.  This example
	// uses a memory-only database to avoid needing to write anything to
	// the disk.  Typically, you would specify a persistent database driver
	// such as "leveldb" and give it a database name as the second
	// parameter.
	db, err := database.CreateDB("memdb")
	if err != nil {
		fmt.Println(err)
		return
	}
	defer db.Close()

	// Insert the main network genesis block.
	genesis := btcutil.NewBlock(chaincfg.MainNetParams.GenesisBlock)
	newHeight, err := db.InsertBlock(genesis)
	if err != nil {
		fmt.Println(err)
		return
	}

	fmt.Println("New height:", newHeight)

}

Output:

New height: 0

func OpenDB 

func OpenDB(dbtype string, args ...interface{}) (pbdb Db, err error)

OpenDB opens an existing database.

type DriverDB 

type DriverDB struct {
	DbType   string
	CreateDB func(args ...interface{}) (pbdb Db, err error)
	OpenDB   func(args ...interface{}) (pbdb Db, err error)
}

DriverDB defines a structure for backend drivers to use when they registered themselves as a backend which implements the Db interface.

type TxListReply 

type TxListReply struct {
	Sha     *wire.ShaHash
	Tx      *wire.MsgTx
	BlkSha  *wire.ShaHash
	Height  int64
	TxSpent []bool
	Err     error
}

TxListReply is used to return individual transaction information when data about multiple transactions is requested in a single call.

Source Files

View all Source files

Directories

Path Synopsis
ldb
Package ldb implements an instance of the database package backed by leveldb.
 Package ldb implements an instance of the database package backed by leveldb.
dbtest
Package memdb implements an instance of the database package that uses memory for the block storage.
 Package memdb implements an instance of the database package that uses memory for the block storage.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.