bitbox

README

Bitbox is a golang library that utilize bitcoind regtest mode to create environment for testing your apps.

Quick start

Use example below to bootstrap your tests.

import "github.com/angrypie/bitbox"

func TestSomething(t *testing.T) {
	client := bitbox.New()
	//Start 2 bitcoind nodes connected together
	err := client.Start(2) // you should have bitcoind installed
	if err != nil {
		t.Error(err)
	}
	blocks, _ := client.BlockHeight()        // get current network block height
	client.Generate(0, 105)                  // generate first blocks, reward will go to 0 account
	address, _ := client.Address(1)          // get new address of second node
	tx, _ := client.Send(0, address, 0.0001) // send funds from first node to second
	client.Generate(0, 1)                    // generate another block to get confirmation

	log.Println(block, address, tx)
	// In real world don't forget to check errors
}

Documentation

Index

• type Bitbox
  • func New(args ...string) (bitbox Bitbox)
• type BitboxDefaults
  • func (b *BitboxDefaults) AccountAddress(node int, account string) (address string, err error)
  • func (b *BitboxDefaults) AccountBalance(node int, account string) (balance float64, err error)
  • func (b *BitboxDefaults) BlockHeight() (blocks int32, err error)
  • func (b *BitboxDefaults) Client(nodeIndex int) *rpcclient.Client
  • func (b *BitboxDefaults) CreateNodes(nodes int, create createNodeFunc) (err error)
  • func (b *BitboxDefaults) Generate(node int, blocks uint32) (err error)
  • func (b *BitboxDefaults) GetRawTransaction(txHash string) (result *btcutil.Tx, err error)
  • func (b *BitboxDefaults) Info() *State
  • func (b *BitboxDefaults) Send(node int, address string, amount float64) (tx string, err error)
  • func (b *BitboxDefaults) Stop() (err error)
• type Bitcoind
  • func (b *Bitcoind) Address(node int) (address string, err error)
  • func (b *Bitcoind) Balance(node int) (balance float64, err error)
  • func (b *Bitcoind) InitMempool() error
  • func (b *Bitcoind) Start(nodes int) (err error)
• type Btcd
  • func (b *Btcd) Address(node int) (address string, err error)
  • func (b *Btcd) Balance(node int) (balance float64, err error)
  • func (b *Btcd) InitMempool() error
  • func (b *Btcd) Send(node int, address string, amount float64) (tx string, err error)
  • func (b *Btcd) Start(nodes int) (err error)
• type Node
• type State

Types

type Bitbox

type Bitbox interface {
	//Start runs specified number of bitcoind nodes in regtest mode.
	Start(nodes int) (err error)
	//Stop terminates all nodes, nnd cleans data directories.
	Stop() (err error)
	//Info returns information about bitbox state.
	Info() *State
	//Generate perform blocks mining.
	Generate(nodeIndex int, blocks uint32) (err error)
	//Send sends funds from node to specified address.
	Send(node int, address string, amount float64) (tx string, err error)
	//Balance returns avaliable balance of specified nodes wallet.
	Balance(node int) (balance float64, err error)
	//Address generates new adderess of specified nodes wallet.
	Address(node int) (address string, err error)
	//GetRawTransaction returns raw transaction by hash.
	GetRawTransaction(txHash string) (result *btcutil.Tx, err error)
	//BlockHeight returns current block height.
	BlockHeight() (blocks int32, err error)
	//InitMempool makes mempool usable by sending transaction and generating blocks.
	InitMempool() (err error)
}

Bitbox represent API interface to multiple bitcoin nodes, that are running in regtest/simnet mode.

func New

func New(args ...string) (bitbox Bitbox)

New creates new Bitbox client. Pass 'btcd' as first argument to use such backend, by default 'bitcoind' is used.

type BitboxDefaults

type BitboxDefaults struct {
	Nodes       []Node
	NodesNumber int
	Started     bool
}

func (*BitboxDefaults) AccountAddress

func (b *BitboxDefaults) AccountAddress(node int, account string) (address string, err error)

Address generates new adderess of specified nodes wallet.

func (*BitboxDefaults) AccountBalance

func (b *BitboxDefaults) AccountBalance(node int, account string) (balance float64, err error)

Balance returns avaliable balance of specified nodes wallet.

func (*BitboxDefaults) BlockHeight

func (b *BitboxDefaults) BlockHeight() (blocks int32, err error)

BlockHeight returns current block height.

func (*BitboxDefaults) Client

func (b *BitboxDefaults) Client(nodeIndex int) *rpcclient.Client

func (*BitboxDefaults) CreateNodes

func (b *BitboxDefaults) CreateNodes(nodes int, create createNodeFunc) (err error)

Start runs specified number of bitcoin nodes in regtest/simnet mode.

func (*BitboxDefaults) Generate

func (b *BitboxDefaults) Generate(node int, blocks uint32) (err error)

Generate perform blocks mining.

func (*BitboxDefaults) GetRawTransaction

func (b *BitboxDefaults) GetRawTransaction(txHash string) (result *btcutil.Tx, err error)

GetRawTransaction returns raw transaction by hash.

func (*BitboxDefaults) Info

func (b *BitboxDefaults) Info() *State

Info returns information about bitbox state.

func (*BitboxDefaults) Send

func (b *BitboxDefaults) Send(node int, address string, amount float64) (tx string, err error)

func (*BitboxDefaults) Stop

func (b *BitboxDefaults) Stop() (err error)

Stop terminates all nodes, nnd cleans data directories.

type Bitcoind

type Bitcoind struct {
	BitboxDefaults
}

func (*Bitcoind) Address

func (b *Bitcoind) Address(node int) (address string, err error)

Address generates new adderess of specified nodes wallet.

func (*Bitcoind) Balance

func (b *Bitcoind) Balance(node int) (balance float64, err error)

Balance returns avaliable balance of specified nodes wallet.

func (*Bitcoind) InitMempool

func (b *Bitcoind) InitMempool() error

InitMempool makes mempool usable by sending transaction and generating blocks.

func (*Bitcoind) Start

func (b *Bitcoind) Start(nodes int) (err error)

Start runs specified number of bitcoind nodes in regtest mode.

type Btcd

type Btcd struct {
	BitboxDefaults
}

func (*Btcd) Address

func (b *Btcd) Address(node int) (address string, err error)

Address generates new adderess of specified nodes wallet.

func (*Btcd) Balance

func (b *Btcd) Balance(node int) (balance float64, err error)

Balance returns avaliable balance of specified nodes wallet.

func (*Btcd) InitMempool

func (b *Btcd) InitMempool() error

InitMempool makes mempool usable by sending transaction and generating blocks.

func (*Btcd) Send

func (b *Btcd) Send(node int, address string, amount float64) (tx string, err error)

Send sends funds from node to specified address.

func (*Btcd) Start

func (b *Btcd) Start(nodes int) (err error)

Start runs specified number of btcd nodes in simnet mode.

type Node

type Node interface {
	Start() error
	Stop() error
	Client() *rpcclient.Client
	Info() *State
}

type State

type State struct {
	Name        string
	NodePort    string
	RPCPort     string
	ZmqAddress  string
	IsStarted   bool
	NodesNumber int
}

State represent current bitbox state, contain useful info.