ouroboros

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
Chain-Sync	Implemented
Block-Fetch	Implemented
TxSubmission	Not Implemented
Local TxSubmission	Implemented
Local State Query	Not Implemented
Keep-Alive	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
• Variables
• func GetProtocolVersionsNtC() []uint16
• func GetProtocolVersionsNtN() []uint16
• type Ouroboros
  • func New(options *OuroborosOptions) (*Ouroboros, error)
  • func (o *Ouroboros) Dial(proto string, address string) error
• type OuroborosOptions
• type ProtocolVersionNtC
  • func GetProtocolVersionNtC(version uint16) ProtocolVersionNtC
• type ProtocolVersionNtN
  • func GetProtocolVersionNtN(version uint16) ProtocolVersionNtN

Constants

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

Variables

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,
	},
}

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

var ProtocolVersionMapNtN = map[uint16]ProtocolVersionNtN{
	7: ProtocolVersionNtN{
		EnableShelleyEra:            true,
		EnableKeepAliveProtocol:     true,
		EnableAllegraEra:            true,
		EnableMaryEra:               true,
		EnableTxSubmission2Protocol: true,
		EnableAlonzoEra:             true,
	},
	8: ProtocolVersionNtN{
		EnableShelleyEra:            true,
		EnableKeepAliveProtocol:     true,
		EnableAllegraEra:            true,
		EnableMaryEra:               true,
		EnableTxSubmission2Protocol: true,
		EnableAlonzoEra:             true,
		EnableFullDuplex:            true,
	},
}

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

Functions

func GetProtocolVersionsNtC

func GetProtocolVersionsNtC() []uint16

func GetProtocolVersionsNtN

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
	// contains filtered or unexported fields
}

func New

func New(options *OuroborosOptions) (*Ouroboros, 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()

type OuroborosOptions

type OuroborosOptions struct {
	Conn                            net.Conn
	NetworkMagic                    uint32
	ErrorChan                       chan error
	Server                          bool
	UseNodeToNodeProtocol           bool
	SendKeepAlives                  bool
	ChainSyncCallbackConfig         *chainsync.ChainSyncCallbackConfig
	BlockFetchCallbackConfig        *blockfetch.BlockFetchCallbackConfig
	KeepAliveCallbackConfig         *keepalive.KeepAliveCallbackConfig
	LocalTxSubmissionCallbackConfig *localtxsubmission.CallbackConfig
}

type ProtocolVersionNtC

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
	EnableLocalTxMonitorProtocol bool
}

func GetProtocolVersionNtC

func GetProtocolVersionNtC(version uint16) ProtocolVersionNtC

type ProtocolVersionNtN

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
	EnableTxSubmission2Protocol bool
	EnableAlonzoEra             bool
	EnableFullDuplex            bool
}

func GetProtocolVersionNtN

func GetProtocolVersionNtN(version uint16) ProtocolVersionNtN