chainlink-protos

Note

This demo represents an educational example to use a Chainlink system, product, or service and is provided to demonstrate how to interact with Chainlink’s systems, products, and services to integrate them into your own. This template is provided “AS IS” and “AS AVAILABLE” without warranties of any kind, it has not been audited, and it may be missing key checks or error handling to make the usage of the system, product or service more clear. Do not use the code in this example in a production environment without completing your own audits and application of best practices. Neither Chainlink Labs, the Chainlink Foundation, nor Chainlink node operators are responsible for unintended outputs that are generated due to errors in code.

This repository serves as a central hub for shared protobuf definitions used across various services. Currently, it includes protobuf definitions and generated Go SDKs for the job-distributor and orchestrator services. Contributions and additional proto files for other services are welcome.

Why use Chainlink Protos?

• No More Copy-Pasting Code: Centralized proto definitions eliminate the need to copy-paste code across different repositories.
• Publicly Accessible Repository: No need for tokens, credentials, or GOPRIVATE settings.
• Proto Breaking Changes Validation with Buf: Ensures backward compatibility and consistent formatting.
• Automated Golang SDK Generation: GitHub workflows keep the generated code up-to-date.
• Independent Versioning in a Monorepo: Each package is versioned separately for better control and integration.

Usage

Go applications can import only the necessary SDKs.

$ go get github.com/smartcontractkit/chainlink-protos/job-distributor@v<LATEST_VERSION>
$ go get github.com/smartcontractkit/chainlink-protos/orchestrator@v<LATEST_VERSION>

Getting Started

Dependencies

Dependencies are managed via asdf.

./scripts/setup-asdf-plugin.sh
asdf install

Installing wsRPC

Communication between core node and job distributor requires the library wsRPC. To generate protos that are compatible with wsRPC, we will need to install the CLI.

Follow the instructions here to install it.

Formatting

Ensure buf is installed following the dependencies above.

task fmt

Generating GO SDKs

Note

Commiting the generated code resulting from the proto changes is optional. The CI will automatically update the pull request with the generated files through the GitHub workflow.

Generate the GO SDKs to implement gRPC services or clients via task

$ task proto:all
$ task proto:gen:job-distributor # only run for job-distributor
$ task proto:gen:orchestrator: # only run for orchestrator

Contributing

Filing a PR

Before creating a PR with your change, you should generate a "changeset" file.

Let's assume that you've made some local changes in one of the protos. Before filing a PR you need to generate a "changeset" description required for the automated release process. Follow the steps below:

• Run pnpm changset in the git top level directory.
• This repo contains multiple packages, so it will ask you for which package it should generate changeset update.
• Answer remaining questions. At the end, you will have a new .changeset/<random-name>.md file generated.
• Now you need to commit and push your changes
• Create a Pull request which includes your code change and generated "changeset" file.

Preparing a release

After merging your PR, a changesets CI job will create or update a "Version Packages" PR which contains a release bump.

Merging Version Packages PR

Now you can Approve/Request approval and Merge the PR from the previous step. After merging, it will kick off the push-main.yml workflow and that will release a new versions and push tags automatically. You can navigate to the tags view, to check if the latest tag is available.