gateway

README

Gateway

A Gateway facilitates the interactions between the local node and remote nodes (peers). It relays incoming blocks and transactions to local modules, and broadcasts outgoing blocks and transactions to peers. In a broad sense, it is responsible for ensuring that the local consensus set is consistent with the "network" consensus set.

The gateway connects a ScPrime node to the ScPrime flood network. The flood network is used to propagate blocks and transactions. The gateway is the primary avenue that a node uses to hear about transactions and blocks, and is the primary avenue used to tell the network about blocks that you have mined or about transactions that you have created.

For the user to be securely connected to the network, the user must be connected to at least one node which will send them all of the blocks. An attacker can trick the user into thinking that a different blockchain is the full blockchain if the user is not connected to any nodes who are seeing + broadcasting the real chain (and instead is connected only to attacker nodes or to nodes that are not broadcasting). This situation is called an eclipse attack.

Connecting to a large number of nodes increases the resiliency of the network, but also puts a networking burden on the nodes and can slow down block propagation or increase orphan rates. The gateway's job is to keep the network efficient while also protecting the user against attacks.

The gateway keeps a list of nodes that it knows about. It uses this list to form connections with other nodes, and then uses those connections to participate in the flood network. The primary vector for an attacker to achieve an eclipse attack is node list domination. If a gateway's nodelist is heavily dominated by attacking nodes, then when the gateway chooses to make random connections the gateway is at risk of selecting only attacker nodes.

