network

README

bitcoin-network

Go library for connecting an application to the Bitcoin network.

The network layer will open connections to multiple peers (nodes in the Bitcoin network) and query them for addresses of other peers. It maintains a list of peers, with information about recent activity and failures. It takes arbitrary messages as input and send them on to specified peers or broadcast them to all connected peers. Received messages are handed to a dispatcher which based on message type will forward them to subscribers.

example application

The example program in bin/example.go will connect to a few nodes (3 by default) based on DNS lookup, and request to have the transactions in each node's mempool transferred to it (although these will not be used for anything). Broken or failed connections will be replaced by working ones.

$ go run bin/example.go 
2015/09/16 17:46:43.215966 peer.go:90: Connecting to "75.109.245.15:8333".
2015/09/16 17:46:43.216406 peer.go:90: Connecting to "23.234.20.235:8333".
2015/09/16 17:46:43.217605 peer.go:90: Connecting to "67.160.56.194:8333".
2015/09/16 17:46:43.296395 network.go:211: Error (Receive from "75.109.245.15:8333" failed: Error while seeking for next message: EOF.); closing connection.
2015/09/16 17:46:43.296626 peer.go:90: Connecting to "175.140.234.159:8333".
2015/09/16 17:46:43.393480 example.go:78: Received "version" message from "23.234.20.235:8333".
2015/09/16 17:46:43.467350 example.go:78: Received "version" message from "67.160.56.194:8333".
2015/09/16 17:46:43.895785 example.go:78: Received "version" message from "175.140.234.159:8333".
2015/09/16 17:46:45.067863 example.go:94: Received "inv" message of size 1800003 from "23.234.20.235:8333".
2015/09/16 17:46:45.472897 example.go:94: Received "inv" message of size 1800003 from "23.234.20.235:8333".
2015/09/16 17:46:45.686836 example.go:94: Received "inv" message of size 1202871 from "23.234.20.235:8333".
2015/09/16 17:46:46.440169 example.go:94: Received "inv" message of size 1769511 from "67.160.56.194:8333".
^C
interrupt
2015/09/16 17:46:56.804672 network.go:105: Closing connection to "23.234.20.235:8333".
2015/09/16 17:46:56.804735 network.go:105: Closing connection to "175.140.234.159:8333".
2015/09/16 17:46:56.804777 network.go:105: Closing connection to "67.160.56.194:8333".
exit status 1

todo

• Share addresses with other nodes in the network (ie. respond to getaddr messages)
• Smarter quality assesments of nodes, including some metric for the likelihood of the node being independent from others, and feedback from users of the library on the quality of the data a node provides (eg. does it delay new blocks or transactions, forward invalid ones or censor valid ones)
• tests
• add support for connecting to a test net (as opposed to the actual Bitcoin network).

Documentation

Index

• type Config
• type Dispatcher
  • func NewDispatcher(input <-chan Message) *Dispatcher
  • func (d *Dispatcher) Close()
  • func (d *Dispatcher) Run()
  • func (d *Dispatcher) Subscribe(key string, ch chan<- Message)
  • func (d *Dispatcher) Unsubscribe(key string)
• type Message
• type Network
  • func New(config Config) *Network
  • func (n *Network) Close()
  • func (n *Network) Connected() chan struct{}
  • func (n *Network) EndpointMisbehaving(name string, score int, desc string)
  • func (n *Network) EndpointsByQuality() []string
  • func (n *Network) SendChannel() chan<- Message
  • func (n *Network) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type PeerAddress
  • func (a PeerAddress) String() string
• type PeersByQuality
  • func (slice PeersByQuality) Len() int
  • func (slice PeersByQuality) Less(i, j int) bool
  • func (slice PeersByQuality) Swap(i, j int)

Types

type Config

type Config struct {
	// Number of peers the network should aim to connect to.
	DesiredConnections int
	// Path to file used to storing good peers for loading on next startup.
	PeerStorageFile string
	// List of hostnames that will be looked up in DNS to get IPs of peers.
	SeedHostnames []string
	// Channel to send all received messages that are not handled at the
	// connection or network layer. Will not be written to after Close()
	// returns.
	OutputChannel chan<- Message
}

Config passed when creating a new Network.

type Dispatcher

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

func NewDispatcher

func NewDispatcher(input <-chan Message) *Dispatcher

Create a new dispatcher that reads from input. Closing the input channel will shut down the dispatcher. It's still recommended to call Close() to block until it's safe to close subscribing channels.

func (*Dispatcher) Close

func (d *Dispatcher) Close()

Close the connection. Blocks until it's safe to close subscribing channels.

func (*Dispatcher) Run

func (d *Dispatcher) Run()

func (*Dispatcher) Subscribe

func (d *Dispatcher) Subscribe(key string, ch chan<- Message)

Subscribe adds a new subscriber for a type of message. Don't call on running dispatcher.

func (*Dispatcher) Unsubscribe

func (d *Dispatcher) Unsubscribe(key string)

Unsubscribe deletes an existing subscription. Only call on running dispatcher.

type Message

type Message struct {
	Endpoint string
	Type     string
	Data     []byte
}

Package of data going to or comming from a connected peer.

type Network

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

Network sets up a communication network with peers fed to it from DNS, loaded from its storage, and shared from existing peers. The aim is to get a robust network that will give the creator a good overview of the complete Bitcoin network, even if some of the peers are bad actors.

func New

func New(config Config) *Network

func (*Network) Close

func (n *Network) Close()

Close will shut down the whole network cleanly, with the caveat that it's unsafe to call any further methods on the network object while or after Close() has been called.

func (*Network) Connected

func (n *Network) Connected() chan struct{}

Connected returns a channel that closes once an initial connection has been established.

func (*Network) EndpointMisbehaving

func (n *Network) EndpointMisbehaving(name string, score int, desc string)

EndpointMisbehaving allows upper levels to report that a endpoint is misbehaving. This will lower the quality score of the associated peer, potentially disconnecting or banning it. Score should be in the range [1,100], where 1 is the least severe misbehaviour and 100 is the worst.

func (*Network) EndpointsByQuality

func (n *Network) EndpointsByQuality() []string

EndpointsByQuality returns a list of the currently connected endpoint sorted by quality, starting with the best. The quality score is determined by factors like responsiveness and honesty.

func (*Network) SendChannel

func (n *Network) SendChannel() chan<- Message

func (*Network) ServeHTTP

func (n *Network) ServeHTTP(w http.ResponseWriter, r *http.Request)

type PeerAddress

type PeerAddress struct {
	Address     string
	Reporter    string
	Services    uint64
	Time        time.Time
	FailureTime time.Time
}

func (PeerAddress) String

func (a PeerAddress) String() string

type PeersByQuality

type PeersByQuality []*peer

func (PeersByQuality) Len

func (slice PeersByQuality) Len() int

func (PeersByQuality) Less

func (slice PeersByQuality) Less(i, j int) bool

func (PeersByQuality) Swap

func (slice PeersByQuality) Swap(i, j int)