ouroboros

package module
v0.31.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 9, 2023 License: Apache-2.0 Imports: 15 Imported by: 0

README

go-ouroboros-network

A Go client implementation of the Cardano Ouroboros network protocol

This is loosely based on the official Haskell implementation

NOTE: this library is under heavily development, and the interface should not be considered stable until it reaches v1.0.0

Implementation status

The Ouroboros protocol consists of a simple multiplexer protocol and various mini-protocols that run on top of it. This makes it easy to implement only parts of the protocol without negatively affecting usability of this library.

The multiplexer and handshake mini-protocol are "fully" working. The focus will be on the node-to-client (local) protocols, but the node-to-node protocols will also be implemented in time.

Mini-protocols
Name Status
Handshake Implemented
ChainSync Implemented
BlockFetch Implemented
TxSubmission2 Not Implemented
LocalTxSubmission Implemented
LocalStateQuery Partly Implemented
KeepAlive Implemented
LocalTxMonitor Not Implemented

Testing

Testing is currently a mostly manual process. There's an included test program that use the library and a Docker Compose file to launch a local cardano-node instance.

Starting the local cardano-node instance
$ docker-compose up -d

If you want to use mainnet, set the CARDANO_NETWORK environment variable.

$ export CARDANO_NETWORK=mainnet
$ docker-compose up -d

You can communicate with the cardano-node instance on port 8081 (for "public" node-to-node protocol), port 8082 (for "private" node-to-client protocol), or the ./tmp/cardano-node/ipc/node.socket UNIX socket file (also for "private" node-to-client protocol).

NOTE: if using the UNIX socket file, you may need to adjust the permissions/ownership to allow your user to access it. The cardano-node Docker image runs as root by default and the UNIX socket ends up with root:root ownership and 0755 permissions, which doesn't allow a non-root use to write to it by default.

Running cardano-cli against local cardano-node instance
$ docker exec -ti go-ouroboros-network_cardano-node_1 sh -c 'CARDANO_NODE_SOCKET_PATH=/ipc/node.socket cardano-cli query tip --testnet-magic 1097911063'
Building and running the test program

Compile the test program.

$ make

Run the test program pointing to the UNIX socket (via socat) from the cardano-node instance started above.

$ ./go-ouroboros-network -address localhost:8082 -network testnet ...

Run it against the public port in node-to-node mode.

$ ./go-ouroboros-network -address localhost:8081 -ntn -network testnet ...

Test chain-sync (works in node-to-node and node-to-client modes).

$ ./go-ouroboros-network ... chain-sync -start-era byron

Test local-tx-submission (only works in node-to-client mode).

$ ./go-ouroboros-network ... local-tx-submission ...

Test following the chain tip in the preview network.

$ ./go-ouroboros-network -network preview -address preview-node.world.dev.cardano.org:30002 -ntn chain-sync -tip
Stopping the local cardano-node instance
$ docker-compose down --volumes

Documentation

Overview

Package ouroboros implements support for interacting with Cardano nodes using the Ouroboros network protocol.

The Ouroboros network protocol consists of a muxer and multiple mini-protocols that provide various functions. A handshake and protocol versioning are used to ensure peer compatibility.

This package is the main entry point into this library. The other packages can be used outside of this one, but it's not a primary design goal.

Index

Constants

This section is empty.

Variables

View Source 
var (
	NetworkTestnet = Network{Id: 0, Name: "testnet", NetworkMagic: 1097911063}
	NetworkMainnet = Network{Id: 1, Name: "mainnet", NetworkMagic: 764824073}
	NetworkPreprod = Network{Id: 2, Name: "preprod", NetworkMagic: 1}
	NetworkPreview = Network{Id: 3, Name: "preview", NetworkMagic: 2}

	NetworkInvalid = Network{Id: 0, Name: "invalid", NetworkMagic: 0} // NetworkInvalid is used as a return value for lookup functions when a network isn't found
)

Network definitions

