ouroboros

package module
v0.18.0 Latest Latest
Warning

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

 Go to latest Published: Oct 21, 2022 License: Apache-2.0 Imports: 11 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 -testnet ...

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

$ ./go-ouroboros-network -address localhost:8081 -ntn -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 ...
Stopping the local cardano-node instance
$ docker-compose down --volumes

Documentation

Index

Constants

View Source 
const (
	// The NtC protocol versions have the 15th bit set in the handshake
	PROTOCOL_VERSION_NTC_FLAG = 0x8000
)

Variables

View Source 
var ProtocolVersionMapNtC = map[uint16]ProtocolVersionNtC{
	9: ProtocolVersionNtC{
		EnableLocalQueryProtocol: true,
		EnableShelleyEra:         true,
		EnableAllegraEra:         true,
		EnableMaryEra:            true,
		EnableAlonzoEra:          true,
	},

	10: ProtocolVersionNtC{
		EnableLocalQueryProtocol: true,
		EnableShelleyEra:         true,
		EnableAllegraEra:         true,
		EnableMaryEra:            true,
		EnableAlonzoEra:          true,
	},

	11: ProtocolVersionNtC{
		EnableLocalQueryProtocol: true,
		EnableShelleyEra:         true,
		EnableAllegraEra:         true,
		EnableMaryEra:            true,
		EnableAlonzoEra:          true,
	},
	12: ProtocolVersionNtC{
		EnableLocalQueryProtocol:     true,
		EnableShelleyEra:             true,
		EnableAllegraEra:             true,
		EnableMaryEra:                true,
		EnableAlonzoEra:              true,
		EnableLocalTxMonitorProtocol: true,
	},
	13: ProtocolVersionNtC{
		EnableLocalQueryProtocol:     true,
		EnableShelleyEra:             true,
		EnableAllegraEra:             true,
		EnableMaryEra:                true,
		EnableAlonzoEra:              true,
		EnableBabbageEra:             true,
		EnableLocalTxMonitorProtocol: true,
	},

	14: ProtocolVersionNtC{
		EnableLocalQueryProtocol:     true,
		EnableShelleyEra:             true,
		EnableAllegraEra:             true,
		EnableMaryEra:                true,
		EnableAlonzoEra:              true,
		EnableBabbageEra:             true,
		EnableLocalTxMonitorProtocol: true,
	},
}

We don't bother supporting NtC protocol versions before 9 (when Alonzo was enabled)

View Source 
var ProtocolVersionMapNtN = map[uint16]ProtocolVersionNtN{
	7: ProtocolVersionNtN{
		EnableShelleyEra:        true,
		EnableKeepAliveProtocol: true,
		EnableAllegraEra:        true,
		EnableMaryEra:           true,
		EnableAlonzoEra:         true,
	},
	8: ProtocolVersionNtN{
		EnableShelleyEra:        true,
		EnableKeepAliveProtocol: true,
		EnableAllegraEra:        true,
		EnableMaryEra:           true,
		EnableAlonzoEra:         true,
	},
	9: ProtocolVersionNtN{
		EnableShelleyEra:        true,
		EnableKeepAliveProtocol: true,
		EnableAllegraEra:        true,
		EnableMaryEra:           true,
		EnableAlonzoEra:         true,
		EnableBabbageEra:        true,
	},
	10: ProtocolVersionNtN{
		EnableShelleyEra:        true,
		EnableKeepAliveProtocol: true,
		EnableAllegraEra:        true,
		EnableMaryEra:           true,
		EnableAlonzoEra:         true,
		EnableBabbageEra:        true,
		EnableFullDuplex:        true,
	},
}

We don't bother supporting NtN protocol versions before 7 (when Alonzo was enabled)

Functions

func GetProtocolVersionsNtC added in v0.6.0 

func GetProtocolVersionsNtC() []uint16

func GetProtocolVersionsNtN added in v0.6.0 

func GetProtocolVersionsNtN() []uint16

Types

type Ouroboros 

