diff --git a/src/content/cre-templates/ai-audit-firewall.mdx b/src/content/cre-templates/ai-audit-firewall.mdx new file mode 100644 index 00000000000..29e1e65ceba --- /dev/null +++ b/src/content/cre-templates/ai-audit-firewall.mdx @@ -0,0 +1,229 @@ +--- +title: "AI Smart Contract Audit Firewall" +description: "Automatically analyze and screen smart contract interactions before execution to detect and block malicious transactions, while preserving the confidentiality of chain scanner and LLM reasoning API credentials." +author: "Chainlink Labs" +excerpt: "Gate transactions with dual-model AI audits inside a TEE and deliver the verdict onchain." +image: "thumbnail.jpg" +tags: + - "confidential" + - "ai" + - "security" +githubUrl: "https://github.com/smartcontractkit/confidential-compute-examples/tree/main/ai-audit-firewall" +githubRepoLinks: + - label: "TypeScript" + url: "https://github.com/smartcontractkit/confidential-compute-examples/tree/main/ai-audit-firewall" +datePublished: "2026-08-04" +lastModified: "2026-08-04" +--- + +import { Aside, Accordion } from "@components" + +## What This Template Does + +This workflow runs inside a **Trusted Execution Environment (TEE)** and acts as a confidential gate for proposed token interactions. Contract source, transaction details, and model prompts never leave the confidential runtime. + +On every cron execution the workflow: + +1. Fetches a **proposed transaction** +2. Fetches the **token and protocol contract artifacts** from a scanner service +3. Runs **two independent LLM audits** — the second receives the first analysis as prior context +4. Merges the risk flags and decides **ALLOW**, **DENY**, or **MANUAL_REVIEW** +5. Writes an audit log entry and a firewall action +6. Optionally writes the verdict onchain with `EVMClient` + + + +## Risk Flags + +Both models are asked to evaluate the same four checks: + +| Flag | What it detects | +| --------------------- | ------------------------------------------------------------------ | +| `obfuscatedTax` | Hidden or dynamically-adjustable transfer fees | +| `privilegeEscalation` | Owner or admin functions that can seize funds or change core rules | +| `externalCallRisk` | Untrusted external calls and reentrancy surface | +| `logicBomb` | Conditional logic that changes behavior after a trigger is reached | + +## Verdict Logic + +The `determineVerdict` function merges both analyses: + +- **DENY** — any malicious risk flag is set in the merged flag set +- **MANUAL_REVIEW** — either model recommends `review`, either model's confidence is below `0.7`, or the two models disagree +- **ALLOW** — both models agree, both are confident, and no risk flag fired + + + +## Prerequisites + +- **[Bun](https://bun.com/docs/installation)** — the repository is configured as a Bun workspace +- **[Chainlink CRE CLI](https://docs.chain.link/cre/getting-started/cli-installation)** installed and configured +- **Git** for cloning the repository +- **A funded wallet on Ethereum Sepolia** — only if you want to test the optional onchain delivery path + +## Setup + + + +```bash +git clone https://github.com/smartcontractkit/confidential-compute-examples.git +cd confidential-compute-examples +bun install +``` + +`bun install` at the repository root installs dependencies for every workflow because the repo is a Bun workspace. + + + + + +From the repository root: + +```bash +cp .env.example .env +``` + +Set the values you want to use. The mock keys are used by both the workflow and the shared demo server: + +```bash +MOCK_PORT=8787 +MOCK_SCANNER_API_KEY=mock-scanner-key +MOCK_PRIMARY_LLM_API_KEY=mock-primary-llm-key +MOCK_SECONDARY_LLM_API_KEY=mock-secondary-llm-key +``` + +`secrets.yaml` at the repository root maps the logical secret IDs to these environment variables. + + + + + +Open `ai-audit-firewall/config.staging.json`: + +```json +{ + "schedule": "0 */5 * * * *", + "mock_base_url": "http://127.0.0.1:8787/audit-firewall", + "scanner_url": "http://127.0.0.1:8787/audit-firewall/scanner", + "primary_llm_url": "http://127.0.0.1:8787/audit-firewall/v1/analysis/primary", + "secondary_llm_url": "http://127.0.0.1:8787/audit-firewall/v1/analysis/secondary", + "secrets_ids": { + "scanner_api_key_id": "scanner_api_key", + "primary_llm_api_key_id": "primary_llm_api_key", + "secondary_llm_api_key_id": "secondary_llm_api_key" + } +} +``` + +1. Keep the default values if you are using the shared mock server on port `8787` +2. Update `mock_base_url`, `scanner_url`, `primary_llm_url`, and `secondary_llm_url` if you are using a different port or host +3. Keep `secrets_ids` aligned with `secrets.yaml` +4. If you do not want to test onchain delivery yet, remove or clear the `evms` entry + + + + + +```bash +cd ai-audit-firewall +bun run typecheck +bun run test +``` + + + + + +From the repository root: + +```bash +bun run mock:server +``` + +The server listens on `http://127.0.0.1:8787` and serves this workflow's routes under the `/audit-firewall/*` namespace — transaction proposals, contract artifact lookups, the two audit model endpoints, and the logging and action endpoints. + + + + + +In a new terminal, from the repository root: + +```bash +cre workflow simulate ./ai-audit-firewall --target=staging-settings +``` + +The workflow logs each stage (`audit-firewall-onchain-report-start`, `audit-firewall-complete`) and returns a JSON result containing the verdict, reasoning, merged risk flags, both model analyses, the audit log ID, and the firewall action ID. + + + +## Secrets + +`config.staging.json` expects these secret IDs in `secrets_ids`: + +- `scanner_api_key` +- `primary_llm_api_key` +- `secondary_llm_api_key` + +## Optional Onchain Delivery + +The workflow can encode the verdict as a CRE report and write it to a consumer contract. + + + +Deploy `contracts/AuditFirewallConsumer.sol`. It extends `contracts/ReceiverTemplate.sol`, which validates that reports arrive from the Chainlink Forwarder. + +Forwarder mode must match your environment: + +- **Simulation** uses the Mock Forwarder +- **Production** uses the Keystone Forwarder + +Deploy or configure the consumer with the forwarder address that matches the mode you are running. See [Forwarder Addresses](https://docs.chain.link/cre/supported-networks-ts#forwarder-addresses) for the correct address. + + + + + +Set `evms[0]` in your config file: + +```json +"evms": [ + { + "chain_selector_name": "ethereum-testnet-sepolia", + "consumer_address": "0xYourConsumer", + "gas_limit": "500000" + } +] +``` + +1. Set `evms[0].consumer_address` to the deployed consumer address +2. Keep `evms[0].chain_selector_name` aligned with the target network in `project.yaml` +3. Increase `evms[0].gas_limit` if your deployed contract needs more gas + + + + + +## Production Checklist + +1. Replace the example URLs in `config.production.json` with real endpoints +2. Set real secret values for the scanner and both model providers +3. Deploy the consumer contract +4. Update `config.production.json` so `evms[0].consumer_address`, `evms[0].chain_selector_name`, and `evms[0].gas_limit` match the deployed target +5. Confirm the consumer's forwarder address matches your environment + +## Troubleshooting + +- **401 responses from the APIs** usually indicate a secret mismatch between `.env`, `secrets.yaml`, and `secrets_ids` in the config file +- **Simulation failures tied to RPC config** usually come from incorrect `project.yaml` target values +- **Model responses that fail to parse** mean your configured endpoint is not returning the expected JSON payload shape — the workflow expects `riskFlags`, `recommendation`, `confidence`, and `reasoning` +- **Onchain write failures** mean the consumer rejected the report; confirm the forwarder address configured on the contract matches the mode you are simulating or deploying in diff --git a/src/content/cre-templates/automated-liquidation-protection.mdx b/src/content/cre-templates/automated-liquidation-protection.mdx new file mode 100644 index 00000000000..061e5706f7f --- /dev/null +++ b/src/content/cre-templates/automated-liquidation-protection.mdx @@ -0,0 +1,189 @@ +--- +title: "Automated Liquidation Protection" +description: "Automatically protect DeFi lending positions by continuously monitoring liquidation risk and executing collateral management, debt repayment, position reduction, or hedging strategies while preserving the confidentiality of centralized exchange as well as LLM API keys, proprietary risk management thresholds, and execution preferences." +author: "Chainlink Labs" +excerpt: "Run policy-constrained liquidation defense confidentially with CRE and TEE execution." +image: "thumbnail.jpg" +tags: + - "confidential" + - "liquidation" + - "defi" +githubUrl: "https://github.com/smartcontractkit/confidential-compute-examples/tree/main/automated-liquidation-protection" +githubRepoLinks: + - label: "TypeScript" + url: "https://github.com/smartcontractkit/confidential-compute-examples/tree/main/automated-liquidation-protection" +datePublished: "2026-08-04" +lastModified: "2026-08-04" +--- + +import { Aside, Accordion } from "@components" + +## What This Template Does + +This workflow runs inside a **Trusted Execution Environment (TEE)** and generates a policy-constrained defense plan for a leveraged ETH position. Risk data, policy parameters, and model prompts never leave the confidential runtime. + +On every cron execution the workflow: + +1. Fetches the exchange and model API secrets from the CRE secrets store +2. Reads the account **policy** and the current **risk state** (leverage, liquidation proximity, collateral health, reserves) +3. Computes a **risk score** from the risk state and policy thresholds +4. Asks an LLM for a set of **defensive actions** +5. Enforces reserve, slippage, and sequencing constraints on the proposed actions +6. Executes the approved actions through an execution endpoint + +If the position is healthy or no action survives the policy filter, the workflow returns `SAFE` without executing anything. + + + +## Defensive Actions + +The LLM may propose any of the following action types. Each one is validated against the policy before it becomes executable: + +| Action | Description | +| --------------------------- | -------------------------------------------------------- | +| `add_collateral` | Post additional collateral from reserves | +| `bridge_and_add_collateral` | Bridge funds from another chain, then post as collateral | +| `reallocate_collateral` | Move collateral between positions or venues | +| `reduce_position` | Partially deleverage the position | +| `close_position` | Fully exit the position | +| `hedge_short_perp` | Open an offsetting short perpetual | + +## Policy Constraints + +The policy is fetched at runtime and bounds everything the model is allowed to do: + +- `max_reserve_deployment_usdc` — ceiling on capital deployed in a single cycle +- `min_reserve_balance_usdc` — reserve floor that must remain untouched +- `max_acceptable_leverage` — leverage target used in risk scoring +- `incremental_deleveraging_limit_pct` — cap on how much of the position can be reduced per cycle +- `liquidation_warning_action_threshold` — proximity threshold that triggers a defense +- `allow_leverage_reduction` — whether deleveraging actions are permitted at all +- `execution_sequence_preference` — `collateral-first`, `deleverage-first`, or `hedge-first` +- `preferred_venues` — venue allowlist used when routing each action + + + +## Prerequisites + +- **[Bun](https://bun.com/docs/installation)** — the repository is configured as a Bun workspace +- **[Chainlink CRE CLI](https://docs.chain.link/cre/getting-started/cli-installation)** installed and configured +- **Git** for cloning the repository + +## Setup + + + +```bash +git clone https://github.com/smartcontractkit/confidential-compute-examples.git +cd confidential-compute-examples +bun install +``` + +`bun install` at the repository root installs dependencies for every workflow because the repo is a Bun workspace. + + + + + +From the repository root: + +```bash +cp .env.example .env +``` + +Set the values you want to use. The mock keys are used by both the workflow and the shared demo server: + +```bash +MOCK_PORT=8787 +MOCK_EXCHANGE_API_KEY=mock-exchange-key +MOCK_OPENAI_API_KEY=mock-openai-key +``` + +`secrets.yaml` at the repository root maps the logical secret IDs to these environment variables. + + + + + +Open `automated-liquidation-protection/config.staging.json`: + +```json +{ + "schedule": "0 */5 * * * *", + "mock_base_url": "http://127.0.0.1:8787/liquidation", + "openai_url": "http://127.0.0.1:8787/liquidation/v1/responses", + "openai_model": "gpt-4.1-mini", + "secrets_ids": { + "exchange_api_key_id": "exchange_api_key", + "openai_api_key_id": "openai_api_key" + } +} +``` + +1. Keep the default values if you are using the shared mock server on port `8787` +2. Update `mock_base_url` and `openai_url` if you are using a different port or host +3. Keep `secrets_ids` aligned with `secrets.yaml` + + + + + +```bash +cd automated-liquidation-protection +bun run typecheck +bun run test +``` + + + + + +From the repository root: + +```bash +bun run mock:server +``` + +The server listens on `http://127.0.0.1:8787` and serves this workflow's routes under the `/liquidation/*` namespace — policy, risk state, model responses, and the execution endpoint. + + + + + +In a new terminal, from the repository root: + +```bash +cre workflow simulate ./automated-liquidation-protection --target=staging-settings +``` + +The workflow logs each stage (`liquidation-getsecret-ok`, `liquidation-defense-executed`) and returns either `SAFE` or a JSON summary with the status, action count, risk score, and execution ID. + + + +## Secrets + +`config.staging.json` expects these secret IDs in `secrets_ids`: + +- `exchange_api_key` +- `openai_api_key` + +## Production Checklist + +1. Replace `mock_base_url` with your real risk, policy, and execution service URL +2. Use a production model endpoint and model in `openai_url` and `openai_model` +3. Confirm `config.production.json` points to the correct service base URL before deployment +4. Register production secret values for exchange and model access + +## Troubleshooting + +- **401 responses from the APIs** usually indicate a secret mismatch between `.env`, `secrets.yaml`, and `secrets_ids` in the config file +- **Simulation failures tied to RPC config** usually come from incorrect `project.yaml` target values +- **Model responses that fail to parse** mean your configured endpoint is not returning the expected JSON payload shape — the workflow expects `shouldDefend`, `reasoning`, and `actions` diff --git a/src/content/cre-templates/automated-portfolio-rebalancing.mdx b/src/content/cre-templates/automated-portfolio-rebalancing.mdx new file mode 100644 index 00000000000..9148db1d693 --- /dev/null +++ b/src/content/cre-templates/automated-portfolio-rebalancing.mdx @@ -0,0 +1,175 @@ +--- +title: "Automated Portfolio Rebalancing" +description: "Automatically rebalance crypto portfolios by continuously monitoring allocation drift and executing portfolio adjustments when predefined thresholds are exceeded, while preserving the confidentiality of exchange API keys, LLM reasoning, portfolio allocation thresholds, and execution preferences." +author: "Chainlink Labs" +excerpt: "Rebalance a portfolio confidentially with policy-constrained, LLM-assisted trade execution." +image: "thumbnail.jpg" +tags: + - "confidential" + - "rebalancing" + - "defi" +githubUrl: "https://github.com/smartcontractkit/confidential-compute-examples/tree/main/automated-portfolio-rebalancing" +githubRepoLinks: + - label: "TypeScript" + url: "https://github.com/smartcontractkit/confidential-compute-examples/tree/main/automated-portfolio-rebalancing" +datePublished: "2026-08-04" +lastModified: "2026-08-04" +--- + +import { Aside, Accordion } from "@components" + +## What This Template Does + +This workflow runs inside a **Trusted Execution Environment (TEE)** and generates policy-constrained rebalance trades when allocation drift exceeds the configured threshold. Holdings, prices, and target allocations never leave the confidential runtime. + +On every cron execution the workflow: + +1. Fetches the exchange and model API secrets from the CRE secrets store +2. Reads **policy**, **holdings**, **prices**, and a **volatility index** +3. Computes per-asset **allocation drift** against the target weights +4. Asks an LLM for **trade proposals** +5. Enforces slippage, reserve-floor, and max-trade-size constraints +6. Chunks oversized trades and routes each chunk to a preferred venue +7. Executes the approved trade plan through an execution endpoint + +If no asset has drifted past the threshold, the workflow returns without trading. + + + +## Policy Constraints + +The policy is fetched at runtime and bounds every trade the model is allowed to propose: + +- `target_allocations` — target weight per symbol +- `drift_threshold_pct` — minimum drift required before rebalancing runs at all +- `max_trade_usd` — maximum notional per trade; larger trades are split into chunks +- `reserve_floor_usdc` — USDC reserve that must remain untouched +- `max_slippage_bps` — slippage ceiling applied to every trade +- `preferred_venues` — venue allowlist used when routing each chunk + + + +## Prerequisites + +- **[Bun](https://bun.com/docs/installation)** — the repository is configured as a Bun workspace +- **[Chainlink CRE CLI](https://docs.chain.link/cre/getting-started/cli-installation)** installed and configured +- **Git** for cloning the repository + +## Setup + + + +```bash +git clone https://github.com/smartcontractkit/confidential-compute-examples.git +cd confidential-compute-examples +bun install +``` + +`bun install` at the repository root installs dependencies for every workflow because the repo is a Bun workspace. + + + + + +From the repository root: + +```bash +cp .env.example .env +``` + +Set the values you want to use. The mock keys are used by both the workflow and the shared demo server: + +```bash +MOCK_PORT=8787 +MOCK_EXCHANGE_API_KEY=mock-exchange-key +MOCK_OPENAI_API_KEY=mock-openai-key +``` + +`secrets.yaml` at the repository root maps the logical secret IDs to these environment variables. + + + + + +Open `automated-portfolio-rebalancing/config.staging.json`: + +```json +{ + "schedule": "0 */5 * * * *", + "mock_base_url": "http://127.0.0.1:8787/rebalancing", + "openai_url": "http://127.0.0.1:8787/rebalancing/v1/responses", + "openai_model": "gpt-4.1-mini", + "secrets_ids": { + "exchange_api_key_id": "exchange_api_key", + "openai_api_key_id": "openai_api_key" + } +} +``` + +1. Keep the default values if you are using the shared mock server on port `8787` +2. Update `mock_base_url` and `openai_url` if you are using a different port or host +3. Keep `secrets_ids` aligned with `secrets.yaml` + + + + + +```bash +cd automated-portfolio-rebalancing +bun run typecheck +bun run test +``` + + + + + +From the repository root: + +```bash +bun run mock:server +``` + +The server listens on `http://127.0.0.1:8787` and serves this workflow's routes under the `/rebalancing/*` namespace — portfolio, prices, volatility, policy, model responses, and the execution endpoint. + + + + + +In a new terminal, from the repository root: + +```bash +cre workflow simulate ./automated-portfolio-rebalancing --target=staging-settings +``` + +The workflow logs each stage (`rebalance-executed`) and returns a JSON summary with the status, trade count, maximum drift percentage, and execution ID. + + + +## Secrets + +`config.staging.json` expects these secret IDs in `secrets_ids`: + +- `exchange_api_key` +- `openai_api_key` + +## Production Checklist + +1. Replace `mock_base_url` with your real policy, market, and execution service URL +2. Use a production model endpoint and model in `openai_url` and `openai_model` +3. Confirm `config.production.json` points to the correct service base URL before deployment +4. Register production secret values for exchange and model access + +## Troubleshooting + +- **401 responses from the APIs** usually indicate a secret mismatch between `.env`, `secrets.yaml`, and `secrets_ids` in the config file +- **Simulation failures tied to RPC config** usually come from incorrect `project.yaml` target values +- **Model responses that fail to parse** mean your configured endpoint is not returning the expected JSON payload shape — the workflow expects `shouldRebalance`, `reasoning`, and `trades` diff --git a/src/content/cre-templates/hello-confidential-workflows.mdx b/src/content/cre-templates/hello-confidential-workflows.mdx new file mode 100644 index 00000000000..8146fbd5dc2 --- /dev/null +++ b/src/content/cre-templates/hello-confidential-workflows.mdx @@ -0,0 +1,259 @@ +--- +title: "Hello Confidential Workflows" +description: "Quickstart confidential workflow that registers a TEE handler, securely fetches a secret inside the enclave, executes a capability call from within the enclave, and returns to the DON for any operations requiring decentralized consensus." +author: "Chainlink Labs" +excerpt: "Learn the minimal end-to-end shape of a CRE Confidential Workflow with TEE execution." +image: "thumbnail.jpg" +cliTemplateIds: + - label: "TypeScript" + id: "hello-confidential-workflows-ts" +tags: + - "confidential" + - "tee" + - "secrets" +githubUrl: "https://github.com/smartcontractkit/cre-templates/tree/main/starter-templates/hello-confidential-workflows" +githubRepoLinks: + - label: "TypeScript" + url: "https://github.com/smartcontractkit/cre-templates/tree/main/starter-templates/hello-confidential-workflows/hello-confidential-workflows-ts" +datePublished: "2026-08-04" +lastModified: "2026-08-04" +--- + +import { Aside, Accordion } from "@components" + + + +## What This Template Does + +By default, a CRE workflow's callback runs on Workflow DON nodes, where node operators can in principle inspect what it is computing. That's fine for most workflows — but some logic is sensitive on its own: a risk threshold, a rebalancing policy, a proprietary scoring model. Leaking the policy can be as damaging as leaking a credential. + +A **[Confidential Workflow](https://docs.chain.link/cre/concepts/confidential-workflows)** moves that part into a hardware-isolated [enclave](https://docs.chain.link/cre/key-terms#enclave). This template is the minimal end-to-end shape of one, in four steps: + +| Step | What it demonstrates | API | +| ---- | ---------------------------------------------------- | ----------------------------------------- | +| 1 | Register a handler that runs inside a TEE | `cre.handlerInTee(trigger, fn, tees)` | +| 2 | Fetch a secret inside the enclave | `runtime.getSecret({ id })` | +| 3 | Make a capability call from inside the enclave | `HTTPClient.sendRequest(teeRuntime, req)` | +| 4 | Cross back to the DON for anything needing consensus | `runtime.usingTheDons()` | + +## Architecture + +```text +┌──────────────┐ +│ CronTrigger │ fires on schedule (runs on the Workflow DON) +└──────┬───────┘ + │ DON hands the triggered request to an enclave + v +╔══════════════════════════════════════════════════════════════╗ +║ ENCLAVE (TEE — hidden from node operators) ║ +║ ║ +║ Step 2: runtime.getSecret({ id: 'API_TOKEN' }) ║ +║ ▲ ║ +║ └──── released by Vault DON, decrypted in-enclave║ +║ ║ +║ Step 3: HTTPClient.sendRequest(runtime, { ... }) ║ +║ Authorization: Bearer ║ +║ ▲ trust from enclave attestation, not consensus ║ +║ ║ +║ Confidential logic: score(response) vs. scoreThreshold ║ +║ -> verdict = APPROVE | REJECT ║ +╚═══════════════════════════╤══════════════════════════════════╝ + │ Step 4: runtime.usingTheDons() + │ ONLY the verdict + score cross out + v +┌──────────────────────────────────────────────────────────────┐ +│ WORKFLOW DON — donRuntime.report({ ... }) │ +│ BFT consensus verifies the enclave attestation, then signs │ +└──────────────────────────────────────────────────────────────┘ +``` + +## How It Works + +`my-workflow/workflow.ts`: + +1. **Registers the cron handler with `cre.handlerInTee`**, constrained to `[{ tee: 'nitro', regions: ['us-west-2'] }]` +2. **Fetches `API_TOKEN`** with `runtime.getSecret()` — the Vault DON releases it only into an attested enclave, and it is decrypted at the moment the call runs +3. **Calls the configured URL** with `HTTPClient.sendRequest(runtime, ...)`, passing the `TeeRuntime` so the request executes from inside the enclave with the secret in the `Authorization` header +4. **Scores the response** against `scoreThreshold` — this stands in for your proprietary logic, and is the part that stays invisible to node operators +5. **Crosses back with `usingTheDons()`** and generates a signed report containing only the verdict and score — never the secret or the raw response + +The default endpoint is `https://postman-echo.com/headers`, which echoes the request headers back — no signup or real API key needed. The workflow uses that to confirm the secret really was injected inside the enclave, reporting it as the boolean `secret reached API: true` rather than by logging the token. It never logs the response body either; the confidentiality boundary is the reason, and it's worth keeping that habit even in simulation. + + + +## Use Cases + +- **Automated liquidation protection** — keep risk thresholds and the defensive strategy off Workflow DON nodes so they can't be predicted and front-run +- **Portfolio rebalancing** — hide the allocation policy and trade-sizing logic so the rebalance isn't anticipated +- **LLM audit firewall** — keep evaluation criteria and third-party API credentials inside the enclave +- **Payment orchestration** — keep routing logic and account details confidential +- **Proprietary scoring** — compute over licensed or sensitive data without exposing the data or the model + +## Prerequisites + +- **[Bun](https://bun.sh/)** runtime installed +- **[Chainlink CRE CLI](https://docs.chain.link/cre/getting-started/cli-installation)** installed and configured +- **Enrollment in the Confidential Workflows private beta** — required to deploy, not to simulate + +## Getting Started + + + +```bash +cd my-workflow && bun install && cd .. +``` + + + + + +```bash +cp .env.example .env +``` + +Set `SECRET_API_TOKEN` in `.env`. `secrets.yaml` maps the workflow-facing secret ID `API_TOKEN` to that environment variable: + +```yaml +secretsNames: + API_TOKEN: + - SECRET_API_TOKEN +``` + +With the default echo endpoint, any non-empty value works. + + + + + +```bash +cd my-workflow && bun test +``` + + + + + +```bash +cre workflow simulate my-workflow --target staging-settings --non-interactive --trigger-index 0 +``` + +Expected output: + +```text +[SIMULATION] Running trigger trigger=cron-trigger@1.0.0 +╭────────────────────────────────────────────────────────────────────────────────────────────────────╮ +│ Trigger requested TEE Execution your trigger will run in one of the following Tees: │ +│ - AWS Nitro in us-west-2 │ +│ The simulator is not a real TEE, and is meant to debug. │ +│ Do not use it for sensitive information. │ +│ During real execution, user logs for this trigger will not be visible, and will not leave the TEE. │ +│ They are presented in the simulator for debugging only. │ +╰────────────────────────────────────────────────────────────────────────────────────────────────────╯ + +[USER LOG] Enclave computation complete. verdict=REJECT + +✓ Workflow Simulation Result: +"REJECT (score: 371, secret reached API: true)" +``` + +Three things to notice: + +- The simulator confirms the TEE constraint it resolved (`AWS Nitro in us-west-2`) and warns that **it is not a real enclave** — logs are shown for debugging only. In real execution those logs never leave the TEE. +- `secret reached API: true` means the Vault DON secret was fetched inside the enclave and arrived in the outbound request's `Authorization` header. +- The verdict flips between `APPROVE` and `REJECT` from run to run. That's expected: the score is derived from the live response body, and the echo endpoint includes a per-request trace ID. Lower `scoreThreshold` to see `APPROVE` consistently. + + + +## Configuration + +`my-workflow/config.staging.json`: + +| Field | Description | +| ---------------- | ----------------------------------------------------------------------- | +| `schedule` | Cron expression (6 fields, seconds first) | +| `url` | Endpoint called from inside the enclave | +| `secretId` | Secret ID fetched with `runtime.getSecret()`; must match `secrets.yaml` | +| `scoreThreshold` | Threshold the confidential scoring compares against | + +## TEE Constraints + +The third argument to `handlerInTee` declares which enclaves the handler accepts: + +```ts +{ +} // any registered TEE, any region +{ + regions: ["us-west-2"] +} // any TEE, restricted to a region +;[{ tee: "nitro", regions: ["us-west-2"] }] // specific TEE types and regions +``` + +AWS Nitro in `us-west-2` is currently the only registered TEE type and region. This is an actively evolving alpha API — check your installed SDK version if you expect otherwise. + +## Confidentiality Boundary + +Understanding what is and isn't protected matters more here than in a regular workflow. + +| Protected by default | **Not** automatically protected | +| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | +| Secrets the Vault DON releases into the enclave | Triggers, chain reads, and chain writes — these always run on Workflow DON nodes | +| Sensitive inputs and intermediate values you don't share outside the enclave | Your workflow's **source code and deployed binary** | +| Capability calls made from inside the enclave | Capability calls not routed through the enclave | +| Enclave execution memory, while your computation runs | Reports, calldata, and any output you deliver outside the enclave | + +Consequences worth internalizing: + +- **Your source and binary are readable.** If the logic itself is the secret, make sure it actually _executes_ inside the enclave — don't rely on the binary being opaque, because it isn't. +- **`usingTheDons()` is a one-way door.** Anything you pass into a capability call on that runtime executes on Workflow DON nodes like any non-confidential call. Cross over only what doesn't need to stay hidden. +- **Don't log from inside the enclave in production.** Logs leave the confidentiality boundary. This template logs only the verdict, and the comment marks it for removal before deploying. +- **Keep enclave logic deterministic.** The enclave result is attested and verified by DON consensus. +- **Enclaves are not tenant-isolated today.** A single enclave can run confidential workflows from multiple customers concurrently, sharing execution memory. Isolation between confidential executions is planned, not part of the current beta. + +## Which Secrets Belong in an Enclave? + +Not every secret needs enclave-level protection. + +**Higher value — consider enclave execution:** wallet and CA private keys; exchange, custody, payment-processor, banking, or LLM-provider credentials; OAuth client secrets, JWT signing keys, KMS keys; payment data, health data, other PII. + +**Lower value — regular DON execution is usually fine:** API keys for publicly available data (weather, explorers, public price feeds, public RPCs); public wallet addresses. + +The common thread: a secret belongs in the enclave if disclosure would expose more than the workflow needs. + +## Customization + +- **Put your real logic in the enclave** — replace `scoreResponse` in `workflow.ts` with the policy, threshold, or model you need to keep private +- **Deliver the report onchain** — pass the report from Step 4 to `evmClient.writeReport(donRuntime, report)`; the RPCs in `project.yaml` are already set up for Sepolia. See the [Keeper Bot](/cre-templates/keeper-bot) or [Event Reactor](/cre-templates/event-reactor) templates for the full write path +- **Change the trigger** — `handlerInTee` accepts any CRE trigger, same as `handler`; swap cron for a log trigger to react to onchain events confidentially +- **Fetch more secrets** — call `runtime.getSecret()` once per secret; the TypeScript `SecretsProvider` has no batch variant + +## Security + +- Never commit `.env` files or secrets — `.gitignore` covers `*.env` +- Remove or gate every `runtime.log()` inside the TEE handler before deploying +- Audit what crosses `usingTheDons()`; that data is no longer confidential + +## Further Reading + +- [Confidential Workflows in CRE](https://docs.chain.link/cre/concepts/confidential-workflows) — concepts and use cases +- [Making a Workflow Confidential](https://docs.chain.link/cre/guides/workflow/using-confidential-workflows) — step-by-step guide +- [Confidential Workflows Client SDK Reference](https://docs.chain.link/cre/reference/sdk/confidential-workflows-client) — full API +- [Confidential HTTP](https://docs.chain.link/cre/capabilities/confidential-http) — for a single outbound request, without a full confidential handler +- [confidential-compute-examples](https://github.com/smartcontractkit/confidential-compute-examples) — production-shaped reference workflows + +