Functions

This section is empty.

Types

type Network added in v0.29.0 

type Network struct {
	Id           uint
	Name         string
	NetworkMagic uint32
}

Network represents a Cardano network

func NetworkById added in v0.29.0 

func NetworkById(id uint) Network

NetworkById returns a predefined network by ID

func NetworkByName added in v0.29.0 

func NetworkByName(name string) Network

NetworkByName returns a predefined network by name

func NetworkByNetworkMagic added in v0.29.0 

func NetworkByNetworkMagic(networkMagic uint32) Network

NetworkByNetworkMagic returns a predefined network by network magic

func (Network) String added in v0.29.0 

func (n Network) String() string

type Ouroboros 

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

The Ouroboros type is a wrapper around a net.Conn object that handles communication using the Ouroboros network protocol over that connection

func New 

func New(options ...OuroborosOptionFunc) (*Ouroboros, error)

New returns a new Ouroboros object with the specified options. If a connection is provided, the handshake will be started. An error will be returned if the handshake fails

func (*Ouroboros) BlockFetch added in v0.4.0 

func (o *Ouroboros) BlockFetch() *blockfetch.BlockFetch

BlockFetch returns the block-fetch protocol handler

func (*Ouroboros) ChainSync added in v0.3.0 

func (o *Ouroboros) ChainSync() *chainsync.ChainSync

ChainSync returns the chain-sync protocol handler

func (*Ouroboros) Close added in v0.13.1 

func (o *Ouroboros) Close() error

Close will shutdown the Ouroboros connection

func (*Ouroboros) Dial 

func (o *Ouroboros) Dial(proto string, address string) error

Dial will establish a connection using the specified protocol and address. These parameters are passed to the net.Dial func. The handshake will be started when a connection is established. An error will be returned if the connection fails, a connection was already established, or the handshake fails

func (*Ouroboros) ErrorChan 

func (o *Ouroboros) ErrorChan() chan error

ErrorChan returns the channel for asynchronous errors

func (*Ouroboros) KeepAlive added in v0.7.0 

func (o *Ouroboros) KeepAlive() *keepalive.KeepAlive

KeepAlive returns the keep-alive protocol handler

func (*Ouroboros) LocalStateQuery added in v0.11.0 

func (o *Ouroboros) LocalStateQuery() *localstatequery.LocalStateQuery

LocalStateQuery returns the local-state-query protocol handler

func (*Ouroboros) LocalTxMonitor added in v0.28.0 

func (o *Ouroboros) LocalTxMonitor() *localtxmonitor.LocalTxMonitor

LocalTxMonitor returns the local-tx-monitor protocol handler

func (*Ouroboros) LocalTxSubmission added in v0.8.0 

func (o *Ouroboros) LocalTxSubmission() *localtxsubmission.LocalTxSubmission

LocalTxSubmission returns the local-tx-submission protocol handler

func (*Ouroboros) Muxer added in v0.10.1 

func (o *Ouroboros) Muxer() *muxer.Muxer

Muxer returns the muxer object for the Ouroboros connection

func (*Ouroboros) TxSubmission added in v0.12.0 

func (o *Ouroboros) TxSubmission() *txsubmission.TxSubmission

TxSubmission returns the tx-submission protocol handler

type OuroborosOptionFunc added in v0.18.0 

type OuroborosOptionFunc func(*Ouroboros)

OuroborosOptionFunc is a type that represents functions that modify the Ouroboros config

func WithBlockFetchConfig added in v0.18.0 

func WithBlockFetchConfig(cfg blockfetch.Config) OuroborosOptionFunc

WithBlockFetchConfig specifies BlockFetch protocol config

func WithChainSyncConfig added in v0.18.0 

func WithChainSyncConfig(cfg chainsync.Config) OuroborosOptionFunc

WithChainSyncConfig secifies ChainSync protocol config

func WithConnection added in v0.18.0 

func WithConnection(conn net.Conn) OuroborosOptionFunc

