bitboxbase

README

BitBox Base Integration

The code in this directory contains the logic needed for integration of the desktop app with the BitBox Base. There are two ways to connect with a BitBox Base.

• By connecting directly with the network address of the base
• Automatically by mdns

The package mdns implements these two connection variants. Both variants attempt a connection with the TryMakeNewBase function, given an ip. TryMakeNewBase will attempt to create a new BitBoxBase instance with NewBitBoxBase, given a valid ip. NewBitBoxBase calls the Connect function from the rpcclient package. Here, the connection is first checked with an initial get request. Subsequently a websocket connection is spawned. A noise 'XX' three part handshake is performed through the websocket connection with the base. Once the noise handshake is done, the base checks if user verification of the noise channel's binding hash has to be done. If yes, an event is emitted containing the pairing channel hash that the user can then compare with the base. All traffic from and to the base should be noise encrypted hereafter. The websocket is then passed to a separate goroutine where it listens indefinitely and emits events when receiving data.

To orchestrate between multiple connections, the backend keeps a map of connected BitBox Bases, by mapping from a unique ID assigned to each Base on connection to their instantiation. It also creates a NewDetector and gives it function callbacks to register and deregister BitBox Bases. This detector instance listens for new BitBox Bases on the local network indefinitely. When a new one is found, it calls TryMakeNewBase, and the passed-in register callback. The callback then triggers an event letting the frontend know that a new BitBox Base is registered. The frontend then gets all the registered BitBox Bases's IDs and starts listening for events. The callback also subscribes the backend to any events that the websocket connection with the Base emits and passes these to the websocket in the handlers package.

The handler also exposes a http POST endpoint that allows for direct connection with the base. For this, it passes an ip to the backend's detector instance that then subsequently calls TryMakeNewBase.

When a detector, or bitboxbase is instantiated, a pointer to the backend's config is passed to them. This allows them to write new configurations to connect to the electrs server on the base. For this the handler exposes a 'connectelectrum' POST endpoint.

The communication between the BitBox Base and the wallet app is done with go's rpc package. Responses from rpc calls are written into data structures as defined in rpcclient.go. The rpcclient is also capable of receiving notifications. To this end a special notification byte is sent to the rpcclient's websocket and on receival triggers a corresponding rpc call.

Documentation

Index

• type BitBoxBase
  • func NewBitBoxBase(address string, id string, config *config.Config, bitboxBaseConfigDir string, ...) (*BitBoxBase, error)
  • func (base *BitBoxBase) ChannelHash() (string, bool)
  • func (base *BitBoxBase) Close()
  • func (base *BitBoxBase) ConnectElectrum() error
  • func (base *BitBoxBase) ConnectRPCClient() error
  • func (base *BitBoxBase) Deregister() (bool, error)
  • func (base *BitBoxBase) GetRegisterTime() time.Time
  • func (base *BitBoxBase) Identifier() string
  • func (base *BitBoxBase) MiddlewareInfo() (rpcmessages.SampleInfoResponse, error)
  • func (base *BitBoxBase) Ping() (bool, error)
  • func (base *BitBoxBase) RPCClient() *rpcclient.RPCClient
  • func (base *BitBoxBase) Self() *BitBoxBase
  • func (base *BitBoxBase) Status() bitboxbasestatus.Status
  • func (base *BitBoxBase) SyncWithOption(option SyncOption) (bool, error)
  • func (base *BitBoxBase) VerificationProgress() (rpcmessages.VerificationProgressResponse, error)
• type Interface
• type SyncOption

Types

type BitBoxBase

type BitBoxBase struct {
	observable.Implementation
	// contains filtered or unexported fields
}

BitBoxBase provides the dictated bitboxbase api to communicate with the base

func NewBitBoxBase

func NewBitBoxBase(address string, id string, config *config.Config, bitboxBaseConfigDir string, onUnregister func(string)) (*BitBoxBase, error)

NewBitBoxBase creates a new bitboxBase instance

func (*BitBoxBase) ChannelHash

func (base *BitBoxBase) ChannelHash() (string, bool)

ChannelHash returns the bitboxbase's rpcClient noise channel hash

func (*BitBoxBase) Close

func (base *BitBoxBase) Close()

