dingo

README

Dingo

Dingo

⚠️ This is a work in progress and is currently under heavy development

Running

Dingo does not support a configuration file of its own and uses environment variables to modify its own behavior.

This behavior can be changed via the following environment variables:

• CARDANO_BIND_ADDR
  • IP address to bind for listening (default: 0.0.0.0)
• CARDANO_CONFIG
  • Full path to the Cardano node configuration (default: ./config/cardano/preview/config.json)
  • Use your own configuration files for different networks
  • Genesis configuration files are read from the same directory by default
• CARDANO_DATABASE_PATH
  • A directory which contains the ledger database files (default: .dingo)
  • This is the location for persistent data storage for the ledger
• CARDANO_INTERSECT_TIP
  • Ignore prior chain history and start from current position (default: false)
  • This is experimental and will likely break... use with caution
• CARDANO_METRICS_PORT
  • TCP port to bind for listening for Prometheus metrics (default: 12798)
• CARDANO_NETWORK
  • Named Cardano network (default: preview)
• CARDANO_PRIVATE_BIND_ADDR
  • IP address to bind for listening for Ouroboros NtC (default: 127.0.0.1)
• CARDANO_PRIVATE_PORT
  • TCP port to bind for listening for Ouroboros NtC (default: 3002)
• CARDANO_RELAY_PORT
  • TCP port to bind for listening for Ouroboros NtN (default: 3001)
• CARDANO_SOCKET_PATH
  • UNIX socket path for listening (default: dingo.socket)
  • This socket speaks Ouroboros NtC and is used by client software
• CARDANO_TOPOLOGY
  • Full path to the Cardano node topology (default: "")
• CARDANO_UTXORPC_PORT
  • TCP port to bind for listening for UTxO RPC (default: 9090)
• TLS_CERT_FILE_PATH - SSL certificate to use, requires TLS_KEY_FILE_PATH (default: empty)
• TLS_KEY_FILE_PATH - SSL certificate key to use (default: empty)

Example

Running on mainnet (😅):

CARDANO_NODE=mainnet ./dingo

Dingo will drop a dingo.socket file which can be used by other clients, such as cardano-cli or software like adder or kupo. This has only had limited testing, so success/failure reports are very welcome and encouraged!

Features

• Network
  • UTxO RPC
  • Ouroboros
    • Node-to-node
      • ChainSync
      • BlockFetch
      • TxSubmission2
    • Node-to-client
      • ChainSync
      • LocalTxMonitor
      • LocalTxSubmission
      • LocalStateQuery
    • Peer governor
      • Topology config
      • Peer churn
      • Ledger peers
    • Connection manager
      • Inbound connections
        • Node-to-client over TCP
        • Node-to-client over UNIX socket
        • Node-to-node over TCP
      • Outbound connections
        • Node-to-node over TCP
• Ledger
  • Blocks
    • Block storage
    • Chain selection
  • UTxO tracking
  • Protocol parameters
  • Certificates
    • Pool registration
    • Stake registration/delegation
    • Governance
  • Transaction validation
    • Phase 1 validation
      • UTxO rules
      • Witnesses
      • Block body
      • Certificates
      • Delegation/pools
      • Governance
    • Phase 2 validation
      • Smart contracts
• Mempool
  • Accept transactions from local clients
  • Distribute transactions to other nodes
  • Validation of transaction on add
  • Consumer tracking
  • Transaction purging on chain update

Additional planned features can be found in our issue tracker and project boards.

Catalyst Fund 12 - Go Node (Dingo)
Catalyst Fund 13 - Archive Node

Check the issue tracker for known issues. Due to rapid development, bugs happen especially as there is functionality which has not yet been developed.

Development / Building

This requires Go 1.23 or better is installed. You also need make.

# Build
make
# Run
./dingo

You can also run the code without building a binary, first

go run ./cmd/dingo/

Documentation

Index

• type Config
  • func NewConfig(opts ...ConfigOptionFunc) Config
• type ConfigOptionFunc
  • func WithCardanoNodeConfig(cardanoNodeConfig *cardano.CardanoNodeConfig) ConfigOptionFunc
  • func WithDatabasePath(dataDir string) ConfigOptionFunc
  • func WithIntersectPoints(points []ocommon.Point) ConfigOptionFunc
  • func WithIntersectTip(intersectTip bool) ConfigOptionFunc
  • func WithListeners(listeners ...ListenerConfig) ConfigOptionFunc
  • func WithLogger(logger *slog.Logger) ConfigOptionFunc
  • func WithNetwork(network string) ConfigOptionFunc
  • func WithNetworkMagic(networkMagic uint32) ConfigOptionFunc
  • func WithOutboundSourcePort(port uint) ConfigOptionFunc
  • func WithPeerSharing(peerSharing bool) ConfigOptionFunc
  • func WithPrometheusRegistry(registry prometheus.Registerer) ConfigOptionFunc
  • func WithTopologyConfig(topologyConfig *topology.TopologyConfig) ConfigOptionFunc
  • func WithTracing(tracing bool) ConfigOptionFunc
  • func WithTracingStdout(stdout bool) ConfigOptionFunc
  • func WithUtxorpcPort(port uint) ConfigOptionFunc
  • func WithUtxorpcTlsCertFilePath(path string) ConfigOptionFunc
  • func WithUtxorpcTlsKeyFilePath(path string) ConfigOptionFunc
