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
      • 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
    • Total collateral
    • Reference inputs
    • Voting procedures
    • Proposal procedures
    • Current treasury value
    • Donation
• 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

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

Manual testing

Various small test programs can be found in cmd/ in this repo or 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.

Start by building the test programs:

make

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

./gouroboros -address backbone.cardano-mainnet.iohk.io:3001 -network mainnet -ntn 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