https://github.com/blinklabs-io/gouroboros
Go implementation of the Cardano Ouroboros family of protocols
https://github.com/blinklabs-io/gouroboros
blockchain cardano go golang golang-library library network ouroboros ouroboros-network protocol
Last synced: about 2 months ago
JSON representation
Go implementation of the Cardano Ouroboros family of protocols
- Host: GitHub
- URL: https://github.com/blinklabs-io/gouroboros
- Owner: blinklabs-io
- License: apache-2.0
- Created: 2021-12-05T21:36:37.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2026-01-23T19:57:44.000Z (5 months ago)
- Last Synced: 2026-01-24T04:50:21.128Z (5 months ago)
- Topics: blockchain, cardano, go, golang, golang-library, library, network, ouroboros, ouroboros-network, protocol
- Language: Go
- Homepage:
- Size: 4.7 MB
- Stars: 77
- Watchers: 2
- Forks: 26
- Open Issues: 24
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Agents: AGENTS.md
Awesome Lists containing this project
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.
- [ ] Ouroboros support
- [ ] Muxer
- [X] support for multiple mini-protocols over single connection
- [X] support for separate initiator and responder instance for each protocol
- [ ] support for buffer limits for each mini-protocol
- [ ] Protocols
- [X] Handshake
- [X] Client support
- [X] Server support
- [X] Keepalive
- [X] Client support
- [X] Server support
- [X] ChainSync
- [X] Client support
- [X] Server support
- [X] BlockFetch
- [X] Client support
- [X] Server support
- [X] TxSubmission
- [X] Client support
- [X] Server support
- [X] PeerSharing
- [X] Client support
- [X] Server support
- [X] LocalTxSubmission
- [X] Client support
- [X] Server support
- [X] LocalTxMonitor
- [X] Client support
- [X] Server support
- [ ] LocalStateQuery
- [X] Client support
- [X] Server support
- [ ] Queries
- [X] System start
- [X] Current era
- [X] Chain tip
- [X] Era history
- [X] Current protocol parameters
- [ ] Future protocol parameters
- [X] Stake distribution
- [ ] Non-myopic member rewards
- [ ] Proposed protocol parameter updates
- [X] UTxOs by address
- [ ] UTxO whole
- [X] UTxO by TxIn
- [ ] Debug epoch state
- [ ] Filtered delegations and reward accounts
- [X] Genesis config
- [ ] Reward provenance
- [X] Stake pools
- [X] Stake pool params
- [ ] Reward info pools
- [X] Pool state
- [X] Stake snapshots
- [X] Pool distribution
- [X] Constitution ([CIP-1694](https://cips.cardano.org/cip/CIP-1694))
- [X] Governance state ([CIP-1694](https://cips.cardano.org/cip/CIP-1694))
- [X] DRep state ([CIP-1694](https://cips.cardano.org/cip/CIP-1694))
- [X] DRep stake distribution ([CIP-1694](https://cips.cardano.org/cip/CIP-1694))
- [X] SPO stake distribution ([CIP-1694](https://cips.cardano.org/cip/CIP-1694))
- [X] Committee state ([CIP-1694](https://cips.cardano.org/cip/CIP-1694))
- [X] Filtered vote delegatees ([CIP-1694](https://cips.cardano.org/cip/CIP-1694))
- [ ] Treasury ([CIP-1694](https://cips.cardano.org/cip/CIP-1694))
- [X] LeiosFetch ([CIP-0164](https://cips.cardano.org/cip/CIP-0164))
- [X] Client support
- [X] Server support
- [X] LeiosNotify ([CIP-0164](https://cips.cardano.org/cip/CIP-0164))
- [X] Client support
- [X] Server support
- [X] LocalMessageSubmission ([CIP-0137](https://cips.cardano.org/cip/CIP-0137) DMQ)
- [X] Client support
- [X] Server support
- [X] MessageSubmission ([CIP-0137](https://cips.cardano.org/cip/CIP-0137) DMQ)
- [X] Client support
- [X] Server support
- [X] LocalMessageNotification ([CIP-0137](https://cips.cardano.org/cip/CIP-0137) DMQ)
- [X] Client support
- [X] Server support
- [ ] Ledger
- [ ] Eras
- [X] Byron
- [X] Blocks
- [X] Transactions
- [X] TX inputs
- [X] TX outputs
- [X] Shelley
- [X] Blocks
- [X] Transactions
- [X] TX inputs
- [X] TX outputs
- [X] Parameter updates
- [X] Allegra
- [X] Blocks
- [X] Transactions
- [X] TX inputs
- [X] TX outputs
- [X] Parameter updates
- [X] Mary
- [X] Blocks
- [X] Transactions
- [X] TX inputs
- [X] TX outputs
- [X] Parameter updates
- [X] Alonzo
- [X] Blocks
- [X] Transactions
- [X] TX inputs
- [X] TX outputs
- [X] Parameter updates
- [X] Babbage
- [X] Blocks
- [X] Transactions
- [X] TX inputs
- [X] TX outputs
- [X] Parameter updates
- [X] Conway
- [X] Blocks
- [X] Transactions
- [X] TX inputs
- [X] TX outputs
- [X] Parameter updates
- [X] Transaction attributes
- [X] Inputs
- [X] Outputs
- [X] Metadata
- [X] Fees
- [X] TTL
- [X] Certificates
- [X] Staking reward withdrawls
- [X] Protocol parameter updates
- [X] Auxiliary data hash
- [X] Validity interval start
- [X] Mint operations
- [X] Script data hash
- [X] Collateral inputs
- [X] Required signers
- [X] Collateral return ([CIP-0040](https://cips.cardano.org/cip/CIP-0040))
- [X] Total collateral ([CIP-0040](https://cips.cardano.org/cip/CIP-0040))
- [X] Reference inputs ([CIP-0031](https://cips.cardano.org/cip/CIP-0031))
- [X] Voting procedures ([CIP-1694](https://cips.cardano.org/cip/CIP-1694))
- [X] Proposal procedures ([CIP-1694](https://cips.cardano.org/cip/CIP-1694))
- [X] Current treasury value ([CIP-1694](https://cips.cardano.org/cip/CIP-1694))
- [X] Donation ([CIP-1694](https://cips.cardano.org/cip/CIP-1694))
- [X] Block Validation
- [X] Block body hash validation
- [X] VRF proof verification
- [X] KES signature verification
- [X] Transaction validation (UTxO rules)
- [X] Stake pool verification
- [X] Native script evaluation
- [X] Plutus script validation (via plutigo)
- [X] Structured error handling (ValidationError)
- [X] Byron era validation (OBFT consensus, proxy signatures, body proof)
- [X] Cryptography
- [X] KES (Key-Evolving Signatures)
- [X] Signature verification
- [X] Key generation
- [X] Key evolution
- [X] VRF (Verifiable Random Function)
- [X] Proof generation
- [X] Proof verification
- [X] Leader election input construction
- [ ] Consensus
- [X] Leader election
- [X] Block construction
- [X] Chain selection
- [X] Threshold calculation
- [X] Genesis configuration
- [X] Byron consensus (OBFT header validation)
- [X] Testing
- [X] Test framework for mocking Ouroboros conversations
- [X] Conformance tests (2200+ passing)
- [X] Ledger rules (314 tests via Amaru vectors)
- [X] VRF cryptography (29 vectors + 15 unit tests)
- [X] KES cryptography (14 tests via input-output-hk/kes vectors)
- [X] Consensus (212 tests for leader election, threshold, selection)
- [X] Byron blocks (15 tests from mainnet/testnet/conformance)
- [X] Fuzz testing (75 targets with nightly CI)
- [X] CBOR deserialization and serialization
- [X] Protocol messages
- [X] Ledger
- [X] Block parsing
- [X] Transaction parsing
- [ ] Misc
- [X] Address handling ([CIP-0019](https://cips.cardano.org/cip/CIP-0019))
- [X] Decode from bech32 ([CIP-0005](https://cips.cardano.org/cip/CIP-0005))
- [X] Encode as bech32 ([CIP-0005](https://cips.cardano.org/cip/CIP-0005))
- [X] Deserialize from CBOR
- [X] 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
```
### Running the linter
gOuroboros uses [golangci-lint](https://golangci-lint.run/) for code quality checks. Install it following the
[official installation guide](https://golangci-lint.run/docs/welcome/install/local/), then run:
```
make lint
```
### Manual testing
Various small test programs can be found in the [gOuroboros Starter Kit](https://github.com/blinklabs-io/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.
You can use the `chain-sync` program from `gouroboros-starter-kit` to start a ChainSync from a public node.
Run the chain-sync test program 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` 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
```