ouroboros

package module
v0.38.2 Latest Latest
Warning

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

 Go to latest Published: May 11, 2023 License: Apache-2.0 Imports: 15 Imported by: 19

README

gouroboros

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 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 gouroboros-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.

$ ./gouroboros -address localhost:8082 -network testnet ...

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

$ ./gouroboros -address localhost:8081 -ntn -network testnet ...

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

$ ./gouroboros ... chain-sync -start-era byron

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

$ ./gouroboros ... local-tx-submission ...

Test following the chain tip in the preview network.

$ ./gouroboros -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, PublicRootAddress: "relays-new.cardano-mainnet.iohk.io", PublicRootPort: 3001}
	NetworkPreprod = Network{Id: 2, Name: "preprod", NetworkMagic: 1, PublicRootAddress: "preprod-node.world.dev.cardano.org", PublicRootPort: 30000}
	NetworkPreview = Network{Id: 3, Name: "preview", NetworkMagic: 2, PublicRootAddress: "preview-node.world.dev.cardano.org", PublicRootPort: 30002}

	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 

type Network struct {
	Id                uint
	Name              string
	NetworkMagic      uint32
	PublicRootAddress string
	PublicRootPort    uint
}

Network represents a Cardano network

func NetworkById 

func NetworkById(id uint) Network

NetworkById returns a predefined network by ID

func NetworkByName 

func NetworkByName(name string) Network

NetworkByName returns a predefined network by name

func NetworkByNetworkMagic 

func NetworkByNetworkMagic(networkMagic uint32) Network

NetworkByNetworkMagic returns a predefined network by network magic

func (Network) String 

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 

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

BlockFetch returns the block-fetch protocol handler

func (*Ouroboros) ChainSync 

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

ChainSync returns the chain-sync protocol handler

func (*Ouroboros) Close 

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 

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

KeepAlive returns the keep-alive protocol handler

func (*Ouroboros) LocalStateQuery 

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

LocalStateQuery returns the local-state-query protocol handler

func (*Ouroboros) LocalTxMonitor 

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

LocalTxMonitor returns the local-tx-monitor protocol handler

func (*Ouroboros) LocalTxSubmission 

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

LocalTxSubmission returns the local-tx-submission protocol handler

func (*Ouroboros) Muxer 

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

Muxer returns the muxer object for the Ouroboros connection

func (*Ouroboros) TxSubmission 

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

TxSubmission returns the tx-submission protocol handler

type OuroborosOptionFunc 

type OuroborosOptionFunc func(*Ouroboros)

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

func WithBlockFetchConfig 

func WithBlockFetchConfig(cfg blockfetch.Config) OuroborosOptionFunc

WithBlockFetchConfig specifies BlockFetch protocol config

func WithChainSyncConfig 

func WithChainSyncConfig(cfg chainsync.Config) OuroborosOptionFunc

WithChainSyncConfig secifies ChainSync protocol config

func WithConnection 

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 

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 

func WithErrorChan(errorChan chan error) OuroborosOptionFunc

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

func WithFullDuplex 

func WithFullDuplex(fullDuplex bool) OuroborosOptionFunc

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

func WithKeepAlive 

func WithKeepAlive(keepAlive bool) OuroborosOptionFunc

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

func WithKeepAliveConfig 

func WithKeepAliveConfig(cfg keepalive.Config) OuroborosOptionFunc

WithKeepAliveConfig specifies KeepAlive protocol config

func WithLocalStateQueryConfig 

func WithLocalStateQueryConfig(cfg localstatequery.Config) OuroborosOptionFunc

WithLocalStateQueryConfig specifies LocalStateQuery protocol config

func WithLocalTxSubmissionConfig 

func WithLocalTxSubmissionConfig(cfg localtxsubmission.Config) OuroborosOptionFunc

WithLocalTxSubmissionConfig specifies LocalTxSubmission protocol config

func WithNetwork 

func WithNetwork(network Network) OuroborosOptionFunc

WithNetwork specifies the network

func WithNetworkMagic 

func WithNetworkMagic(networkMagic uint32) OuroborosOptionFunc

WithNetworkMagic specifies the network magic value

func WithNodeToNode 

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 

func WithServer(server bool) OuroborosOptionFunc

WithServer specifies whether to act as a server

func WithTxSubmissionConfig 

func WithTxSubmissionConfig(cfg txsubmission.Config) OuroborosOptionFunc

WithTxSubmissionConfig specifies TxSubmission protocol config

Source Files

View all Source files

Directories

Path Synopsis
cmd
block-fetch
common
gouroboros
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.