ouroboros

package module
v0.93.1 Latest Latest
Warning

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

 Go to latest Published: Aug 26, 2024 License: Apache-2.0 Imports: 21 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
        • Parameter updates
      • Allegra
        • Blocks
        • Transactions
        • TX inputs
        • TX outputs
        • Parameter updates
      • Mary
        • Blocks
        • Transactions
        • TX inputs
        • TX outputs
        • Parameter updates
      • Alonzo
        • Blocks
        • Transactions
        • TX inputs
        • TX outputs
        • Parameter updates
      • Babbage
        • Blocks
        • Transactions
        • TX inputs
        • TX outputs
        • Parameter updates
      • Conway
        • Blocks
        • Transactions
        • TX inputs
        • TX outputs
        • Parameter updates
    • 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
      • Voting procedures
      • Proposal procedures
      • Current treasury value
      • Donation
  • 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

gOuroboros includes automated tests that cover various aspects of its functionality, but not all. For more than the basics, manual testing is required.

Running the automated tests

make test

Manual testing

Various small test programs can be found in cmd/ in this repo or in the gOuroboros Starter Kit repo. Some of them can be run against public nodes via NtN protocols, but some may require access to the UNIX socket of a local node for NtC protocols.

Run chain-sync from the start of a particular era

This is useful for testing changes to the handling of ledger types for a particular era. It will decode each block and either print a summary line for the block or an error.

Start by building the test programs:

make

Run the chain-sync test program against a public mainnet node, starting at the beginning of the Shelley era:

./gouroboros -address backbone.cardano-mainnet.iohk.io:3001 -network mainnet -ntn chain-sync -bulk -start-era shelley

This will produce a LOT of output and take quite a few hours to reach chain tip. You're mostly looking for it to get through all blocks of the chosen start era before hitting the next era or chain tip

Dump details of a particular block

You can use the block-fetch program from gouroboros-starter-kit to fetch a particular block and dump its details. You must provide at least the block slot and hash. This is useful for debugging decoding problems, since it allows fetching a specific block and decoding it over and over.

BLOCK_FETCH_SLOT=120521627 BLOCK_FETCH_HASH=afd4c97e32003d9803a305011cbd8796e6b36bf61576567206887e35795b6e09 ./block-fetch

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

View Source 
const (
	// Default connection timeout
	DefaultConnectTimeout = 30 * time.Second
)

Variables

View Source 
var (
	NetworkTestnet = Network{
		Id:           common.AddressNetworkTestnet,
		Name:         "testnet",
		NetworkMagic: 1097911063,
	}
	NetworkMainnet = Network{
		Id:                common.AddressNetworkMainnet,
		Name:              "mainnet",
		NetworkMagic:      764824073,
		PublicRootAddress: "backbone.cardano-mainnet.iohk.io",
		PublicRootPort:    3001,
	}
	NetworkPreprod = Network{
		Id:                common.AddressNetworkTestnet,
		Name:              "preprod",
		NetworkMagic:      1,
		PublicRootAddress: "preprod-node.world.dev.cardano.org",
		PublicRootPort:    30000,
	}
	NetworkPreview = Network{
		Id:                common.AddressNetworkTestnet,
		Name:              "preview",
		NetworkMagic:      2,
		PublicRootAddress: "preview-node.play.dev.cardano.org",
		PublicRootPort:    3001,
	}
	NetworkSancho = Network{
		Id:                common.AddressNetworkTestnet,
		Name:              "sanchonet",
		NetworkMagic:      4,
		PublicRootAddress: "sanchonet-node.play.dev.cardano.org",
		PublicRootPort:    3001,
	}

	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 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. It works the same as [DialTimeout], except that it provides a default connect timeout

func (*Connection) DialTimeout added in v0.68.0 

func (c *Connection) DialTimeout(
	proto string,
	address string,
	timeout time.Duration,
) error

DialTimeout will establish a connection using the specified protocol, address, and timeout. These parameters are passed to the net.DialTimeout 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) Id added in v0.78.0 

func (c *Connection) Id() ConnectionId

Id returns the connection ID

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) ProtocolVersion added in v0.77.0 

func (c *Connection) ProtocolVersion() (uint16, protocol.VersionData)

ProtocolVersion returns the negotiated protocol version and the version data from the remote peer

func (*Connection) TxSubmission added in v0.40.0 

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

TxSubmission returns the tx-submission protocol handler

type ConnectionId added in v0.78.0 

type ConnectionId = connection.ConnectionId

type ConnectionManager added in v0.65.0 

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

func NewConnectionManager added in v0.65.0 

func NewConnectionManager(cfg ConnectionManagerConfig) *ConnectionManager

func (*ConnectionManager) AddConnection added in v0.65.0 

func (c *ConnectionManager) AddConnection(conn *Connection)

func (*ConnectionManager) AddHost added in v0.65.0 

func (c *ConnectionManager) AddHost(
	address string,
	port uint,
	tags ...ConnectionManagerTag,
)

func (*ConnectionManager) AddHostsFromTopology added in v0.65.0 

func (c *ConnectionManager) AddHostsFromTopology(topology *TopologyConfig)

func (*ConnectionManager) GetConnectionById added in v0.65.0 