Some research has been done on Bitcoin's flood networks. The more relevant research has been listed below. The papers listed first are more relevant. Eclipse Attacks on Bitcoin's Peer-to-Peer Network (Heilman, Kendler, Zohar, Goldberg) Stubborn Mining: Generalizing Selfish Mining and Combining with an Eclipse Attack (Nayak, Kumar, Miller, Shi) An Overview of BGP Hijacking (https://www.bishopfox.com/blog/2015/08/an-overview-of-bgp-hijacking/)

Alerts

The gateway might register the following alerts:

• Gateway-Offline: Registered when the gateway is not connected to the public internet

TODO

• Fill in subsystems

Documentation

Overview

Package gateway connects a ScPrime node to the ScPrime flood network. The flood network is used to propagate blocks and transactions. The gateway is the primary avenue that a node uses to hear about transactions and blocks, and is the primary avenue used to tell the network about blocks that you have mined or about transactions that you have created.

Index

• Variables
• type Gateway
  • func New(addr string, bootstrap bool, persistDir string) (*Gateway, error)
  • func NewCustomGateway(addr string, bootstrap bool, persistDir string, deps modules.Dependencies) (*Gateway, error)
  • func (g *Gateway) AddToBlocklist(addresses []string) error
  • func (g *Gateway) Address() modules.NetAddress
  • func (g *Gateway) Alerts() (crit, err, warn []modules.Alert)
  • func (g *Gateway) BandwidthCounters() (uint64, uint64, time.Time, error)
  • func (g *Gateway) Blocklist() ([]string, error)
  • func (g *Gateway) Broadcast(name string, obj interface{}, peers []modules.Peer)
  • func (g *Gateway) Close() error
  • func (g *Gateway) Connect(addr modules.NetAddress) error
  • func (g *Gateway) ConnectManual(addr modules.NetAddress) error
  • func (g *Gateway) Disconnect(addr modules.NetAddress) error
  • func (g *Gateway) DisconnectManual(addr modules.NetAddress) error
  • func (g *Gateway) DiscoverAddress(cancel <-chan struct{}) (net.IP, error)
  • func (g *Gateway) ForwardPort(port string) error
  • func (g *Gateway) Online() (online bool)
  • func (g *Gateway) Peers() []modules.Peer
  • func (g *Gateway) RPC(addr modules.NetAddress, name string, fn modules.RPCFunc) error
  • func (g *Gateway) RateLimits() (int64, int64)
  • func (g *Gateway) RegisterConnectCall(name string, fn modules.RPCFunc)
  • func (g *Gateway) RegisterRPC(name string, fn modules.RPCFunc)
  • func (g *Gateway) RemoveFromBlocklist(addresses []string) error
  • func (g *Gateway) SetBlocklist(addresses []string) error
  • func (g *Gateway) SetRateLimits(downloadSpeed, uploadSpeed int64) error
  • func (g *Gateway) UnregisterConnectCall(name string)
  • func (g *Gateway) UnregisterRPC(name string)

Variables

var (
	// AlertMSGGatewayOffline indicates that the last time the gateway checked
	// the network status it was offline.
	AlertMSGGatewayOffline = "not connected to the internet"
)

Constants related to the gateway's alerts.

Types

type Gateway

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

Gateway implements the modules.Gateway interface.

func New

func New(addr string, bootstrap bool, persistDir string) (*Gateway, error)

New returns an initialized Gateway.

func NewCustomGateway

func NewCustomGateway(addr string, bootstrap bool, persistDir string, deps modules.Dependencies) (*Gateway, error)

NewCustomGateway returns an initialized Gateway with custom dependencies.

func (*Gateway) AddToBlocklist

func (g *Gateway) AddToBlocklist(addresses []string) error

AddToBlocklist adds addresses to the Gateway's blocklist

func (*Gateway) Address

func (g *Gateway) Address() modules.NetAddress

Address returns the NetAddress of the Gateway.

func (*Gateway) Alerts

func (g *Gateway) Alerts() (crit, err, warn []modules.Alert)

Alerts implements the modules.Alerter interface for the gateway.

func (*Gateway) BandwidthCounters

func (g *Gateway) BandwidthCounters() (uint64, uint64, time.Time, error)

BandwidthCounters returns the Gateway's upload and download bandwidth

func (*Gateway) Blocklist

func (g *Gateway) Blocklist() ([]string, error)

Blocklist returns the Gateway's blocklist

func (*Gateway) Broadcast

func (g *Gateway) Broadcast(name string, obj interface{}, peers []modules.Peer)

Broadcast calls an RPC on all of the specified peers. The calls are run in parallel. Broadcasts are restricted to "one-way" RPCs, which simply write an object and disconnect. This is why Broadcast takes an interface{} instead of an RPCFunc.

func (*Gateway) Close

func (g *Gateway) Close() error

Close saves the state of the Gateway and stops its listener process.

func (*Gateway) Connect

func (g *Gateway) Connect(addr modules.NetAddress) error

Connect establishes a persistent connection to a peer, and adds it to the Gateway's peer list.

func (*Gateway) ConnectManual

func (g *Gateway) ConnectManual(addr modules.NetAddress) error

ConnectManual is a wrapper for the Connect function. It is specifically used if a user wants to connect to a node manually. This also removes the node from the blocklist.

func (*Gateway) Disconnect

func (g *Gateway) Disconnect(addr modules.NetAddress) error

Disconnect terminates a connection to a peer and removes it from the Gateway's peer list.

func (*Gateway) DisconnectManual

func (g *Gateway) DisconnectManual(addr modules.NetAddress) error

DisconnectManual is a wrapper for the Disconnect function. It is specifically used if a user wants to connect to a node manually. This also adds the node to the blocklist.

func (*Gateway) DiscoverAddress

func (g *Gateway) DiscoverAddress(cancel <-chan struct{}) (net.IP, error)

DiscoverAddress discovers and returns the current public IP address of the gateway. Contrary to Address, DiscoverAddress is blocking and might take multiple minutes to return. A channel to cancel the discovery can be supplied optionally. If nil is supplied, a reasonable timeout will be used by default.

func (*Gateway) ForwardPort

func (g *Gateway) ForwardPort(port string) error

ForwardPort adds a port mapping to the router.

func (*Gateway) Online

func (g *Gateway) Online() (online bool)

Online returns true if the node is connected to the internet. During testing we always assume that the node is online

func (*Gateway) Peers

func (g *Gateway) Peers() []modules.Peer

Peers returns the addresses currently connected to the Gateway.

func (*Gateway) RPC

func (g *Gateway) RPC(addr modules.NetAddress, name string, fn modules.RPCFunc) error

RPC calls an RPC on the given address. RPC cannot be called on an address that the Gateway is not connected to.

func (*Gateway) RateLimits

func (g *Gateway) RateLimits() (int64, int64)

RateLimits returns the currently set bandwidth limits of the gateway.

func (*Gateway) RegisterConnectCall

func (g *Gateway) RegisterConnectCall(name string, fn modules.RPCFunc)

RegisterConnectCall registers a name and RPCFunc to be called on a peer upon connecting.

func (*Gateway) RegisterRPC

func (g *Gateway) RegisterRPC(name string, fn modules.RPCFunc)

RegisterRPC registers an RPCFunc as a handler for a given identifier. To call an RPC, use gateway.RPC, supplying the same identifier given to RegisterRPC. Identifiers should always use PascalCase. The first 8 characters of an identifier should be unique, as the identifier used internally is truncated to 8 bytes.

func (*Gateway) RemoveFromBlocklist

func (g *Gateway) RemoveFromBlocklist(addresses []string) error

RemoveFromBlocklist removes addresses from the Gateway's blocklist

func (*Gateway) SetBlocklist

func (g *Gateway) SetBlocklist(addresses []string) error

SetBlocklist sets the blocklist of the gateway

func (*Gateway) SetRateLimits

func (g *Gateway) SetRateLimits(downloadSpeed, uploadSpeed int64) error

SetRateLimits changes the rate limits for the peer-connections of the gateway.

func (*Gateway) UnregisterConnectCall

func (g *Gateway) UnregisterConnectCall(name string)

UnregisterConnectCall unregisters an on-connect call and removes the corresponding RPCFunc from g.initRPCs. Future connections to peers will not trigger the RPC to be called on them.

func (*Gateway) UnregisterRPC

func (g *Gateway) UnregisterRPC(name string)

UnregisterRPC unregisters an RPC and removes the corresponding RPCFunc from g.handlers. Future calls to the RPC by peers will fail.