UTxO RPC

UTxO RPC is a collaborative project from TxPipe and Blink Labs that was funded in Project Catalyst Fund 11. You can read the proposals here:

This week at Cardano Go Live Coding, we took our first look at what these projects will mean for the Cardano developer community. UTxO RPC is about a lot more than Go Development. It provides a common specificiation for how Go, Rust, Python, and JavaScript developers can build applications Cardano. This week's session was a great place for any developer to understand how.

In case you missed it, here's a link to the video on YouTube.

This Week at Cardano Go Live Coding

In our first two sessions, we gave some general structure to how we can work together during these weekly sessions.

This week, our Miro board went from looking like this:

To looking like this:

To start the session, I asked two questions:

For the needs of Andamio, what might we build into Andamio CLI?
For the purposes of learning and experimenting, what can we just play with?

Chris had a great answer to the second question: a lot of what we might want to do maps to emerging, exciting work going on with UTxO RPC.

🎉 Now the fun starts! 🎉

Three ways to "query tip"

To understand why developers are going to love UTxO RPC, let's look at an example together. Suppose that we want to write a Go function that gets the most recent block on a blockchain. There are a few ways to do it.

#1: With an API

A simple approach would be to make a request to a Cardano API provider like Blockfrost, and wrap it in some Go boilerplate:

1...
2
3func queryTip() {
4  url := "https://cardano-preprod.blockfrost.io/api/v0/blocks/latest"
5
6  req, err := http.NewRequest("GET", url, nil)
7  if err != nil {
8    fmt.Println("Error creating request:", err)
9    return
10  }
11
12  req.Header.Set("project_id", "your project id")
13
14  client := &http.Client{}
15  resp, err := client.Do(req)
16  if err != nil {
17    fmt.Println("Error on response:", err)
18    return
19  }
20  defer resp.Body.Close()
21
22  body, err := ioutil.ReadAll(resp.Body)
23  if err != nil {
24    fmt.Println("Error reading body:", err)
25    return
26  }
27
28  var block Block
29  err = json.Unmarshal(body, &block)
30  if err != nil {
31    fmt.Println("Error decoding JSON:", err)
32    return
33  }
34
35  fmt.Printf(
36    "Chain Tip:\nSlot: %-10d Block Hash: %x\n",
37    block.Slot,
38    block.Hash,
39  )
40}

This is convenient because all we need is an API endpoint, and just like that, we have the data we need! But as you can see, there's a lot of boilerplate for simply handling the JSON response from the API. What if we didn't have to retrieve and parse JSON to get the same result?

#2: With gOuroboros, as shown in Go Live Coding #001

Another way to write a queryTip function is to use lower-level tools like gOuroboros, from Blink Labs. In this example, we can see how gouroboros establishes a direct connection (in this case with a synced Cardano Node at cfg.Address), and gets the current tip of the blockchain.

What's nice about this approach is that we are not translating any data from JSON. The gOuroboros client just provides it in a format that's easy to read. On line 39, we get tip from the client. Then on lines 45 and 46 we print directly from that data.

1import (
2  ...
3  ouroboros "github.com/blinklabs-io/gouroboros"
4)
5
6...
7
8func chainTip() {
9  // Set config defaults
10  var cfg = Config{
11    Magic:   1,
12    Address: "0.0.0.0:3001",
13  }
14  // Parse environment variables
15  if err := envconfig.Process("cardano_node", &cfg); err != nil {
16    panic(err)
17  }
18  // Create error channel
19  errorChan := make(chan error)
20  // start error handler
21  go func() {
22    for {
23      err := <-errorChan
24      panic(err)
25    }
26  }()
27  // Configure Ouroboros
28  o, err := ouroboros.NewConnection(
29    ouroboros.WithNetworkMagic(uint32(cfg.Magic)),
30    ouroboros.WithErrorChan(errorChan),
31    ouroboros.WithNodeToNode(true),
32  )
33  if err != nil {
34    panic(err)
35  }
36  if err = o.Dial("tcp", cfg.Address); err != nil {
37    panic(err)
38  }
39  tip, err := o.ChainSync().Client.GetCurrentTip()
40  if err != nil {
41    panic(err)
42  }
43  fmt.Printf(
44    "Chain Tip:\nSlot: %-10d Block Hash: %x\n",
45    tip.Point.Slot,
46    tip.Point.Hash,
47  )
48  fmt.Println()
49}