func (c *ConnectionManager) GetConnectionById(
	connId ConnectionId,
) *ConnectionManagerConnection

func (*ConnectionManager) GetConnectionsByTags added in v0.65.0 

func (c *ConnectionManager) GetConnectionsByTags(
	tags ...ConnectionManagerTag,
) []*ConnectionManagerConnection

func (*ConnectionManager) RemoveConnection added in v0.66.0 

func (c *ConnectionManager) RemoveConnection(connId ConnectionId)

type ConnectionManagerConfig added in v0.65.0 

type ConnectionManagerConfig struct {
	ConnClosedFunc ConnectionManagerConnClosedFunc
}

type ConnectionManagerConnClosedFunc added in v0.71.0 

type ConnectionManagerConnClosedFunc func(ConnectionId, error)

ConnectionManagerConnClosedFunc is a function that takes a connection ID and an optional error

type ConnectionManagerConnection added in v0.65.0 

type ConnectionManagerConnection struct {
	Conn *Connection
	Tags map[ConnectionManagerTag]bool
}

func (*ConnectionManagerConnection) AddTags added in v0.65.0 

func (c *ConnectionManagerConnection) AddTags(tags ...ConnectionManagerTag)

func (*ConnectionManagerConnection) RemoveTags added in v0.65.0 

func (c *ConnectionManagerConnection) RemoveTags(tags ...ConnectionManagerTag)

type ConnectionManagerHost added in v0.65.0 

type ConnectionManagerHost struct {
	Address string
	Port    uint
	Tags    map[ConnectionManagerTag]bool
}

type ConnectionManagerTag added in v0.65.0 

type ConnectionManagerTag uint16

ConnectionManagerTag represents the various tags that can be associated with a host or connection 

const (
	ConnectionManagerTagNone ConnectionManagerTag = iota

	ConnectionManagerTagHostProducer
	ConnectionManagerTagHostLocalRoot
	ConnectionManagerTagHostPublicRoot
	ConnectionManagerTagHostP2PLedger
	ConnectionManagerTagHostP2PGossip

	ConnectionManagerTagRoleInitiator
	ConnectionManagerTagRoleResponder
)

func (ConnectionManagerTag) String added in v0.65.0 

func (c ConnectionManagerTag) String() string

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 WithLocalTxMonitorConfig added in v0.73.0 

func WithLocalTxMonitorConfig(
	cfg localtxmonitor.Config,
) ConnectionOptionFunc

WithLocalTxMonitorConfig specifies LocalTxMonitor 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 WithPeerSharing added in v0.75.0 

func WithPeerSharing(peerSharing bool) ConnectionOptionFunc

WithPeerSharing specifies whether to enable peer sharing. This affects both the protocol handshake and whether the PeerSharing protocol is enabled

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 // network ID used for addresses
	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 TopologyConfig added in v0.62.0 

type TopologyConfig struct {
	Producers          []TopologyConfigLegacyProducer `json:"Producers"`
	LocalRoots         []TopologyConfigP2PLocalRoot   `json:"localRoots"`
	PublicRoots        []TopologyConfigP2PPublicRoot  `json:"publicRoots"`
	UseLedgerAfterSlot uint64                         `json:"useLedgerAfterSlot"`
}

TopologyConfig represents a Cardano node topology config

func NewTopologyConfigFromFile added in v0.62.0 

func NewTopologyConfigFromFile(path string) (*TopologyConfig, error)

func NewTopologyConfigFromReader added in v0.62.0 

func NewTopologyConfigFromReader(r io.Reader) (*TopologyConfig, error)

type TopologyConfigLegacyProducer added in v0.62.0 

type TopologyConfigLegacyProducer struct {
	Address   string `json:"addr"`
	Port      uint   `json:"port"`
	Valency   uint   `json:"valency"`
	Continent string `json:"continent"`
	State     string `json:"state"`
}

type TopologyConfigP2PAccessPoint added in v0.62.0 

type TopologyConfigP2PAccessPoint struct {
	Address string `json:"address"`
	Port    uint   `json:"port"`
}

type TopologyConfigP2PLocalRoot added in v0.62.0 

type TopologyConfigP2PLocalRoot struct {
	AccessPoints []TopologyConfigP2PAccessPoint `json:"accessPoints"`
	Advertise    bool                           `json:"advertise"`
	Valency      uint                           `json:"valency"`
}

type TopologyConfigP2PPublicRoot added in v0.62.0 

type TopologyConfigP2PPublicRoot struct {
	AccessPoints []TopologyConfigP2PAccessPoint `json:"accessPoints"`
	Advertise    bool                           `json:"advertise"`
	Valency      uint                           `json:"valency"`
}

Source Files

View all Source files

Directories

Path Synopsis
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.
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.
cmd
common
gouroboros
tx-submission
internal
test
allegra
alonzo
babbage
byron
common
conway
mary
shelley
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 peersharing implements the Ouroboros PeerSharing protocol
 Package peersharing implements the Ouroboros PeerSharing protocol
txsubmission
Package txsubmission implements the Ouroboros TxSubmission protocol
 Package txsubmission implements the Ouroboros TxSubmission protocol

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.