Telchar: Plutus Blacksmith

The Problem

Interacting with Plutus validators requires understanding of their interface. The process often involves writing a significant amount of boilerplate code, which can be tedious and error-prone.

In the world of web2, we see a similar problem with APIs. To interact with a given protocol, developers need to know the interfaces of the APIs in advance. Building these client libraries manually can be a laborious and error-prone process, hence the emergence of tools such as OpenAPI and AsyncAPI. These technologies allow developers to generate client libraries from a specification file, significantly reducing the possibility of errors and the amount of manual work required.

About Plutus Blueprints (CIP-57)

A Plutus contract has a binary interface, primarily defined by its datum and redeemer. Without the source-code for the validator, these data structures are opaque: you can somehow inspect the structures by doing some reverse-engineering of on-chain activity, but the full semantic context of each field is missing.

To fix this, Cardano CIP-57 specifies a language for documenting Plutus contracts in a machine-readable manner, akin to what OpenAPI does for HTTP services. Each validator can now be accompanied by a json file (referred to as "Blueprint") that provides a comprehensive description of datums and redeemer structures, providing the missing semantic context.

Furthermore, this definition is agnostic of the actual source-code for the validator. It doesn't matter which language was used to develop the contract (Aiken, PlutusTx, etc), the blueprint file will still apply.

Here's an example of a fragment of a very simple Blueprint file describing the "hello world" contract that can be found as an example in the CIP:

{
  "title": "hello_world",
  "datum": {
    "title": "Datum",
    "purpose": "spend",
    "schema": {
      "anyOf": [
        {
          "title": "Datum",
          "dataType": "constructor",
          "index": 0,
          "fields": [
            {
              "title": "owner",
              "dataType": "bytes"
            }
          ]
        }
      ]
    }
  },
  "redeemer": {
    "title": "Redeemer",
    "schema": {
      "anyOf": [
        {
          "title": "Redeemer",
          "dataType": "constructor",
          "index": 0,
          "fields": [
            {
              "title": "msg",
              "dataType": "bytes"
            }
          ]
        }
      ]
    }
  },
  "compiledCode": "58ad010000323...65734ae855d11",
  "hash": "5e1e8fa84f2b557ddc362329413caa3fd89a1be26bfd24be05ce0a02"
}        

Enter Telchar

Telchar is a toolchain designed to improve the developer experience when integrating Plutus validators into off-chain processes. Leveraging the information provided in blueprint files, Telchar aims to enhance two areas: discovery and code generation.

Discovery: we want to make it simple for developers to search and find blueprint definitions for protocols that were authored by third parties. We'll build a public registry where contract authors can publish their blueprint files for any other team to read and integrate.

Codegen: we want to remove as much boilerplate from the process of having to build transactions for known protocols where there're blueprint files available. We'll use codegen (code generation) templates to turn a blueprint into "typings" for popular transaction builder libraries in the ecosystem.

Blueprint Registry

The first step is to build a public registry. Imagine something akin to NPM (Node Package Manager) or PyPi (Python Package Index), but designed for Plutus blueprints. A registry of script interface definitions that can be searched and consumed to simplify interactions with on-chain scripts.

In more detail, developers can use the registry to:

• blueprint publishing: Authors of on-chain validators can publish their blueprint files, making them easily discoverable to others.
• blueprint search: Protocol integrators can search for and retrieve existing blueprint files and interface definition data, either programmatically or manually.
• parametrize scripts: Scripts that depend on parameters will be supported, allowing integrators to customize them for specific use cases.
• known parameterizations: Developers can post known parameterizations, which will be linked to their source blueprint. This will allow a direct match to on-chain transactions.
• reference scripts: The registry will enable developers to track on-chain UTxOs that hold scripts for particular blueprints. These can be used as reference scripts in their own transactions.
• source code link: Developers will have metadata fields available to link additional information to the blueprint, such as the location of the source code (if relevant).
• public registry: A hosted version of the registry will be publicly available and offered as the default instance, but the use of it is not mandatory.
• private registry: Teams can run their own independent version of the registry for private workflows or to avoid dependencies on external services.

Telchar CLI

The next in our ideal flow for developers is to provide a CLI they can install locally. This CLI will allow them to download a specific blueprint spec and use it as source for the codegen process.

Developers will be able to run "telchar codegen blueprint.json" from their command line. This will output code files containing the type definitions for the datums / redeemers defined in the blueprint. Devs can choose from a list of templates, each one targeting one of the popular transaction builder libraries in the ecosystem.

The complete list of features for the Telchar CLI is the following:

• publish command: A CLI command to upload blueprint files from the local development environment onto the registry.
• codegen: A CLI command to automatically generate code for type declarations from blueprint files. This can be used in libraries such as Lucid, MeshSDK, PyCardano, Plu-Ts, Pallas, and potentially other transaction builders in the ecosystem.
• plutus data builder: An interactive CLI command will be available for developers to build Plutus data payloads that match the blueprint specification. This can be used for testing or transaction building.
• deploy reference script: A CLI command to deploy fully-defined scripts as on-chain UTxOs. These can then be used as reference scripts by other transactions (Plutus v2).
• github actions: The CLI will be available as a Github Action, allowing developers to use the tools as part of their continuous integration pipelines.

Long-term Goals

The Telchar Registry & CLI are the first components of what we hope will become a fully-fledged dev environment for Plutus, akin to what Hardhat is to Ethereum.

This is an ambitious project and something we're tackling step-by-step. Development of the Telchar registry and CLI components is part of our Catalyst Fund 12 proposal.

Watch our Github account to keep track of development progress: https://github.com/txpipe