Project Configuration

This page explains how to manage configuration within Chainlink Runtime Environment (CRE) projects. It covers the standard project structure, the roles and usage of the configuration files (project.yaml and workflow.yaml), and the concept of targets for handling environment-specific settings.

You will understand:

• The recommended directory structure for CRE projects and the significance of key files.
• How to define global settings in project.yaml and override them with workflow-specific settings in workflow.yaml.
• The purpose of targets and how they enable seamless switching between different operational environments.
• The process by which the CRE CLI resolves and merges target configurations.

1. Glossary

2. Project structure

A typical CRE TypeScript project is organized as follows:

myProject/
├── .env                    # Secret values (never commit to a Version Control System like Git)
├── .gitignore
├── project.yaml            # Global configuration
├── secrets.yaml            # Secret name declarations
├── contracts/              # Contract-related files
│   └── abi/                # TypeScript ABI definitions (.ts files)
│       ├── MessageEmitter.ts
│       ├── index.ts
│       └── …
├── workflow1/
│   ├── package.json        # NPM dependencies for this workflow
│   ├── tsconfig.json       # TypeScript configuration
│   ├── bun.lock            # Dependency lock file
│   ├── node_modules/       # Installed dependencies
│   ├── workflow.yaml       # Workflow-specific configuration (optional)
│   ├── main.ts             # Your workflow code
│   └── …
├── workflow2/
│   ├── package.json        # NPM dependencies for this workflow
│   ├── tsconfig.json       # TypeScript configuration
│   ├── bun.lock            # Dependency lock file
│   ├── node_modules/       # Installed dependencies
│   ├── workflow.yaml       # Workflow-specific configuration (optional)
│   ├── main.ts             # Your workflow code
│   └── …
└── …

• project.yaml: Global settings, shared by every workflow in the project.
• workflow.yaml: Local settings for a single workflow. Add this file only when the workflow needs overrides.
• secrets.yaml: Secret declarations, a manifest of logical secret names used across the project.
• contracts/abi/: TypeScript ABI definitions, where you place .ts files that export contract ABIs using viem's type system. Unlike Go, TypeScript doesn't require generating bindings—ABIs are used directly with viem.
• package.json / tsconfig.json: Workflow-specific dependencies and TypeScript configuration. Each workflow manages its own dependencies independently.
• node_modules/: Installed dependencies for the workflow (generated by npm install or similar).

3. Configuration files

3.1. Global configuration (project.yaml)

project.yaml holds everything that rarely changes across workflows, such as RPC endpoints.

# project.yaml
staging-settings:
  rpcs:
    - chain-name: ethereum-testnet-sepolia
      url: https://ethereum-sepolia-rpc.publicnode.com

# You can define other targets for future use
production-settings:
  account:
    workflow-owner-address: "0x..." # Optional: For multi-sig wallets
  rpcs:
    - chain-name: ethereum-testnet-sepolia
      url: https://ethereum-sepolia-rpc.publicnode.com
    - chain-name: ethereum-mainnet
      url: https://mainnet.infura.io/v3/<YOUR-PROJECT-ID>

Configuration fields

3.2. Workflow configuration (workflow.yaml)

workflow.yaml captures details unique to one workflow instance, like its name and entry point file.

# workflow.yaml
staging-settings:
  user-workflow:
    workflow-name: "my-por-workflow-staging"
  workflow-artifacts:
    workflow-path: "./main.ts" # Points to the TypeScript entry file
    config-path: "./config.staging.json"
    secrets-path: "" # Empty if not using secrets

production-settings:
  user-workflow:
    workflow-owner-address: "<address>" # Optional: For multi-sig wallets
    workflow-name: "my-por-workflow-production"
  workflow-artifacts:
    workflow-path: "./main.ts" # Points to the TypeScript entry file
    config-path: "./config.production.json"
    secrets-path: "" # e.g. "../secrets.yaml" if using secrets

Configuration fields

3.3. Secrets configuration (secrets.yaml)

secrets.yaml is an optional project-level file that maps logical secret names to environment variables. This allows you to decouple the secret names used in your code from the actual environment variable names.

# secrets.yaml (at project root)
secretsNames:
  DATA_SOURCE_API_KEY:
    - DATA_SOURCE_API_KEY_ENV

To use secrets in your workflow, reference this file in your workflow.yaml:

workflow-artifacts:
  secrets-path: "../secrets.yaml"

For simulation, secret values are loaded from your .env file or environment variables. For deployed workflows, secrets are managed through the Vault DON using cre secrets commands.

For complete details on using secrets in your workflows, see Secrets Management.

4. Targets

A target is a top-level key inside both project.yaml and workflow.yaml. It bundles all settings for a single environment or variant.

The CLI selects the active target using the --target flag. Example:

# Simulate using the 'staging-settings' target
cre workflow simulate my-workflow --target staging-settings

Alternatively, the CRE_TARGET environment variable can be used to specify the target. The CLI picks the active target in this order:

1. --target <name> flag
2. CRE_TARGET=<name> environment variable

4.1. Defining Multiple Targets

You can store many targets in one file. This is useful for managing different environments (like simulation vs. production) or for testing variations of a workflow.

# In project.yaml

# Target for simulation and testing
staging-settings:
  rpcs:
    - chain-name: ethereum-testnet-sepolia
      url: https://ethereum-sepolia-rpc.publicnode.com

# Target for production deployment
production-settings:
  account:
    workflow-owner-address: "0x123..." # Optional: For multi-sig wallets
  rpcs:
    - chain-name: ethereum-mainnet
      url: https://mainnet.infura.io/v3/<YOUR-PROJECT-ID>

4.2. How Target Resolution Works

When you run a CLI command with a target, e.g., --target staging-settings:

1. Load the staging-settings target from project.yaml.
2. Load the same target from workflow.yaml (if the file exists and contains a matching target definition).
3. Merge the two objects.
   • Keys present in both files → value from workflow.yaml wins.
   • Keys present in only one file → that value is used.
4. Validate the final object before execution.