Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/blinklabs-io/gouroboros

Go implementation of the Cardano Ouroboros protocol
https://github.com/blinklabs-io/gouroboros

blockchain cardano go golang golang-library library network ouroboros ouroboros-network protocol

Last synced: 3 months ago
JSON representation

Go implementation of the Cardano Ouroboros protocol

Host: GitHub
URL: https://github.com/blinklabs-io/gouroboros
Owner: blinklabs-io
License: apache-2.0
Created: 2021-12-05T21:36:37.000Z (almost 3 years ago)
Default Branch: main
Last Pushed: 2024-05-20T21:00:06.000Z (6 months ago)
Last Synced: 2024-05-21T01:15:50.107Z (6 months ago)
Topics: blockchain, cardano, go, golang, golang-library, library, network, ouroboros, ouroboros-network, protocol
Language: Go
Homepage:
Size: 1.39 MB
Stars: 61
Watchers: 1
Forks: 10
Open Issues: 43
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: CODEOWNERS

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

        - [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

        - [ ] Pool state

        - [ ] Stake snapshots

        - [ ] Pool distribution

- [ ] 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

      - [ ] 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

    - [X] Total collateral

    - [X] Reference inputs

    - [X] Voting procedures

    - [X] Proposal procedures

    - [X] Current treasury value

    - [X] Donation

- [ ] Testing

  - [X] Test framework for mocking Ouroboros conversations

  - [ ] CBOR deserialization and serialization

    - [X] Protocol messages

    - [ ] Ledger

      - [ ] Block parsing

      - [ ] Transaction parsing

- [ ] Misc

  - [X] Address handling

    - [X] Decode from bech32

    - [X] Encode as bech32

    - [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

```

### Manual testing

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

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

```