ouroboros

package module
v0.55.0 Latest Latest
Warning

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

 Go to latest Published: Oct 12, 2023 License: Apache-2.0 Imports: 16 Imported by: 19

README

gOurobros Logo
GitHub Go Reference Discord

Introduction

gOuroboros is a powerful and versatile framework for building Go apps that interact with the Cardano blockchain. Quickly and easily write Go apps that communicate with Cardano nodes or manage blocks/transactions. Sync the blockchain from a local or remote node, query a local node for protocol parameters or UTxOs by address, and much more.

Features

This is not an exhaustive list of existing and planned features, but it covers the bulk of it.

  • Ouroboros support
    • Muxer
      • support for multiple mini-protocols over single connection
      • support for separate initiator and responder instance for each protocol
      • support for buffer limits for each mini-protocol
    • Protocols
      • Handshake
        • Client support
        • Server support
      • Keepalive
        • Client support
        • Server support
      • ChainSync
        • Client support
        • Server support
      • BlockFetch
        • Client support
        • Server support
      • TxSubmission
        • Client support
        • Server support
      • PeerSharing
        • Client support
        • Server support
      • LocalTxSubmission
        • Client support
        • Server support
      • LocalTxMonitor
        • Client support
        • Server support
      • LocalStateQuery
        • Client support
        • Server support
        • Queries
          • System start
          • Current era
          • Chain tip
          • Era history
          • Current protocol parameters
          • Stake distribution
          • Non-myopic member rewards
          • Proposed protocol parameter updates
          • UTxOs by address
          • UTxO whole
          • UTxO by TxIn
          • Debug epoch state
          • Filtered delegations and reward accounts
          • Genesis config
          • Reward provenance
          • Stake pools
          • Stake pool params
          • Reward info pools
          • Pool state
          • Stake snapshots
          • Pool distribution
  • Ledger
    • Eras
      • Byron
        • Blocks
        • Transactions
        • TX inputs
        • TX outputs
      • Shelley
        • Blocks
        • Transactions
        • TX inputs
        • TX outputs
      • Allegra
        • Blocks
        • Transactions
        • TX inputs
        • TX outputs
      • Mary
        • Blocks
        • Transactions
        • TX inputs
        • TX outputs
      • Alonzo
        • Blocks
        • Transactions
        • TX inputs
        • TX outputs
      • Babbage
        • Blocks
        • Transactions
        • TX inputs
        • TX outputs
      • Conway
        • Blocks
        • Transactions
        • TX inputs
        • TX outputs
    • Transaction attributes
      • Inputs
      • Outputs
      • Metadata
      • Fees
      • TTL
      • Certificates
      • Staking reward withdrawls
      • Protocol parameter updates
      • Auxiliary data hash
      • Validity interval start
      • Mint operations
      • Script data hash
      • Collateral inputs
      • Required signers
      • Collateral return
      • Total collateral
      • Reference inputs
  • Testing
    • Test framework for mocking Ouroboros conversations
    • CBOR deserialization and serialization
      • Protocol messages
      • Ledger
        • Block parsing
        • Transaction parsing
  • Misc
    • Address handling
      • Decode from bech32
      • Encode as bech32
      • Deserialize from CBOR
      • Retrieve staking key

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}
	NetworkSancho  = Network{Id: 4, Name: "sancho", NetworkMagic: 4, PublicRootAddress: "sanchonet-node.world.dev.cardano.org", PublicRootPort: 30004}

	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

func GetProtocolVersionsNtC added in v0.39.0 

func GetProtocolVersionsNtC() []uint16

GetProtocolVersionNtC returns a list of supported NtC protocol versions

func GetProtocolVersionsNtN added in v0.39.0 

func GetProtocolVersionsNtN() []uint16

GetProtocolVersionNtN returns a list of supported NtN protocol versions

Types

type Connection added in v0.40.0 

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

The Connection 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 ...ConnectionOptionFunc) (*Connection, error)

New is an alias to NewConnection for backward compatibility

func NewConnection added in v0.40.0 

func NewConnection(options ...ConnectionOptionFunc) (*Connection, error)

NewConnection returns a new Connection 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 (*Connection) BlockFetch added in v0.40.0 

func (c *Connection) BlockFetch() *blockfetch.BlockFetch

BlockFetch returns the block-fetch protocol handler

func (*Connection) ChainSync added in v0.40.0 

func (c *Connection) ChainSync() *chainsync.ChainSync

ChainSync returns the chain-sync protocol handler

func (*Connection) Close added in v0.40.0 

func (c *Connection) Close() error

Close will shutdown the Ouroboros connection

func (*Connection) Dial added in v0.40.0 

func (c *Connection) 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 (*Connection) ErrorChan added in v0.40.0 

func (c *Connection) ErrorChan() chan error

ErrorChan returns the channel for asynchronous errors

func (*Connection) Handshake added in v0.40.0 

func (c *Connection) Handshake() *handshake.Handshake

Handshake returns the handshake protocol handler

func (*Connection) KeepAlive added in v0.40.0 

func (c *Connection) KeepAlive() *keepalive.KeepAlive

KeepAlive returns the keep-alive protocol handler

func (*Connection) LocalStateQuery added in v0.40.0 

func (c *Connection) LocalStateQuery() *localstatequery.LocalStateQuery

LocalStateQuery returns the local-state-query protocol handler

func (*Connection) LocalTxMonitor added in v0.40.0 

func (c *Connection) LocalTxMonitor() *localtxmonitor.LocalTxMonitor

