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
        • Future 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
        • Constitution (CIP-1694)
        • Governance state (CIP-1694)
        • DRep state (CIP-1694)
        • DRep stake distribution (CIP-1694)
        • SPO stake distribution (CIP-1694)
        • Committee state (CIP-1694)
        • Filtered vote delegatees (CIP-1694)
        • Treasury (CIP-1694)
    • LeiosFetch (CIP-0164)
      • Client support
      • Server support
    • LeiosNotify (CIP-0164)
      • Client support
      • Server support
    • LocalMessageSubmission (CIP-0137 DMQ)
      • Client support
      • Server support
    • MessageSubmission (CIP-0137 DMQ)
      • Client support
      • Server support
    • LocalMessageNotification (CIP-0137 DMQ)
      • Client support
      • Server support
• 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 (CIP-0040)
    • Total collateral (CIP-0040)
    • Reference inputs (CIP-0031)
    • Voting procedures (CIP-1694)
    • Proposal procedures (CIP-1694)
    • Current treasury value (CIP-1694)
    • Donation (CIP-1694)
• Block Validation
  • Block body hash validation
  • VRF proof verification
  • KES signature verification
  • Transaction validation (UTxO rules)
  • Stake pool verification
  • Native script evaluation
  • Plutus script validation (via plutigo)
  • Structured error handling (ValidationError)
  • Byron era validation (OBFT consensus, proxy signatures, body proof)
• Cryptography
  • KES (Key-Evolving Signatures)
    • Signature verification
    • Key generation
    • Key evolution
  • VRF (Verifiable Random Function)
    • Proof generation
    • Proof verification
    • Leader election input construction
• Consensus
  • Leader election
  • Block construction
  • Chain selection
  • Threshold calculation
  • Genesis configuration
  • Byron consensus (OBFT header validation)
• Testing
  • Test framework for mocking Ouroboros conversations
  • Conformance tests (2200+ passing)
    • Ledger rules (314 tests via Amaru vectors)
    • VRF cryptography (29 vectors + 15 unit tests)
    • KES cryptography (14 tests via input-output-hk/kes vectors)
    • Consensus (212 tests for leader election, threshold, selection)
    • Byron blocks (15 tests from mainnet/testnet/conformance)
  • Fuzz testing (75 targets with nightly CI)
  • CBOR deserialization and serialization
    • Protocol messages
    • Ledger
      • Block parsing
      • Transaction parsing
• Misc
  • Address handling (CIP-0019)
    • Decode from bech32 (CIP-0005)
    • Encode as bech32 (CIP-0005)
    • 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

Running the linter

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

make lint

Manual testing

Various small test programs can be found 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.

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