blinklabs-io/gouroboros

Go implementation of the Cardano Ouroboros family of protocols

1,875 commits

updated Sep 23, 2026

See the code

README

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.

Examples

The examples/ directory contains self-contained example programs demonstrating how to use the library. Each example has its own Go module with a local replace back to this checkout:

Example	Protocol	Description
`block-fetch`	Node-to-Node	Fetch a specific block by slot and hash
`chain-sync`	NtC / NtN	Sync blocks from genesis or a specific era; supports rollback/rollforward
`chain-tip`	Node-to-Client	Get the current chain tip via ChainSync
`peer-sharing`	Node-to-Node	Request a list of peers from a remote node
`ping`	Node-to-Client	Measure connection and protocol handshake latency
`state-query`	Node-to-Client	Query protocol parameters and other node state
`tx-monitor`	Node-to-Client	Inspect the node mempool contents
`tx-submission`	Node-to-Client	Submit a signed transaction to the node

Build all examples:

make build

Run an example directly (e.g. check the current chain tip over a local socket):

go -C examples/chain-tip run .

See the inline comments in each main.go and the environment variables each command accepts for full usage details.

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

Running the linter

gOuroboros uses golangci-lint for code quality checks. Install it following the official installation guide, then run:

make lint

Manual testing

Example programs are included in the examples/ directory of this repo. Some can be run against public nodes via NtN protocols; others 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.

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

CARDANO_NODE_ADDRESS=backbone.cardano.iog.io:3001 CARDANO_NODE_NETWORK=mainnet ./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 example 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

blockchain

cardano

golang

golang-library

library

network

ouroboros

ouroboros-network

protocol

Contributors

744 commits

699 commits

159 commits

57 commits

Similar repos

blinklabs-io/dingo

Cardano Blockchain Node

same org

IntersectMBO/ouroboros-network

Specifications of network protocols and implementations of components running these protocols which…

296

input-output-hk/ouroboros-network

Specifications of network protocols and implementations of components running these protocols which…

296

CardanoSolutions/ogmios

❇️ A WebSocket JSON/RPC bridge for Cardano

326

coinbase/mesh-sdk-go

Mesh Client Go SDK

200

libp2p/go-libp2p

libp2p implementation in Go

6,881

coinbase/rosetta-sdk-go

Mesh Client Go SDK

200

jiayaoqijia/eth2030

Ethereum execution client targeting the 2030 roadmap. 50 packages, 18K+ tests, 58 EIPs, 100% EF…

Languages

99.8%

blinklabs-io/gouroboros

Go implementation of the Cardano Ouroboros family of protocols

1,875 commits

updated Sep 23, 2026

See the code

README

Introduction

Features

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

Examples

The examples/ directory contains self-contained example programs demonstrating how to use the library. Each example has its own Go module with a local replace back to this checkout:

Example	Protocol	Description
`block-fetch`	Node-to-Node	Fetch a specific block by slot and hash
`chain-sync`	NtC / NtN	Sync blocks from genesis or a specific era; supports rollback/rollforward
`chain-tip`	Node-to-Client	Get the current chain tip via ChainSync
`peer-sharing`	Node-to-Node	Request a list of peers from a remote node
`ping`	Node-to-Client	Measure connection and protocol handshake latency
`state-query`	Node-to-Client	Query protocol parameters and other node state
`tx-monitor`	Node-to-Client	Inspect the node mempool contents
`tx-submission`	Node-to-Client	Submit a signed transaction to the node

Build all examples:

make build

Run an example directly (e.g. check the current chain tip over a local socket):

go -C examples/chain-tip run .

See the inline comments in each main.go and the environment variables each command accepts for full usage details.

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

Running the linter

gOuroboros uses golangci-lint for code quality checks. Install it following the official installation guide, then run:

make lint

Manual testing

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.

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

CARDANO_NODE_ADDRESS=backbone.cardano.iog.io:3001 CARDANO_NODE_NETWORK=mainnet ./chain-sync -bulk -start-era shelley

Dump details of a particular block

BLOCK_FETCH_SLOT=120521627 BLOCK_FETCH_HASH=afd4c97e32003d9803a305011cbd8796e6b36bf61576567206887e35795b6e09 ./block-fetch

blockchain

cardano

golang

golang-library

library

network

ouroboros

ouroboros-network

protocol

Similar repos

blinklabs-io/dingo

Cardano Blockchain Node

same org

IntersectMBO/ouroboros-network

Specifications of network protocols and implementations of components running these protocols which…

296

input-output-hk/ouroboros-network

Specifications of network protocols and implementations of components running these protocols which…

296

CardanoSolutions/ogmios

❇️ A WebSocket JSON/RPC bridge for Cardano

326

coinbase/mesh-sdk-go

Mesh Client Go SDK

200

libp2p/go-libp2p

libp2p implementation in Go

6,881

coinbase/rosetta-sdk-go

Mesh Client Go SDK

200

jiayaoqijia/eth2030

Ethereum execution client targeting the 2030 roadmap. 50 packages, 18K+ tests, 58 EIPs, 100% EF…

Contributors

744 commits

699 commits

159 commits

57 commits

Languages

99.8%