• type ListenerConfig
• type Node
  • func New(cfg Config) (*Node, error)
  • func (n *Node) Run() error
  • func (n *Node) Stop() error

Types

type Config

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

func NewConfig

func NewConfig(opts ...ConfigOptionFunc) Config

NewConfig creates a new dingo config with the specified options

type ConfigOptionFunc

type ConfigOptionFunc func(*Config)

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

func WithCardanoNodeConfig

func WithCardanoNodeConfig(
	cardanoNodeConfig *cardano.CardanoNodeConfig,
) ConfigOptionFunc

WithCardanoNodeConfig specifies the CardanoNodeConfig object to use. This is mostly used for loading genesis config files referenced by the dingo config

func WithDatabasePath

func WithDatabasePath(dataDir string) ConfigOptionFunc

WithDatabasePath specifies the persistent data directory to use. The default is to store everything in memory

func WithIntersectPoints

func WithIntersectPoints(points []ocommon.Point) ConfigOptionFunc

WithIntersectPoints specifies intersect point(s) for the initial chainsync. The default is to start at chain genesis

func WithIntersectTip

func WithIntersectTip(intersectTip bool) ConfigOptionFunc

WithIntersectTip specifies whether to start the initial chainsync at the current tip. The default is to start at chain genesis

func WithListeners

func WithListeners(listeners ...ListenerConfig) ConfigOptionFunc

WithListeners specifies the listener config(s) to use

func WithLogger

func WithLogger(logger *slog.Logger) ConfigOptionFunc

WithLogger specifies the logger to use. This defaults to discarding log output

func WithNetwork

func WithNetwork(network string) ConfigOptionFunc

WithNetwork specifies the named network to operate on. This will automatically set the appropriate network magic value

func WithNetworkMagic

func WithNetworkMagic(networkMagic uint32) ConfigOptionFunc

WithNetworkMagic specifies the network magic value to use. This will override any named network specified

func WithOutboundSourcePort

func WithOutboundSourcePort(port uint) ConfigOptionFunc

WithOutboundSourcePort specifies the source port to use for outbound connections. This defaults to dynamic source ports

func WithPeerSharing

func WithPeerSharing(peerSharing bool) ConfigOptionFunc

WithPeerSharing specifies whether to enable peer sharing. This is disabled by default

func WithPrometheusRegistry

func WithPrometheusRegistry(registry prometheus.Registerer) ConfigOptionFunc

WithPrometheusRegistry specifies a prometheus.Registerer instance to add metrics to. In most cases, prometheus.DefaultRegistry would be a good choice to get metrics working

func WithTopologyConfig

func WithTopologyConfig(
	topologyConfig *topology.TopologyConfig,
) ConfigOptionFunc

WithTopologyConfig specifies a topology.TopologyConfig to use for outbound peers

func WithTracing

func WithTracing(tracing bool) ConfigOptionFunc

WithTracing enables tracing. By default, spans are submitted to a HTTP(s) endpoint using OTLP. This can be configured using the OTEL_EXPORTER_OTLP_* env vars documented in the README for go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp

func WithTracingStdout

func WithTracingStdout(stdout bool) ConfigOptionFunc

WithTracingStdout enables tracing output to stdout. This also requires tracing to enabled separately. This is mostly useful for debugging

func WithUtxorpcPort

func WithUtxorpcPort(port uint) ConfigOptionFunc

WithUtxorpcPort specifies the port to use for the gRPC API listener. This defaults to port 9090

func WithUtxorpcTlsCertFilePath

func WithUtxorpcTlsCertFilePath(path string) ConfigOptionFunc

WithUtxorpcTlsCertFilePath specifies the path to the TLS certificate for the gRPC API listener. This defaults to empty

func WithUtxorpcTlsKeyFilePath

func WithUtxorpcTlsKeyFilePath(path string) ConfigOptionFunc

WithUtxorpcTlsKeyFilePath specifies the path to the TLS key for the gRPC API listener. This defaults to empty

type ListenerConfig

type ListenerConfig = connmanager.ListenerConfig

type Node

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

func New

func New(cfg Config) (*Node, error)

func (*Node) Run

func (n *Node) Run() error

func (*Node) Stop

func (n *Node) Stop() error