Documentation
¶
Index ¶
- Constants
- Variables
- func Encode(msg Encodable) []byte
- func RandomUint64() (uint64, error)
- func ReadElement(r io.Reader, element interface{}) error
- func ReadElements(r io.Reader, elements ...interface{}) error
- func WriteElement(w io.Writer, element interface{}) error
- func WriteElements(w io.Writer, elements ...interface{}) error
- func WriteMessage(w io.Writer, msg Message, bmnet BitmessageNet) error
- func WriteMessageN(w io.Writer, msg Message, bmnet BitmessageNet) (int, error)
- type BitmessageNet
- type Encodable
- type InvVect
- type Message
- type MessageError
- type MsgAddr
- func (msg *MsgAddr) AddAddress(na *NetAddress) error
- func (msg *MsgAddr) AddAddresses(netAddrs ...*NetAddress) error
- func (msg *MsgAddr) ClearAddresses()
- func (msg *MsgAddr) Command() string
- func (msg *MsgAddr) Decode(r io.Reader) error
- func (msg *MsgAddr) Encode(w io.Writer) error
- func (msg *MsgAddr) MaxPayloadLength() int
- type MsgGetData
- type MsgInv
- type MsgObject
- func (msg *MsgObject) CheckPow(data pow.Data, refTime time.Time) bool
- func (msg *MsgObject) Command() string
- func (msg *MsgObject) Copy() *MsgObject
- func (msg *MsgObject) Decode(r io.Reader) error
- func (msg *MsgObject) Encode(w io.Writer) error
- func (msg *MsgObject) Header() *ObjectHeader
- func (msg *MsgObject) MaxPayloadLength() int
- func (msg *MsgObject) Payload() []byte
- func (msg *MsgObject) String() string
- type MsgPong
- type MsgVerAck
- type MsgVersion
- func (msg *MsgVersion) AddService(service ServiceFlag)
- func (msg *MsgVersion) AddUserAgent(name string, version string, comments ...string) error
- func (msg *MsgVersion) Command() string
- func (msg *MsgVersion) Decode(r io.Reader) error
- func (msg *MsgVersion) Encode(w io.Writer) error
- func (msg *MsgVersion) HasService(service ServiceFlag) bool
- func (msg *MsgVersion) MaxPayloadLength() int
- type NetAddress
- type ObjectHeader
- type ObjectType
- type PubKey
- type ServiceFlag
Constants ¶
const ( CmdVersion = "version" CmdVerAck = "verack" CmdAddr = "addr" CmdInv = "inv" CmdGetData = "getdata" CmdObject = "object" CmdPong = "pong" )
Commands used in bitmessage message headers which describe the type of message.
const CommandSize = 12
CommandSize is the fixed size of all commands in the common bitmessage message header. Shorter commands must be zero padded.
const DefaultUserAgent = "/wire:0.1.0/"
DefaultUserAgent for wire
const MaxAddrPerMsg = 1000
MaxAddrPerMsg is the maximum number of addresses that can be in a single bitmessage addr message (MsgAddr).
const ( // MaxInvPerMsg is the maximum number of inventory vectors that can be in a // single bitmessage inv message. MaxInvPerMsg = 50000 )
const MaxMessagePayload = 1600100
MaxMessagePayload is the maximum bytes a message can be regardless of other individual limits imposed by messages themselves. ~1.6 MB, which is which is the maximum possible size of an inv message.
const ( // MaxPayloadOfMsgObject is the the maximum payload of object message = 2^18 bytes. // (not to be confused with the object payload) MaxPayloadOfMsgObject = 262144 )
const MaxPubKeyStringSize = PubKeySize * 2
MaxPubKeyStringSize is the maximum length of a PubKey string.
const MaxStreams = 1
MaxStreams is the maximum number of allowed streams to request according to the bitmessage protocol. Keeping it at 1 for now.
const MaxUserAgentLen = 5000
MaxUserAgentLen is the maximum allowed length for the user agent field in a version message (MsgVersion).
const MessageHeaderSize = 24
MessageHeaderSize is the number of bytes in a bitmessage message header. Bitmessage network (magic) 4 bytes + command 12 bytes + payload length 4 bytes + checksum 4 bytes.
const ( // ProtocolVersion is the latest protocol version this package supports. ProtocolVersion uint32 = 3 )
const PubKeySize = 64
PubKeySize is the size of array used to store uncompressed public keys. Note that the first byte (0x04) is excluded when storing them.
Variables ¶
var ErrInvalidNetAddr = errors.New("provided net.Addr is not a net.TCPAddr")
ErrInvalidNetAddr describes an error that indicates the caller didn't specify a TCP address as required.
var ErrPubKeyStrSize = fmt.Errorf("string length must be %v chars", MaxPubKeyStringSize)
ErrPubKeyStrSize describes an error that indicates the caller specified a PubKey string that does not have the right number of characters.
Functions ¶
func Encode ¶
Encode takes a message and returns a representation of it as a byte array as the message would appear in the database. This array is missing the the standard bitmessage header that goes along with every message sent over the p2p connection.
func RandomUint64 ¶
RandomUint64 returns a cryptographically random uint64 value.
func ReadElement ¶
ReadElement reads the next sequence of bytes from r using big endian depending on the concrete type of element pointed to.
func ReadElements ¶
ReadElements reads multiple items from r. It is equivalent to multiple calls to readElement.
func WriteElement ¶
WriteElement writes the big endian representation of element to w.
func WriteElements ¶
WriteElements writes multiple items to w. It is equivalent to multiple calls to writeElement.
func WriteMessage ¶
func WriteMessage(w io.Writer, msg Message, bmnet BitmessageNet) error
WriteMessage writes a bitmessage Message to w including the necessary header information. This function is the same as WriteMessageN except it doesn't doesn't return the number of bytes written. This function is mainly provided for backwards compatibility with the original API, but it's also useful for callers that don't care about byte counts.
func WriteMessageN ¶
WriteMessageN writes a bitmessage Message to w including the necessary header information and returns the number of bytes written. This function is the same as WriteMessage except it also returns the number of bytes written.
Types ¶
type BitmessageNet ¶
type BitmessageNet uint32
BitmessageNet represents which bitmessage network a message belongs to.
const ( // MainNet represents the main bitmessage network. MainNet BitmessageNet = 0xe9beb4d9 )
Constants used to indicate the message bitmessage network. They can also be used to seek to the next message when a stream's state is unknown, but this package does not provide that functionality since it's generally a better idea to simply disconnect clients that are misbehaving over TCP.
func (BitmessageNet) String ¶
func (n BitmessageNet) String() string
String returns the BitmessageNet in human-readable form.
type InvVect ¶
InvVect defines a bitmessage inventory vector which is used to describe data, as specified by the Type field, that a peer wants, has, or does not have to another peer.
type Message ¶
Message is an interface that describes a bitmessage message. A type that implements Message has complete control over the representation of its data and may therefore contain additional or fewer fields than those which are used directly in the protocol encoded message.
func ReadMessage ¶
ReadMessage reads, validates, and parses the next bitmessage Message from r for bitmessage network. It returns the parsed Message and raw bytes which comprise the message. This function only differs from ReadMessageN in that it doesn't return the number of bytes read. This function is useful for callers that don't care about byte counts.
func ReadMessageN ¶
ReadMessageN reads, validates, and parses the next bitmessage Message from r for the provided protocol version and bitmessage network. It returns the number of bytes read in addition to the parsed Message and raw bytes which comprise the message. This function is the same as ReadMessage except it also returns the number of bytes read.
type MessageError ¶
type MessageError struct { Func string // Function name Description string // Human readable description of the issue }
MessageError describes an issue with a message. An example of some potential issues are messages from the wrong bitmessage network, invalid commands, mismatched checksums, and exceeding max payloads.
This provides a mechanism for the caller to type assert the error to differentiate between general io errors such as io.EOF and issues that resulted from malformed messages.
func NewMessageError ¶
func NewMessageError(f string, desc string) *MessageError
NewMessageError creates an error for the given function and description.
func (*MessageError) Error ¶
func (e *MessageError) Error() string
Error satisfies the error interface and prints human-readable errors.
type MsgAddr ¶
type MsgAddr struct {
AddrList []*NetAddress
}
MsgAddr implements the Message interface and represents a bitmessage addr message. It is used to provide a list of known active peers on the network. An active peer is considered one that has transmitted a message within the last 3 hours. Nodes which have not transmitted in that time frame should be forgotten. Each message is limited to a maximum number of addresses, which is currently 1000. As a result, multiple messages must be used to relay the full list.
Use the AddAddress function to build up the list of known addresses when sending an addr message to another peer.
func NewMsgAddr ¶
func NewMsgAddr() *MsgAddr
NewMsgAddr returns a new bitmessage addr message that conforms to the Message interface. See MsgAddr for details.
func (*MsgAddr) AddAddress ¶
func (msg *MsgAddr) AddAddress(na *NetAddress) error
AddAddress adds a known active peer to the message.
func (*MsgAddr) AddAddresses ¶
func (msg *MsgAddr) AddAddresses(netAddrs ...*NetAddress) error
AddAddresses adds multiple known active peers to the message.
func (*MsgAddr) ClearAddresses ¶
func (msg *MsgAddr) ClearAddresses()
ClearAddresses removes all addresses from the message.
func (*MsgAddr) Command ¶
Command returns the protocol command string for the message. This is part of the Message interface implementation.
func (*MsgAddr) Decode ¶
Decode decodes r using the bitmessage protocol encoding into the receiver. This is part of the Message interface implementation.
func (*MsgAddr) Encode ¶
Encode encodes the receiver to w using the bitmessage protocol encoding. This is part of the Message interface implementation.
func (*MsgAddr) MaxPayloadLength ¶
MaxPayloadLength returns the maximum length the payload can be for the receiver. This is part of the Message interface implementation.
type MsgGetData ¶
type MsgGetData struct {
InvList []*InvVect
}
MsgGetData implements the Message interface and represents a bitmessage getdata message. It is used to request data such as messages and broadcasts from another peer. It should be used in response to the inv (MsgInv) message to request the actual data referenced by each inventory vector the receiving peer doesn't already have. Each message is limited to a maximum number of inventory vectors, which is currently 50,000. As a result, multiple messages must be used to request larger amounts of data.
Use the AddInvVect function to build up the list of inventory vectors when sending a getdata message to another peer.
func NewMsgGetData ¶
func NewMsgGetData() *MsgGetData
NewMsgGetData returns a new bitmessage getdata message that conforms to the Message interface. See MsgGetData for details.
func NewMsgGetDataSizeHint ¶
func NewMsgGetDataSizeHint(sizeHint uint) *MsgGetData
NewMsgGetDataSizeHint returns a new bitmessage getdata message that conforms to the Message interface. See MsgGetData for details. This function differs from NewMsgGetData in that it allows a default allocation size for the backing array which houses the inventory vector list. This allows callers who know in advance how large the inventory list will grow to avoid the overhead of growing the internal backing array several times when appending large amounts of inventory vectors with AddInvVect. Note that the specified hint is just that - a hint that is used for the default allocation size. Adding more (or less) inventory vectors will still work properly. The size hint is limited to MaxInvPerMsg.
func (*MsgGetData) AddInvVect ¶
func (msg *MsgGetData) AddInvVect(iv *InvVect) error
AddInvVect adds an inventory vector to the message.
func (*MsgGetData) Command ¶
func (msg *MsgGetData) Command() string
Command returns the protocol command string for the message. This is part of the Message interface implementation.
func (*MsgGetData) Decode ¶
func (msg *MsgGetData) Decode(r io.Reader) error
Decode decodes r using the bitmessage protocol encoding into the receiver. This is part of the Message interface implementation.
func (*MsgGetData) Encode ¶
func (msg *MsgGetData) Encode(w io.Writer) error
Encode encodes the receiver to w using the bitmessage protocol encoding. This is part of the Message interface implementation.
func (*MsgGetData) MaxPayloadLength ¶
func (msg *MsgGetData) MaxPayloadLength() int
MaxPayloadLength returns the maximum length the payload can be for the receiver. This is part of the Message interface implementation.
type MsgInv ¶
type MsgInv struct {
InvList []*InvVect
}
MsgInv implements the Message interface and represents a bitmessage inv message. It is used to advertise a peer's known data such as messages and broadcasts through inventory vectors. Each message is limited to a maximum number of inventory vectors, which is currently 50,000.
Use the AddInvVect function to build up the list of inventory vectors when sending an inv message to another peer.
func NewMsgInv ¶
func NewMsgInv() *MsgInv
NewMsgInv returns a new bitmessage inv message that conforms to the Message interface. See MsgInv for details.
func NewMsgInvSizeHint ¶
NewMsgInvSizeHint returns a new bitmessage inv message that conforms to the Message interface. See MsgInv for details. This function differs from NewMsgInv in that it allows a default allocation size for the backing array which houses the inventory vector list. This allows callers who know in advance how large the inventory list will grow to avoid the overhead of growing the internal backing array several times when appending large amounts of inventory vectors with AddInvVect. Note that the specified hint is just that - a hint that is used for the default allocation size. Adding more (or less) inventory vectors will still work properly. The size hint is limited to MaxInvPerMsg.
func (*MsgInv) AddInvVect ¶
AddInvVect adds an inventory vector to the message.
func (*MsgInv) Command ¶
Command returns the protocol command string for the message. This is part of the Message interface implementation.
func (*MsgInv) Decode ¶
Decode decodes r using the bitmessage protocol encoding into the receiver. This is part of the Message interface implementation.
func (*MsgInv) Encode ¶
Encode encodes the receiver to w using the bitmessage protocol encoding. This is part of the Message interface implementation.
func (*MsgInv) MaxPayloadLength ¶
MaxPayloadLength returns the maximum length the payload can be for the receiver. This is part of the Message interface implementation.
type MsgObject ¶
type MsgObject struct {
// contains filtered or unexported fields
}
MsgObject implements the Message interface and represents a generic object.
func DecodeMsgObject ¶
DecodeMsgObject takes a byte array and turns it into an object message.
func NewMsgObject ¶
func NewMsgObject(header *ObjectHeader, payload []byte) *MsgObject
NewMsgObject returns a new object message that conforms to the Message interface using the passed parameters and defaults for the remaining fields.
func (*MsgObject) CheckPow ¶
CheckPow checks if the POW that was done for an object message is sufficient. obj is a byte slice containing the object message.
func (*MsgObject) Command ¶
Command returns the protocol command string for the message. This is part of the Message interface implementation.
func (*MsgObject) Decode ¶
Decode decodes r using the bitmessage protocol encoding into the receiver. This is part of the Message interface implementation.
func (*MsgObject) Encode ¶
Encode encodes the receiver to w using the bitmessage protocol encoding. This is part of the Message interface implementation.
func (*MsgObject) Header ¶
func (msg *MsgObject) Header() *ObjectHeader
Header returns the object header.
func (*MsgObject) MaxPayloadLength ¶
MaxPayloadLength returns the maximum length the payload can be for the receiver. This is part of the Message interface implementation.
type MsgPong ¶
type MsgPong struct{}
MsgPong defines a bitmessage pong message which is used by a peer to ensure that the connection between itself and another peer doesn't time out due to inactivity. It implements the Message interface.
This message has no payload.
func NewMsgPong ¶
func NewMsgPong() *MsgPong
NewMsgPong returns a new bitmessage verack message that conforms to the Message interface.
func (*MsgPong) Command ¶
Command returns the protocol command string for the message. This is part of the Message interface implementation.
func (*MsgPong) Decode ¶
Decode decodes r using the bitmessage protocol encoding into the receiver. This is part of the Message interface implementation.
func (*MsgPong) Encode ¶
Encode encodes the receiver to w using the bitmessage protocol encoding. This is part of the Message interface implementation.
func (*MsgPong) MaxPayloadLength ¶
MaxPayloadLength returns the maximum length the payload can be for the receiver. This is part of the Message interface implementation.
type MsgVerAck ¶
type MsgVerAck struct{}
MsgVerAck defines a bitmessage verack message which is used for a peer to acknowledge a version message (MsgVersion) after it has used the information to negotiate parameters. It implements the Message interface.
This message has no payload.
func NewMsgVerAck ¶
func NewMsgVerAck() *MsgVerAck
NewMsgVerAck returns a new bitmessage verack message that conforms to the Message interface.
func (*MsgVerAck) Command ¶
Command returns the protocol command string for the message. This is part of the Message interface implementation.
func (*MsgVerAck) Decode ¶
Decode decodes r using the bitmessage protocol encoding into the receiver. This is part of the Message interface implementation.
func (*MsgVerAck) Encode ¶
Encode encodes the receiver to w using the bitmessage protocol encoding. This is part of the Message interface implementation.
func (*MsgVerAck) MaxPayloadLength ¶
MaxPayloadLength returns the maximum length the payload can be for the receiver. This is part of the Message interface implementation.
type MsgVersion ¶
type MsgVersion struct { // Version of the protocol the node is using. ProtocolVersion int32 // Bitfield which identifies the enabled services. Services ServiceFlag // Time the message was generated. This is encoded as an int64 on the wire. Timestamp time.Time // Address of the remote peer. AddrYou *NetAddress // Address of the local peer. AddrMe *NetAddress // Unique value associated with message that is used to detect self // connections. Nonce uint64 // The user agent that generated messsage. This is a encoded as a varString // on the wire. This has a max length of MaxUserAgentLen. UserAgent string // The stream numbers of interest. StreamNumbers []uint32 }
MsgVersion implements the Message interface and represents a bitmessage version message. It is used for a peer to advertise itself as soon as an outbound connection is made. The remote peer then uses this information along with its own to negotiate. The remote peer must then respond with a version message of its own containing the negotiated values followed by a verack message (MsgVerAck). This exchange must take place before any further communication is allowed to proceed.
func NewMsgVersion ¶
func NewMsgVersion(me *NetAddress, you *NetAddress, nonce uint64, streams []uint32) *MsgVersion
NewMsgVersion returns a new bitmessage version message that conforms to the Message interface using the passed parameters and defaults for the remaining fields.
func NewMsgVersionFromConn ¶
func NewMsgVersionFromConn(conn net.Conn, nonce uint64, currentStream uint32, allStreams []uint32) (*MsgVersion, error)
NewMsgVersionFromConn is a convenience function that extracts the remote and local address from conn and returns a new bitmessage version message that conforms to the Message interface. See NewMsgVersion.
func (*MsgVersion) AddService ¶
func (msg *MsgVersion) AddService(service ServiceFlag)
AddService adds service as a supported service by the peer generating the message.
func (*MsgVersion) AddUserAgent ¶
func (msg *MsgVersion) AddUserAgent(name string, version string, comments ...string) error
AddUserAgent adds a user agent to the user agent string for the version message. The version string is not defined to any strict format, although it is recommended to use the form "major.minor.revision" e.g. "2.6.41".
func (*MsgVersion) Command ¶
func (msg *MsgVersion) Command() string
Command returns the protocol command string for the message. This is part of the Message interface implementation.
func (*MsgVersion) Decode ¶
func (msg *MsgVersion) Decode(r io.Reader) error
Decode decodes r using the bitmessage protocol encoding into the receiver. This is part of the Message interface implementation.
func (*MsgVersion) Encode ¶
func (msg *MsgVersion) Encode(w io.Writer) error
Encode encodes the receiver to w using the bitmessage protocol encoding. This is part of the Message interface implementation.
func (*MsgVersion) HasService ¶
func (msg *MsgVersion) HasService(service ServiceFlag) bool
HasService returns whether the specified service is supported by the peer that generated the message.
func (*MsgVersion) MaxPayloadLength ¶
func (msg *MsgVersion) MaxPayloadLength() int
MaxPayloadLength returns the maximum length the payload can be for the receiver. This is part of the Message interface implementation.
type NetAddress ¶
type NetAddress struct { // Last time the address was seen. Timestamp time.Time // Stream that the address is a member of. Stream uint32 // Bitfield which identifies the services supported by the address. Services ServiceFlag // IP address of the peer. IP net.IP // Port the peer is using. This is encoded in big endian on the wire // which differs from most everything else. Port uint16 }
NetAddress defines information about a peer on the network including the time it was last seen, the services it supports, its IP address, and port.
func NewNetAddress ¶
func NewNetAddress(addr net.Addr, stream uint32, services ServiceFlag) (*NetAddress, error)
NewNetAddress returns a new NetAddress using the provided TCP address and supported services with defaults for the remaining fields.
Note that addr must be a net.TCPAddr. An ErrInvalidNetAddr is returned if it is not.
func NewNetAddressIPPort ¶
func NewNetAddressIPPort(ip net.IP, port uint16, stream uint32, services ServiceFlag) *NetAddress
NewNetAddressIPPort returns a new NetAddress using the provided IP, port, stream and supported services with Timestamp being time.Now().
func (*NetAddress) AddService ¶
func (na *NetAddress) AddService(service ServiceFlag)
AddService adds service as a supported service by the peer generating the message.
func (*NetAddress) HasService ¶
func (na *NetAddress) HasService(service ServiceFlag) bool
HasService returns whether the specified service is supported by the address.
func (*NetAddress) SetAddress ¶
func (na *NetAddress) SetAddress(ip net.IP, port uint16)
SetAddress is a convenience function to set the IP address and port in one call.
type ObjectHeader ¶
type ObjectHeader struct { Nonce pow.Nonce ObjectType ObjectType Version uint64 StreamNumber uint64 // contains filtered or unexported fields }
ObjectHeader is a representation of the header of the object message as defined in the Bitmessage protocol.
func DecodeObjectHeader ¶
func DecodeObjectHeader(r io.Reader) (*ObjectHeader, error)
DecodeObjectHeader decodes the object header from given reader. Object header consists of Nonce, ExpiresTime, ObjectType, Version and Stream, in that order. Read Protocol Specifications for more information.
func NewObjectHeader ¶
func NewObjectHeader( Nonce pow.Nonce, Expiration time.Time, ObjectType ObjectType, Version uint64, StreamNumber uint64) *ObjectHeader
NewObjectHeader creates an ObjectHeader from the given parameters.
func (*ObjectHeader) Encode ¶
func (h *ObjectHeader) Encode(w io.Writer) error
Encode encodes the object header to the given writer. Object header consists of Nonce, ExpiresTime, ObjectType, Version and Stream, in that order. Read Protocol Specifications for more information.
func (*ObjectHeader) EncodeForSigning ¶
func (h *ObjectHeader) EncodeForSigning(w io.Writer) error
EncodeForSigning encodes the object header used for signing. It consists of everything in the normal object header except for nonce.
func (*ObjectHeader) Expiration ¶
func (h *ObjectHeader) Expiration() time.Time
Expiration provides the expration time.
func (*ObjectHeader) String ¶
func (h *ObjectHeader) String() string
String returns the header in a human-readible string form.
type ObjectType ¶
type ObjectType uint32
ObjectType represents the type of object than an object message contains. Objects in bitmessage are things on the network that get propagated. This can include requests/responses for pubkeys, messages and broadcasts.
const ( ObjectTypeGetPubKey ObjectType = 0 ObjectTypePubKey ObjectType = 1 ObjectTypeMsg ObjectType = 2 ObjectTypeBroadcast ObjectType = 3 HighestKnownObjectType ObjectType = ObjectTypeBroadcast )
There are five types of objects in bitmessage.
- GetPubKey: requests for public keys.
- PubKey: public keys sent in response.
- Msg: bitmessage messages.
- Broadcast: broadcast messages.
An ObjectType can also take on other values representing unknown message types.
func (ObjectType) String ¶
func (t ObjectType) String() string
type PubKey ¶
type PubKey [PubKeySize]byte
PubKey is used in several of the bitmessage messages and common structures. The first 32 bytes contain the X value and the other 32 contain the Y value.
func NewPubKey ¶
NewPubKey returns a new PubKey from a byte slice. An error is returned if the number of bytes passed in is not PubKeySize.
func NewPubKeyFromStr ¶
NewPubKeyFromStr creates a PubKey from a hash string. The string should be the hexadecimal string of the PubKey.
type ServiceFlag ¶
type ServiceFlag uint64
ServiceFlag identifies services supported by a bitmessage peer.
const ( // SFNodeNetwork is a flag used to indicate a peer is a full node. SFNodeNetwork ServiceFlag = 1 << iota )
func (ServiceFlag) String ¶
func (f ServiceFlag) String() string
String returns the ServiceFlag in human-readable form.