LocalTxMonitor returns the local-tx-monitor protocol handler

func (*Connection) LocalTxSubmission added in v0.40.0 

func (c *Connection) LocalTxSubmission() *localtxsubmission.LocalTxSubmission

LocalTxSubmission returns the local-tx-submission protocol handler

func (*Connection) Muxer added in v0.40.0 

func (c *Connection) Muxer() *muxer.Muxer

Muxer returns the muxer object for the Ouroboros connection

func (*Connection) PeerSharing added in v0.41.0 

func (c *Connection) PeerSharing() *peersharing.PeerSharing

PeerSharing returns the peer-sharing protocol handler

func (*Connection) TxSubmission added in v0.40.0 

func (c *Connection) TxSubmission() *txsubmission.TxSubmission

TxSubmission returns the tx-submission protocol handler

type ConnectionOptionFunc added in v0.40.0 

type ConnectionOptionFunc func(*Connection)

ConnectionOptionFunc is a type that represents functions that modify the Connection config

func WithBlockFetchConfig 

func WithBlockFetchConfig(cfg blockfetch.Config) ConnectionOptionFunc

WithBlockFetchConfig specifies BlockFetch protocol config

func WithChainSyncConfig 

func WithChainSyncConfig(cfg chainsync.Config) ConnectionOptionFunc

WithChainSyncConfig secifies ChainSync protocol config

func WithConnection 

func WithConnection(conn net.Conn) ConnectionOptionFunc

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) ConnectionOptionFunc

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 WithDelayProtocolStart added in v0.41.0 

func WithDelayProtocolStart(delayProtocolStart bool) ConnectionOptionFunc

WithDelayProtocolStart specifies whether to delay the start of the relevant mini-protocols. This is useful if you are maintaining lots of connections and want to reduce resource overhead by only starting particular protocols

func WithErrorChan 

func WithErrorChan(errorChan chan error) ConnectionOptionFunc

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

func WithFullDuplex 

func WithFullDuplex(fullDuplex bool) ConnectionOptionFunc

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

func WithKeepAlive 

func WithKeepAlive(keepAlive bool) ConnectionOptionFunc

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

func WithKeepAliveConfig 

func WithKeepAliveConfig(cfg keepalive.Config) ConnectionOptionFunc

WithKeepAliveConfig specifies KeepAlive protocol config

func WithLocalStateQueryConfig 

func WithLocalStateQueryConfig(cfg localstatequery.Config) ConnectionOptionFunc

WithLocalStateQueryConfig specifies LocalStateQuery protocol config

func WithLocalTxSubmissionConfig 

func WithLocalTxSubmissionConfig(cfg localtxsubmission.Config) ConnectionOptionFunc

WithLocalTxSubmissionConfig specifies LocalTxSubmission protocol config

func WithNetwork 

func WithNetwork(network Network) ConnectionOptionFunc

WithNetwork specifies the network

func WithNetworkMagic 

func WithNetworkMagic(networkMagic uint32) ConnectionOptionFunc

WithNetworkMagic specifies the network magic value

func WithNodeToNode 

func WithNodeToNode(nodeToNode bool) ConnectionOptionFunc

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

func WithPeerSharingConfig added in v0.41.0 

func WithPeerSharingConfig(cfg peersharing.Config) ConnectionOptionFunc

WithPeerSharingConfig specifies PeerSharing protocol config

func WithServer 

func WithServer(server bool) ConnectionOptionFunc

WithServer specifies whether to act as a server

func WithTxSubmissionConfig 

func WithTxSubmissionConfig(cfg txsubmission.Config) ConnectionOptionFunc

WithTxSubmissionConfig specifies TxSubmission protocol config

type Network 

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

Network represents a Cardano network

func NetworkById 

func NetworkById(id uint8) 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 ProtocolVersionNtC added in v0.39.0 

type ProtocolVersionNtC struct {
	EnableLocalQueryProtocol     bool
	EnableShelleyEra             bool
	EnableAllegraEra             bool
	EnableMaryEra                bool
	EnableAlonzoEra              bool
	EnableBabbageEra             bool
	EnableConwayEra              bool
	EnableLocalTxMonitorProtocol bool
}

Most of these are enabled in all of the protocol versions that we support, but they are here for completeness

func GetProtocolVersionNtC added in v0.39.0 

func GetProtocolVersionNtC(version uint16) ProtocolVersionNtC

GetProtocolVersionNtC returns the protocol version config for the specified NtC protocol version

type ProtocolVersionNtN added in v0.39.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
	EnableConwayEra           bool
	EnableFullDuplex          bool
	EnablePeerSharingProtocol bool
}

func GetProtocolVersionNtN added in v0.39.0 

func GetProtocolVersionNtN(version uint16) ProtocolVersionNtN

GetProtocolVersionNtN returns the protocol version config for the specified NtN protocol version

Source Files

View all Source files

Directories

Path Synopsis
cmd
block-fetch
chain-tip
common
gouroboros
peer-sharing
tx-monitor
tx-submission
internal
base58
Package base58 provides an API for working with modified base58 and Base58Check encodings.
 Package base58 provides an API for working with modified base58 and Base58Check encodings.
bech32
Package bech32 provides a Go implementation of the bech32 format specified in BIP 173.
 Package bech32 provides a Go implementation of the bech32 format specified in BIP 173.
test
test/ouroboros_mock
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
peersharing
Package handshake implements the Ouroboros handshake protocol
 Package handshake implements the Ouroboros handshake 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.