https://github.com/blinklabs-io/gouroboros-starter-kit
A Demeter starter kit that shows how to interact with a Cardano Node using Go
https://github.com/blinklabs-io/gouroboros-starter-kit
blockchain cardano go golang
Last synced: 5 months ago
JSON representation
A Demeter starter kit that shows how to interact with a Cardano Node using Go
- Host: GitHub
- URL: https://github.com/blinklabs-io/gouroboros-starter-kit
- Owner: blinklabs-io
- License: apache-2.0
- Created: 2023-10-12T17:34:52.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-29T11:43:54.000Z (11 months ago)
- Last Synced: 2024-10-29T13:26:33.268Z (11 months ago)
- Topics: blockchain, cardano, go, golang
- Language: Go
- Homepage:
- Size: 119 KB
- Stars: 8
- Watchers: 1
- Forks: 1
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# gOuroboros starter kit
This starter kit is an introduction tutorial on how to use the
[gOuroboros](https://github.com/blinklabs-io/gouroboros) library to communicate
with a Cardano Node using the Ouroboros family of protocols.
The gOuroboros library is a Cardano library written in [Go](https://go.dev). It
allows for communications with a Cardano Node and performing serialization of
Cardano primitives without relying on external tools and binaries, facilitating
the creation of single binary tools with minimal overhead.
## Dev Environment
For running this starter kit you'll need access to a fully synced instance of a
Cardano Node.
If you do not want to install the required components yourself, you can use the
[Demeter.run](https://demeter.run) platform to create a cloud environment with
access to common Cardano infrastructure. The following command will open this
repo in a private, web-based VSCode IDE with access to a shared Cardano Node.
[](https://demeter.run/code?repository=https://github.com/blinklabs-io/gouroboros-starter-kit.git&template=golang)
### Cardano Node Access
Since you're running this starter kit from a _Cardano Workspace_, you already
have access to the required infrastructure, such as the Cardano Node.
The network to which you're connected (mainnet, preview, preprod, etc) is
defined by your project's configuration, selected at the moment of creating
your environment.
To simplify the overall process, _Cardano Workspaces_ come already configured
with specific environmental variables that allows you to connect to the node
without extra step. These are the variables relevant for this particular
tutorial:
- `CARDANO_NODE_SOCKET_PATH`: provides the location of the unix socket within
the workspace where the cardano node is listening.
- `CARDANO_NODE_MAGIC`: the network magic corresponding to the node that is
connected to the workspace.
## What is Included
This starter kit demonstrates communication with a Cardano Node using either
the Node-to-Client or Node-to-Node operation modes of the Ouroboros network
protocol and provides examples of multiple Ouroboros mini-protocols.
- BlockFetch
- ChainSync
- LocalTxMonitor
- PeerSharing
### BlockFetch
The BlockFetch mini-protocol allows for fetching specific blocks from a remote
Cardano Node using Node-to-Node communication over the network. The code for
this example is in a single `main.go` file under `./cmd/block-fetch`.
By default, it will fetch the first block of the Babbage Era on the Cardano
mainnet from IOG's backbone servers. To change this, use the following
environment variables:
- `BLOCK_FETCH_ADDRESS`: the address:port pair of a remote Cardano Node to
retrieve block
- `BLOCK_FETCH_HASH`: the block hash to fetch
- `BLOCK_FETCH_NETWORK`: named Cardano network to use to configure network
magic automatically
- `BLOCK_FETCH_NETWORK_MAGIC`: magic number used to identify a network
- `BLOCK_FETCH_RETURN_CBOR`: return raw CBOR bytes instead of describing text
- `BLOCK_FETCH_SLOT`: the slot in which the block hash was minted
Default:
```bash
go run ./cmd/block-fetch
```
Return raw CBOR bytes:
```bash
BLOCK_FETCH_RETURN_CBOR=true go run ./cmd/block-fetch
```
### ChainSync
The ChainSync mini-protocol allows for syncronization of the blockchain from a
Cardano Node using either Node-to-Node or Node-to-Client communication. This
protocol is more complex, and is split into smaller pieces. The simplest is in
a single `main.go` file under `./cmd/chain-tip`.
For `chain-tip`, the default configuration will communicate over the local
UNIX socket mounted at `/ipc/node.socket` via Node-to-Client ChainSync.
Running the code:
```bash
go run ./cmd/chain-tip
```
### LocalTxMonitor
This starter kit demonstrates communication with a Cardano Node using the
Node-to-Client LocalTxMonitor protocol to fetch information about the Node's
mempool contents. It includes a single `main.go` which performs all of the
work, which is located under `cmd/tx-monitor`.
The default configuration will communicate over the local UNIX socket mounted
at `/ipc/node.socket` via Node-to-Client LocalTxMonitor.
```bash
go run ./cmd/tx-monitor
```
The script will output the contents of the Cardano Node's mempool, then exits.
### PeerSharing
This starter kit demonstrates communication with a Cardano Node using the
Node-to-Node PeerSharing protocol to get a list of connected and discovered
peers from the remote Node. It includes a single `main.go` which performs
all of the work, which is located under `cmd/peer-sharing`.
By default, it will fetch the 10 mainnet peers from from IOG's backbone
servers. To change this, use the following environment variables:
- `PEER_SHARING_ADDRESS`: the address:port pair of a remote Cardano Node to
retrieve block
- `PEER_SHARING_NETWORK`: named Cardano network to use to configure network
magic automatically
- `PEER_SHARING_NETWORK_MAGIC`: magic number used to identify a network
- `PEER_SHARING_PEERS`: number of peers to request, max/default 10
```bash
go run ./cmd/peer-sharing
```
The script will output 10 peer addresses from the Node, then exit.