type Ouroboros struct {
	ErrorChan chan error

	// Mini-protocols
	Handshake *handshake.Handshake
	ChainSync *chainsync.ChainSync

	BlockFetch *blockfetch.BlockFetch

	KeepAlive *keepalive.KeepAlive

	LocalTxSubmission *localtxsubmission.LocalTxSubmission

	LocalStateQuery *localstatequery.LocalStateQuery

	TxSubmission *txsubmission.TxSubmission
	// contains filtered or unexported fields
}

func New 

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

func (*Ouroboros) Close added in v0.13.1 

func (o *Ouroboros) Close() error

func (*Ouroboros) Dial 

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

Convenience function for creating a connection if you didn't provide one when calling New()

func (*Ouroboros) Muxer added in v0.10.1 

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

type OuroborosOptionFunc added in v0.18.0 

type OuroborosOptionFunc func(*Ouroboros)

func WithBlockFetchConfig added in v0.18.0 

func WithBlockFetchConfig(cfg blockfetch.Config) OuroborosOptionFunc

func WithChainSyncConfig added in v0.18.0 

func WithChainSyncConfig(cfg chainsync.Config) OuroborosOptionFunc

func WithConnection added in v0.18.0 

func WithConnection(conn net.Conn) OuroborosOptionFunc

func WithDelayMuxerStart added in v0.18.0 

func WithDelayMuxerStart(delayMuxerStart bool) OuroborosOptionFunc

func WithErrorChan added in v0.18.0 

func WithErrorChan(errorChan chan error) OuroborosOptionFunc

func WithFullDuplex added in v0.18.0 

func WithFullDuplex(fullDuplex bool) OuroborosOptionFunc

func WithKeepAlive added in v0.18.0 

func WithKeepAlive(keepAlive bool) OuroborosOptionFunc

func WithKeepAliveConfig added in v0.18.0 

func WithKeepAliveConfig(cfg keepalive.Config) OuroborosOptionFunc

func WithLocalStateQueryConfig added in v0.18.0 

func WithLocalStateQueryConfig(cfg localstatequery.Config) OuroborosOptionFunc

func WithLocalTxSubmissionConfig added in v0.18.0 

func WithLocalTxSubmissionConfig(cfg localtxsubmission.Config) OuroborosOptionFunc

func WithNetworkMagic added in v0.18.0 

func WithNetworkMagic(networkMagic uint32) OuroborosOptionFunc

func WithNodeToNode added in v0.18.0 

func WithNodeToNode(nodeToNode bool) OuroborosOptionFunc

func WithServer added in v0.18.0 

func WithServer(server bool) OuroborosOptionFunc

func WithTxSubmissionConfig added in v0.18.0 

func WithTxSubmissionConfig(cfg txsubmission.Config) OuroborosOptionFunc

type ProtocolVersionNtC added in v0.6.0 

type ProtocolVersionNtC struct {
	// Most of these are enabled in all of the protocol versions that we support, but
	// they are here for completeness
	EnableLocalQueryProtocol     bool
	EnableShelleyEra             bool
	EnableAllegraEra             bool
	EnableMaryEra                bool
	EnableAlonzoEra              bool
	EnableBabbageEra             bool
	EnableLocalTxMonitorProtocol bool
}

func GetProtocolVersionNtC added in v0.6.0 

func GetProtocolVersionNtC(version uint16) ProtocolVersionNtC

type ProtocolVersionNtN added in v0.6.0 

type ProtocolVersionNtN struct {
	// Most of these are enabled in all of the protocol versions that we support, but
	// they are here for completeness
	EnableShelleyEra        bool
	EnableKeepAliveProtocol bool
	EnableAllegraEra        bool
	EnableMaryEra           bool
	EnableAlonzoEra         bool
	EnableBabbageEra        bool
	EnableFullDuplex        bool
}

func GetProtocolVersionNtN added in v0.6.0 

func GetProtocolVersionNtN(version uint16) ProtocolVersionNtN

Source Files

View all Source files

Directories

Path Synopsis
cmd
go-ouroboros-network
blockfetch
chainsync
handshake
keepalive
localstatequery
localtxsubmission
txsubmission

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.