WithConnection specifies an existing connection to use. If none is provided, the Dial() function can be used to create one later

func WithDelayMuxerStart added in v0.18.0 

func WithDelayMuxerStart(delayMuxerStart bool) OuroborosOptionFunc

WithDelayMuxerStart specifies whether to delay the muxer start. This is useful if you need to take some custom actions before the muxer starts processing messages, generally when acting as a server

func WithErrorChan added in v0.18.0 

func WithErrorChan(errorChan chan error) OuroborosOptionFunc

WithErrorChan specifies the error channel to use. If none is provided, one will be created

func WithFullDuplex added in v0.18.0 

func WithFullDuplex(fullDuplex bool) OuroborosOptionFunc

WithFullDuplex specifies whether to enable full-duplex mode when acting as a client

func WithKeepAlive added in v0.18.0 

func WithKeepAlive(keepAlive bool) OuroborosOptionFunc

WithKeepAlives specifies whether to use keep-alives. This is disabled by default

func WithKeepAliveConfig added in v0.18.0 

func WithKeepAliveConfig(cfg keepalive.Config) OuroborosOptionFunc

WithKeepAliveConfig specifies KeepAlive protocol config

func WithLocalStateQueryConfig added in v0.18.0 

func WithLocalStateQueryConfig(cfg localstatequery.Config) OuroborosOptionFunc

WithLocalStateQueryConfig specifies LocalStateQuery protocol config

func WithLocalTxSubmissionConfig added in v0.18.0 

func WithLocalTxSubmissionConfig(cfg localtxsubmission.Config) OuroborosOptionFunc

WithLocalTxSubmissionConfig specifies LocalTxSubmission protocol config

func WithNetwork added in v0.29.0 

func WithNetwork(network Network) OuroborosOptionFunc

WithNetwork specifies the network

func WithNetworkMagic added in v0.18.0 

func WithNetworkMagic(networkMagic uint32) OuroborosOptionFunc

WithNetworkMagic specifies the network magic value

func WithNodeToNode added in v0.18.0 

func WithNodeToNode(nodeToNode bool) OuroborosOptionFunc

WithNodeToNode specifies whether to use the node-to-node protocol. The default is to use node-to-client

func WithServer added in v0.18.0 

func WithServer(server bool) OuroborosOptionFunc

WithServer specifies whether to act as a server

func WithTxSubmissionConfig added in v0.18.0 

func WithTxSubmissionConfig(cfg txsubmission.Config) OuroborosOptionFunc

WithTxSubmissionConfig specifies TxSubmission protocol config

Source Files

View all Source files

Directories

Path Synopsis
cmd
common
go-ouroboros-network
tx-monitor
Package muxer implements the muxer/demuxer that allows multiple mini-protocols to run over a single connection.
 Package muxer implements the muxer/demuxer that allows multiple mini-protocols to run over a single connection.
Package protocol provides the common functionality for mini-protocols
 Package protocol provides the common functionality for mini-protocols
blockfetch
chainsync
Package chainsync implements the Ouroboros chain-sync protocol
 Package chainsync implements the Ouroboros chain-sync protocol
common
The common package contains types used by multiple mini-protocols
 The common package contains types used by multiple mini-protocols
handshake
Package handshake implements the Ouroboros handshake protocol
 Package handshake implements the Ouroboros handshake protocol
keepalive
localstatequery
Package localstatequery implements the Ouroboros local-state-query protocol
 Package localstatequery implements the Ouroboros local-state-query protocol
localtxmonitor
Package localtxmonitor implements the Ouroboros local-tx-monitor protocol
 Package localtxmonitor implements the Ouroboros local-tx-monitor protocol
localtxsubmission
Package localtxsubmission implements the Ouroboros local-tx-submission protocol
 Package localtxsubmission implements the Ouroboros local-tx-submission protocol
txsubmission
Package utils provides random utility functions
 Package utils provides random utility functions

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.