See the project repo for full code

Still, there's a lot of boilerplate, this time for making the connection to our data source. What if we didn't have to include all of that, or pull in all of the gouroboros library every time we wanted to use it?

#3: With UTxO RPC

Here is what the same function might look like with UTxO RPC. It combines the convenience of using and endpoint like Blockfrost, with the native data types exposed by a native library like gOuroboros.

We simply have to grab the baseUrl (that's our data source) and create a client (just like in example #1). Then, we can run functions directly on that client. What's more, these functions will have the same names is Rust, Python, and JavaScript! Check out these docs: the specifications for each Module are the same for any supported language. This means that across programming languages, developers will be able to use the same logic to build applications.

1package main
2
3import (
4	...
5
6	"connectrpc.com/connect"
7	sync "github.com/utxorpc/go-codegen/utxorpc/v1alpha/sync"
8	utxorpc "github.com/utxorpc/go-sdk"
9)
10
11func queryTipExampleGoSDK() {
12  ctx := context.Background()
13  httpClient := &http.Client{
14    // set up your http client
15  }
16  baseUrl := "https://preview.utxorpc-v0.demeter.run"
17  client := utxorpc.NewClient(httpClient, baseUrl)
18  req := connect.NewRequest(&sync.FetchBlockRequest{})
19  // set API key for demeter
20  req.Header().Set("dmtr-api-key", "dmtr_utxorpc1...")
21  fmt.Println("connecting to utxorpc host:", baseUrl)
22  chainSync, err := client.ChainSync.FetchBlock(ctx, req)
23  if err != nil {
24    fmt.Println(connect.CodeOf(err))
25    if connectErr := new(connect.Error); errors.As(err, &connectErr) {
26      fmt.Println(connectErr.Message())
27      fmt.Println(connectErr.Details())
28    }
29    panic(err)
30    os.Exit(1)
31  }
32  fmt.Println("connected to utxorpc...")
33  for i, blockRef := range chainSync.Msg.Block {
34    fmt.Printf("Block[%d]:\n", i)
35    fmt.Printf("Index: %d\n", blockRef.GetCardano().GetHeader().GetSlot())
36    fmt.Printf("Hash: %x\n", blockRef.GetCardano().GetHeader().GetHash())
37  }
38}

Check out this example on the UTxO RPC GitHub

The Data's got to come from somewhere...

In the example above, the baseUrl is https://preview.utxorpc-v0.demeter.run. This is what TxPipe is building to deliver on the gRPC ❤️ Cardano: A streaming API for Cardano using Dolos by TxPipe project. Dolos is "a new type of Cardano node, fine-tuned to solve a very narrow scope: keeping an updated copy of the ledger and replying to queries from trusted clients, while requiring a small fraction of the resources". It creates a way to serve the data we need for UTxO RPC to work.

We'd all like to make sure that this layer is robust! To deliver on the Fund 11 proposal linked above, Blink Labs is building cardano-node-api as another way to provide the data for UTxO RPC.

At Gimbalabs, we are excited to make sure that these services are accessible. The variety of data providers coming online right now, and the variety of ways that these services can be deployed and shared gives us confidence that the Cardano application ecosystem will be build on robust, reliable, and distributed foundations.

What's Next?

At Cardano Go Live Coding, we'll continue to dive into the details of how cardano-node-api and UTxO RPC work. We'll also look at examples of how application developers can use them.
Just like we can write a queryTip function in a few different ways, we can apply similar patterns to transaction building. In the next live coding sessions, we will start to look at some examples.

About Cardano Go Live Coding

Cardano Go Live Coding meets on Mondays from 1300-1400 UTC.

Follow the project:

Notion page - public dashboard
Andamio CLI on GitHub

Register for Weekly Live Coding Sessions

Every Monday 1300-1400 UTC

If you’re just getting started

If you are a brand new to Go, check out the official tutorial. Then, take a look at Go by Example - it's a great introduction.
On YouTube: How to write beautiful Golang CLI is a helpful overview of Cobra CLI, and it illustrates the design patterns we're using with Andamio CLI
Cardano Go PBL is currently in development - we'll share more soon!

Cardano Go Live Coding Session #003