How smartcontractkit/chainlink works
1. Repository shape and runtime boundaries
- This is a multi-module Go monorepo centered on the Chainlink node.
- The main runtime lives under core/; supporting modules are core/scripts and integration-tests, with a separate deployment/ tree for onchain/offchain provisioning.
- The node is a long-running service backed by Postgres, configured by TOML + environment variables, and packaged for Docker.
2. Node bootstrap and service composition
- core/main.go starts the application; core/services/chainlink is the main orchestration layer that assembles configuration, database access, keystores, relayers, web server, telemetry, and background services.
- core/services/service.go, multi.go, nurse.go, and related packages show that the node is composed as many independently started/stopped services rather than a single monolith.
- Shutdown and recovery are explicit concerns (core/shutdown, core/recovery).
3. Primary control plane: Web API, UI, and CLI
- core/web exposes the HTTP API, GraphQL resolvers, controllers, auth, middleware, and the embedded operator UI assets.
- core/cmd implements the CLI used for local and remote node administration; it talks to the same backend exposed by the web/API layer.
- This is the operator-facing control plane for creating jobs, managing keys, viewing chains/logs/txs, and configuring node state.
4. Persistence and schema management
- core/store owns the database schema, migrations, fixtures, and low-level store models.
- Most operational state is persisted here: jobs, runs, keys, chains, transactions, logs, OCR state, workflow specs, telemetry-related tables, and many capability-specific records.
- The architecture assumes Postgres as the durable system of record; many services have ORM-style layers under core/services/*/orm.go.
5. Job execution pipeline
- core/services/pipeline is the general-purpose execution engine for task graphs: fetching inputs, evaluating tasks, scheduling runs, and producing outputs.
- It includes task implementations for HTTP, JSON/CBOR parsing, crypto/encoding helpers, ETH calls/txs, math, and workflow-specific plumbing.
- This layer is the main dataflow engine for traditional Chainlink jobs: external data enters here, is transformed by tasks, and may result in blockchain writes or adapter calls.
6. Chain interactions, keys, and relayers
- core/services/relay contains chain-specific relayer implementations, especially EVM, plus dummy/adapter variants.
- core/services/keystore and core/services/p2p manage signing keys, peer identity, and communication identity across protocols.
- core/services/ocr, ocr2, ocr3, vrf, functions, feeds, gateway, and related packages are specialized protocol services that sit on top of the relay/keystore foundation.
7. Capabilities and the CRE/workflow subsystem
- core/capabilities and core/services/workflows represent the newer capabilities/workflows architecture.
- Capabilities cover triggers, executable/target modules, remote execution, confidential relay, vault access, web API, streams, compute, CCIP helpers, and test fakes.
- core/services/workflows provides workflow engine, syncers, registries, artifacts, metering, sharding, secrets handling, and v2 execution paths; it is a distinct orchestration layer from the older job pipeline.
8. Gateway and remote execution path
- core/services/gateway and core/capabilities/remote implement the gateway/dispatcher side of distributed capability execution.
- These packages handle request routing, HTTP/WebSocket networking, request caching, response aggregation, and protocol handlers such as functions, vault, confidential relay, and web API capabilities.
- The data flow here is: workflow or capability requests are dispatched over the gateway/network boundary to workers or peers, then aggregated back into node state.
9. Protocol-specific subsystems
- The repo contains large protocol verticals: ocr, ocr2, ocr3, vrf, ccip, llo, s4, ring, cron, blockhashstore, blockheaderfeeder, registrysyncer, feeds, functions, vault, standardcapabilities, and shardorchestrator.
- Each vertical usually includes delegates, validation, onchain readers/transmitters, telemetry, and tests.
- For architecture diagrams, these are best drawn as specialized services fed by the shared runtime, keystore, pipeline/workflow engine, and Postgres.
10. Telemetry, monitoring, and observability
- core/services/telemetry, core/services/synchronization, core/services/headreporter, core/logger, and related packages centralize metrics/logging/tracing/ingress.
- The repo also includes protobuf-based telemetry schemas and ingestion clients, indicating explicit outbound telemetry streams in addition to logs and Prometheus-style metrics.
- Observability is a first-class boundary: many services emit metrics, and some protocols batch and forward structured telemetry to external systems.
11. Deployment and contract orchestration
- deployment/ is a separate tooling and orchestration layer for provisioning contracts, jobs, registries, forwarders, and chain environments.
- It covers CCIP, CRE, data feeds, vault, tokens, Keystone, and environment setup, with “changesets,” “operations,” “sequences,” and “views” around onchain state transitions.
- This code does not run as the node runtime; it coordinates external blockchain state and node/job configuration.
12. Scripts, test harnesses, and environment simulation
- core/scripts, integration-tests, and system-tests contain operator tooling, testnet harnesses, Docker/Kubernetes fixtures, smoke/regression/load tests, and environment builders.
- These modules simulate or manage the external dependencies the node talks to: blockchains, gateways, mock services, job distributor, and test containers.
- tools/ and plugins/ support local development, release tooling, plugin installation, and test automation.
13. External dependencies and integration surfaces
- The node integrates with Postgres, blockchain nodes (especially EVM, but also Solana, Aptos, Sui, Tron, Starknet, Cosmos, TON), external adapters, gateways, and telemetry sinks.
- Docker images and CI workflows indicate the repo is built and validated as a deployable node binary plus optional plugin image.
- For an architecture diagram, the main external edges are: blockchain RPC/WebSocket endpoints, Postgres, operator browser/CLI, external adapters/services, and telemetry backends.
14. Suggested high-level diagram framing
- Center the diagram on the Chainlink node runtime.
- Around it, show: control plane (web UI/API/CLI), execution plane (pipeline/workflows/capabilities), chain-facing services (relayers/keystores/OCR/VRF/CCIP/etc.), persistence (Postgres/store), and observability.
- Put deployment/, integration-tests/, system-tests/, and core/scripts/ outside the runtime as orchestration and validation layers rather than live runtime components.
Main entry points: chainlink Chainlink app · capabilities Capabilities · web Web API · keystore Keystore
Components 21
Node Runtime
Live Chainlink node process and core subsystems.
- Main · Starts the Chainlink node binary.
core/main.go - Chainlink app · Assembles config, database, keys, relayers, web server, telemetry, and services.
core/services/chainlink - Service graph · Lifecycle orchestration for independently started/stopped services.
core/services/service.go - Shutdown · Explicit shutdown coordination.
core/shutdown - Recovery · Crash/recovery handling and restart safety.
core/recovery - Pipeline · Traditional job execution engine for task graphs and run scheduling.
core/services/pipeline - Telemetry · Metrics, tracing, telemetry ingress, head reporting, and observability streams.
core/services/telemetry
Protocol Services
Specialized chain-facing services and protocol verticals.
- Relayers · Chain-specific relayer implementations and write/read transport abstractions.
core/services/relay - Keystore · Chain, OCR, P2P, VRF, and workflow signing identity management.
core/services/keystore - OCR stack · OCR, OCR2, OCR3, bootstrap, and protocol plugin implementations.
core/services/ocr2 - VRF · VRF listeners, proof generation, and protocol-specific state.
core/services/vrf
Capabilities & Workflows
CRE/workflow execution and remote capability paths.
- Gateway · Request routing, network handlers, caching, and response aggregation for remote execution.
core/services/gateway - Capabilities · Capability registry, triggers, executables, targets, and protocol adapters.
core/capabilities - Workflows · Workflow engine, syncers, artifacts, metering, sharding, and v2 execution paths.
core/services/workflows
Control Plane
Operator UI, API, and CLI surfaces.
Persistence & Config
Database, schema, config, and store layers.
Ops & Validation
Deployment, scripts, and test harnesses.
- Deployment · Onchain/offchain provisioning, changesets, and environment orchestration.
deployment - Tests · Integration, system, smoke, load, and environment simulation tooling.
integration-tests
Other components
- Postgres · Durable system of record for jobs, runs, keys, chains, transactions, and workflow state.
Connections 33
- Main → Chainlink app: boots · Entrypoint starts the node application.
- Chainlink app → Service graph: assembles · Builds the runtime from many independently managed services.
- Chainlink app → Config: loads · Reads TOML and environment-based configuration.
- Chainlink app → Store: uses · Initializes schema, migrations, and data access.
- Chainlink app → Web API: serves · Exposes operator HTTP and GraphQL control plane.
- Chainlink app → Pipeline: runs · Executes traditional job pipelines.
- Chainlink app → Relayers: connects · Creates chain relayers and transport adapters.
- Chainlink app → Keystore: signs with · Uses signing keys and node identity services.
- Chainlink app → OCR stack: hosts · Starts OCR-family protocol services and plugins.
- Chainlink app → VRF: hosts · Starts VRF protocol services.
- Chainlink app → Gateway: hosts · Runs gateway/dispatcher services for remote capabilities.
- Chainlink app → Capabilities: loads · Registers capability implementations and adapters.
- Chainlink app → Workflows: runs · Manages workflow engine and sync paths.
- Chainlink app → Telemetry: emits · Publishes metrics, traces, and telemetry.
- Chainlink app → Shutdown: stops via · Coordinates graceful shutdown.
- Chainlink app → Recovery: recovers via · Applies recovery and restart safety.
- Web API → CLI: shared backend · CLI and web API operate on the same node backend.
- Web API → Store: reads/writes · Operator actions are persisted in the store.
- CLI → Web API: calls · CLI drives the node through the operator API.
- Pipeline → Postgres: persists · Job runs and task state are stored in Postgres.
- Store → Postgres: backed by · Persistent system of record is Postgres.
- Workflows → Postgres: persists · Workflow specs, artifacts, secrets, and execution state are stored.
- Gateway → Capabilities: dispatches · Routes remote capability requests to executors and handlers.
- Gateway → Workflows: feeds · Workflow or capability requests originate from workflow runtime.
- OCR stack → Relayers: uses · OCR protocol execution depends on relayers for chain interaction.
- OCR stack → Keystore: signs with · OCR uses protocol keys and peer identity.
- VRF → Keystore: signs with · VRF uses dedicated signing material.
- Capabilities → Keystore: authenticates · Capabilities rely on node identity and signing keys.
- Capabilities → Relayers: targets chains · Some capabilities write to or read from blockchains.
- Telemetry → Postgres: samples from · Observability and ingestion can reference persisted state.
- Deployment → Chainlink app: provisions · Deployment orchestrates node configuration and jobs.
- Tests → Chainlink app: validates · Integration and system tests exercise the live node runtime.
- Tests → Deployment: simulates · Test harnesses model chain and environment setup.