Close implements a method to unset the bitboxBase

func (*BitBoxBase) ConnectElectrum

func (base *BitBoxBase) ConnectElectrum() error

ConnectElectrum connects to the electrs server on the base and configures the backend accordingly

func (*BitBoxBase) ConnectRPCClient

func (base *BitBoxBase) ConnectRPCClient() error

ConnectRPCClient starts the connection with the remote bitbox base middleware

func (*BitBoxBase) Deregister

func (base *BitBoxBase) Deregister() (bool, error)

Deregister calls the backend's BitBoxBaseDeregister callback and sends a notification to the frontend, if bitboxbase is active. If bitboxbase is not active, an error is returned.

func (*BitBoxBase) GetRegisterTime

func (base *BitBoxBase) GetRegisterTime() time.Time

GetRegisterTime implements a getter for the timestamp of when the bitbox base was registered

func (*BitBoxBase) Identifier

func (base *BitBoxBase) Identifier() string

Identifier implements a getter for the bitboxBase ID

func (*BitBoxBase) MiddlewareInfo

func (base *BitBoxBase) MiddlewareInfo() (rpcmessages.SampleInfoResponse, error)

MiddlewareInfo returns the received MiddlewareInfo packet from the rpcClient

func (*BitBoxBase) Ping

func (base *BitBoxBase) Ping() (bool, error)

Ping sends a get requset to the bitbox base middleware root handler and returns true if successful

func (*BitBoxBase) RPCClient

func (base *BitBoxBase) RPCClient() *rpcclient.RPCClient

RPCClient returns ths current instance of the rpcClient

func (*BitBoxBase) Self

func (base *BitBoxBase) Self() *BitBoxBase

Self returns the current bitbox base instance.

func (*BitBoxBase) Status

func (base *BitBoxBase) Status() bitboxbasestatus.Status

Status returns the current state of the bitboxbase.

func (*BitBoxBase) SyncWithOption

func (base *BitBoxBase) SyncWithOption(option SyncOption) (bool, error)

SyncWithOption returns true if the chosen sync option was executed successfully

func (*BitBoxBase) VerificationProgress

func (base *BitBoxBase) VerificationProgress() (rpcmessages.VerificationProgressResponse, error)

VerificationProgress returns the received VerificationProgress packet from the rpcClient

type Interface

type Interface interface {

	// Identifier returns the bitboxBaseID.
	Identifier() string

	// GetRPCClient returns the rpcClient so we can listen to its events.
	RPCClient() *rpcclient.RPCClient

	// Close tells the bitboxbase to close all connections.
	Close()

	// GetRegisterTime implements a getter for the timestamp of when the bitboxBase was registered
	GetRegisterTime() time.Time

	// MiddlewareInfo returns some blockchain information.
	MiddlewareInfo() (rpcmessages.SampleInfoResponse, error)

	// VerificationProgress returns the bitcoind verification progress.
	VerificationProgress() (rpcmessages.VerificationProgressResponse, error)

	// ConnectElectrum connects to the electrs server on the base and configures the backend accordingly
	ConnectElectrum() error

	// Ping sends a get requset to the bitbox base middleware root handler and returns true if successful
	Ping() (bool, error)

	// Self returns an instance of the base
	Self() *BitBoxBase

	// Status returns the current status of the base
	Status() bitboxbasestatus.Status

	// ChannelHash returns the hash of the noise channel
	ChannelHash() (string, bool)

	// Deregister calls the backend's BitBoxBase Deregister callback and sends a notification to the frontend, if bitboxbase is active.
	// If bitboxbase is not active, an error is returned.
	Deregister() (bool, error)

	// SyncOption returns true if the bitcoin resync rpc call executed successfully
	SyncWithOption(SyncOption) (bool, error)
}

Interface represents bitbox base.

type SyncOption

type SyncOption string

SyncOption is a user provided blockchain sync option during BBB initialization

const (
	SyncOptionPresynced            SyncOption = "preSynced"
	SyncOptionReindex              SyncOption = "reindex"
	SyncOptionInitialBlockDownload SyncOption = "initialBlockDownload"
)

SyncOption iota has three options: Accept pre-synchronized blockchain; delete the chainstate and reindex; resync bitcon from scratch with an IBD