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
    • Allegra
      • Blocks
      • Transactions
      • TX inputs
      • TX outputs
    • Mary
      • Blocks
      • Transactions
      • TX inputs
      • TX outputs
    • Alonzo
      • Blocks
      • Transactions
      • TX inputs
      • TX outputs
    • Babbage
      • Blocks
      • Transactions
      • TX inputs
      • TX outputs
    • Conway
      • Blocks
      • Transactions
      • TX inputs
      • TX outputs
  • 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
• 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

Testing is currently a mostly manual process. There's an included test program that use the library and a Docker Compose file to launch a local cardano-node instance.

Starting the local cardano-node instance

$ docker-compose up -d

If you want to use mainnet, set the CARDANO_NETWORK environment variable.

$ export CARDANO_NETWORK=mainnet
$ docker-compose up -d

You can communicate with the cardano-node instance on port 8081 (for "public" node-to-node protocol), port 8082 (for "private" node-to-client protocol), or the ./tmp/cardano-node/ipc/node.socket UNIX socket file (also for "private" node-to-client protocol).

NOTE: if using the UNIX socket file, you may need to adjust the permissions/ownership to allow your user to access it. The cardano-node Docker image runs as root by default and the UNIX socket ends up with root:root ownership and 0755 permissions, which doesn't allow a non-root use to write to it by default.

Running cardano-cli against local cardano-node instance

$ docker exec -ti gouroboros-cardano-node-1 sh -c 'CARDANO_NODE_SOCKET_PATH=/ipc/node.socket cardano-cli query tip --testnet-magic 1097911063'

Building and running the test program

Compile the test program.

$ make

Run the test program pointing to the UNIX socket (via socat) from the cardano-node instance started above.

$ ./gouroboros -address localhost:8082 -network testnet ...

Run it against the public port in node-to-node mode.

$ ./gouroboros -address localhost:8081 -ntn -network testnet ...

Test chain-sync (works in node-to-node and node-to-client modes).

$ ./gouroboros ... chain-sync -start-era byron

Test local-tx-submission (only works in node-to-client mode).

$ ./gouroboros ... local-tx-submission ...

Test following the chain tip in the preview network.

$ ./gouroboros -network preview -address preview-node.world.dev.cardano.org:30002 -ntn chain-sync -tip

Stopping the local cardano-node instance

$ docker-compose down --volumes