ouroboros

package module
v0.73.3 Latest Latest
Warning

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

 Go to latest Published: Mar 11, 2024 License: Apache-2.0 Imports: 20 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

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

Variables

View Source 
var (
	NetworkTestnet = Network{
		Id:           ledger.AddressNetworkTestnet,
		Name:         "testnet",
		NetworkMagic: 1097911063,
	}
	NetworkMainnet = Network{
		Id:                ledger.AddressNetworkMainnet,
		Name:              "mainnet",
		NetworkMagic:      764824073,
		PublicRootAddress: "backbone.cardano-mainnet.iohk.io",
		PublicRootPort:    3001,
	}
	NetworkPreprod = Network{
		Id:                ledger.AddressNetworkTestnet,
		Name:              "preprod",
		NetworkMagic:      1,
		PublicRootAddress: "preprod-node.world.dev.cardano.org",
		PublicRootPort:    30000,
	}
	NetworkPreview = Network{
		Id:                ledger.AddressNetworkTestnet,
		Name:              "preview",
		NetworkMagic:      2,
		PublicRootAddress: "preview-node.play.dev.cardano.org",
		PublicRootPort:    3001,
	}
	NetworkSancho = Network{
		Id:                ledger.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) 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 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(connId int, 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 int) *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 int)

type ConnectionManagerConfig added in v0.65.0 

type ConnectionManagerConfig struct {
	ConnClosedFunc ConnectionManagerConnClosedFunc
}

type ConnectionManagerConnClosedFunc added in v0.71.0 

type ConnectionManagerConnClosedFunc func(int, error)

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

type ConnectionManagerConnection added in v0.65.0 

type ConnectionManagerConnection struct {
	Id   int
	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 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
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.